CAR Import (DAG Import)

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

O que é um ficheiro CAR?

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

• Preservação de CID — calcule os CIDs localmente, verifique que o serviço devolve exatamente o mesmo CID
• Upload em lote — envie centenas de ficheiros num único pedido em vez de um a um
• Migração de fornecedor — exporte um DAG de outro fornecedor, importe para o IPFS Ninja com CIDs idênticos
• DAGs personalizados — envie qualquer estrutura de dados IPLD diretamente

REST API

POST /upload/new

Mesmo endpoint que uploads regulares — adicione 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	Defina como true para ativar a importação CAR
description	string	Não	Breve descrição 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 uploads regulares)

Exemplo: Importar um ficheiro CAR com curl

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

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

Passo 2: Envie 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,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

S3-Compatible API

Utilize 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);

MCP Server

A ferramenta ipfs_import_car está disponível no MCP Server (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)

Utilize a ferramenta CLI 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

Exporte qualquer CID como ficheiro CAR utilizando o CLI do Kubo:

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

Programaticamente com JavaScript

Utilize 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. Pode verificar que o CID raiz é o mesmo antes e depois do upload:

# 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	Deve ter pelo menos um CID raiz
Formato CAR	CARv1 (universalmente suportado)
Disponibilidade	Todos os planos (Dharma, Bodhi, Nirvana)

Os limites de armazenamento e contagem de ficheiros do seu plano aplicam-se. O DAG importado conta como uma entrada de ficheiro, e o tamanho do ficheiro CAR é deduzido da sua quota de armazenamento.

Resolução de Problemas

"invalid CAR file: too small"

O conteúdo enviado tem menos de 40 bytes, o que é demasiado pequeno para ser um ficheiro CAR válido. Certifique-se de que está 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. Divida o seu conteúdo em vários ficheiros CAR mais pequenos utilizando o pacote carbites, ou envie os ficheiros individualmente.

"dag/import did not return a root CID"

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

ipfs-car roots my-archive.car

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

"not enough storage"

O limite de armazenamento do seu plano foi atingido. Elimine ficheiros não utilizados ou faça upgrade do seu plano em ipfs.ninja/pricing.