Importação CAR (Importação de DAG)

Importa DAGs IPFS completos num único pedido utilizando ficheiros CAR (Content Addressable aRchive). Os teus CIDs são preservados exatamente — sem re-chunking nem re-hashing.

O que é um ficheiro CAR?

Um ficheiro CAR empacota uma árvore de diretório IPFS inteira ou um DAG num único arquivo portátil. Cada bloco é guardado com o seu CID original, pelo que o serviço importa tudo tal como está. Isto significa:

• Preservação de CID — calcula os CIDs localmente, verifica que o serviço devolve exatamente o mesmo CID
• Carregamento em lote — carrega centenas de ficheiros num único pedido em vez de um a um
• Migração entre fornecedores — exporta um DAG de outro fornecedor, importa para o IPFS Ninja com CIDs idênticos
• DAGs personalizados — carrega qualquer estrutura de dados IPLD diretamente

Carregamento pelo Painel

Dois percursos de arrastar e largar em /upload usam este mesmo fluxo de importação — sem necessidade de código:

• Larga um ficheiro .car. A zona de carregamento deteta automaticamente a extensão, mostra um aviso "CAR archive detected", e o botão de envio passa a "Import <filename> as CAR". O próprio CID raiz do arquivo é preservado.
• Larga uma pasta. O painel agrupa a pasta num DAG UnixFS no teu browser (usando ipfs-unixfs-importer com o chunker moderno de 1 MiB segundo IPIP-0499) e carrega o CAR resultante pelo mesmo percurso. O CID raiz é um diretório bafybei… que resolve em /ipfs/{cid}/{subpath}.

Ambos usam o fluxo de PUT pré-assinado para qualquer coisa acima de alguns MB — o limite de tamanho de ficheiro é 5 GB por CAR.

API REST

POST /upload/new

Mesmo endpoint que os carregamentos normais — acrescenta car: true para sinalizar uma importação CAR.

Corpo do pedido

Parâmetro	Tipo	Obrigatório	Descrição
content	string	Sim	Ficheiro CAR codificado em base64
car	boolean	Sim	Define como true para ativar a importação CAR
description	string	Não	Descrição curta da importação
folderId	string	Não	ID da pasta para organizar o conteúdo importado
metadata	object	Não	Pares chave-valor personalizados (mesmas regras dos carregamentos normais)

Exemplo: importar um ficheiro CAR com curl

Passo 1: Cria um ficheiro CAR a partir de um diretório local usando ipfs-car:

npx ipfs-car pack ./my-directory -o my-archive.car

Passo 2: Carrega o ficheiro CAR:

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"$(base64 -w0 my-archive.car)\",
    \"car\": true,
    \"description\": \"My directory import\"
  }"

Exemplo: importar um ficheiro CAR com JavaScript

import fs from "fs";

const carBuffer = fs.readFileSync("my-archive.car");
const base64Content = carBuffer.toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: base64Content,
    car: true,
    description: "My directory import"
  })
});

const result = await response.json();
console.log("Root CID:", result.cid);
console.log("Gateway:", result.uris.url);

Exemplo: importar um ficheiro CAR com Python

import requests
import base64

with open("my-archive.car", "rb") as f:
    car_content = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.ipfs.ninja/upload/new",
    headers={
        "X-Api-Key": "bws_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "content": car_content,
        "car": True,
        "description": "My directory import"
    }
)

result = response.json()
print("Root CID:", result["cid"])
print("Gateway:", result["uris"]["url"])

Resposta 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 4.2,
  "car": true,
  "fileCount": 12,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Como funciona a contagem de ficheiros

Cada ficheiro dentro do CAR conta individualmente para o limite de ficheiros do teu plano. Um CAR com 12 ficheiros usa 13 vagas (12 filhos + 1 entrada raiz do CAR). Um CAR de um único ficheiro conta como 1 vaga.

• O armazenamento é cobrado uma vez, na entrada raiz do CAR (o tamanho completo do ficheiro CAR)
• Os ficheiros filhos individuais aparecem na tua listagem de ficheiros com o CID raiz nos seus metadados (carParentCid), para que os possas agrupar
• Máximo de 1000 ficheiros por importação CAR — DAGs maiores têm de ser divididos em várias importações

Se importar o CAR exceder a contagem de ficheiros do teu plano, o pedido é rejeitado com um erro 402 e o conteúdo é desfixado automaticamente:

{
  "error": "file limit exceeded: this CAR contains 523 files, you have 800/1000. Upgrade your plan."
}

API Compatível com S3

Utiliza o cabeçalho x-amz-meta-import: car num pedido PutObject para importar um ficheiro CAR através da API S3.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-archive.car",
  Body: fs.readFileSync("my-archive.car"),
  ContentType: "application/vnd.ipld.car",
  Metadata: { import: "car" }   // ← aciona a importação CAR
}));

console.log("Root CID:", result.ETag);

Servidor MCP

A ferramenta ipfs_import_car está disponível no Servidor MCP (v1.3.0+):

You: Import my-archive.car to IPFS
Claude: [calls ipfs_import_car with base64 content]
     → Root CID: bafybeig... — https://ipfs.ninja/ipfs/bafybeig...

Criar Ficheiros CAR

A partir de um diretório (recomendado)

Utiliza a ferramenta de linha de comandos ipfs-car:

# Install
npm install -g ipfs-car

# Pack a directory into a CAR file
ipfs-car pack ./my-directory -o my-archive.car

# Check the root CID before uploading
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

A partir de um nó IPFS em execução

Exporta qualquer CID como ficheiro CAR usando o CLI do Kubo:

ipfs dag export QmXyz... > my-archive.car

Programaticamente com JavaScript

Utiliza a biblioteca @ipld/car:

import { CarWriter } from "@ipld/car";
import { CID } from "multiformats/cid";
import * as raw from "multiformats/codecs/raw";
import { sha256 } from "multiformats/hashes/sha2";

// Create blocks
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// Write CAR
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// Collect output
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Verificar a Integridade do CID

O principal benefício da importação CAR é a preservação do CID. Podes verificar que o CID raiz corresponde antes e depois do carregamento:

# 1. Pack directory and note the root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Upload to IPFS Ninja
curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 collection.car)\", \"car\": true}" \
  | jq .cid
# "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
# ✓ CIDs match — content imported exactly as built locally

Migrar de Outro Fornecedor

Do Pinata

# Export from Pinata using IPFS gateway
ipfs dag export QmYourCID > export.car

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Do Filebase

# Filebase supports CAR export via their S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Limites

Limite	Valor
Tamanho máximo do ficheiro CAR	100 MB
Raiz única máxima	Tem de haver pelo menos um CID raiz
Formato CAR	CARv1 (universalmente suportado)
Disponibilidade	Todos os planos (Dharma, Bodhi, Nirvana)

Aplicam-se os limites de armazenamento e de contagem de ficheiros do teu plano. O DAG importado conta como uma entrada de ficheiro, e o tamanho do ficheiro CAR é deduzido da tua quota de armazenamento.

Resolução de Problemas

"invalid CAR file: too small"

O conteúdo carregado tem menos de 40 bytes, o que é demasiado pequeno para ser um ficheiro CAR válido. Confirma que estás a enviar o conteúdo CAR completo codificado em base64.

"File too large. Maximum upload size is 100 MB."

O ficheiro CAR descodificado excede 100 MB. Divide o teu conteúdo em vários ficheiros CAR mais pequenos usando o pacote carbites, ou carrega os ficheiros individualmente.

"dag/import did not return a root CID"

O nó IPFS não conseguiu processar o ficheiro CAR. Verifica se o ficheiro é um arquivo CARv1 válido:

ipfs-car roots my-archive.car

Se este comando falhar, o ficheiro CAR está malformado. Volta a gerá-lo com ipfs-car pack ou ipfs dag export.

"not enough storage"

O limite de armazenamento do teu plano foi atingido. Elimina ficheiros não utilizados ou faz upgrade do teu plano em ipfs.ninja/pricing.