CAR Import (DAG Import)

Importe DAGs completos de IPFS en una sola solicitud utilizando archivos CAR (Content Addressable aRchive). Sus CIDs se conservan exactamente — sin re-fragmentación ni re-hashing.

¿Qué es un archivo CAR?

Un archivo CAR empaqueta un árbol de directorios IPFS completo o un DAG en un único archivo portátil. Cada bloque se almacena con su CID original, por lo que el servicio importa todo tal cual. Esto significa:

• Conservación de CID — calcule los CIDs localmente, verifique que el servicio devuelve exactamente el mismo CID
• Carga por lotes — suba cientos de archivos en una sola solicitud en lugar de uno por uno
• Migración de proveedor — exporte un DAG de otro proveedor, impórtelo a IPFS Ninja con CIDs idénticos
• DAGs personalizados — suba cualquier estructura de datos IPLD directamente

REST API

POST /upload/new

El mismo endpoint que las cargas regulares — añada car: true para indicar una importación CAR.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
content	string	Sí	Archivo CAR codificado en Base64
car	boolean	Sí	Establezca en true para habilitar la importación CAR
description	string	No	Descripción breve de la importación
folderId	string	No	ID de carpeta para organizar el contenido importado
metadata	object	No	Pares clave-valor personalizados (mismas reglas que las cargas regulares)

Ejemplo: Importar un archivo CAR con curl

Paso 1: Cree un archivo CAR a partir de un directorio local usando ipfs-car:

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

Paso 2: Suba el archivo 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\"
  }"

Ejemplo: Importar un archivo CAR con 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);

Ejemplo: Importar un archivo CAR con 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"])

Respuesta 200 OK

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

API compatible con S3

Use la cabecera x-amz-meta-import: car en una solicitud PutObject para importar un archivo CAR a través del S3 API.

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" }   // ← activa la importación CAR
}));

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

MCP Server

La herramienta ipfs_import_car está disponible en el 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...

Creación de archivos CAR

Desde un directorio (recomendado)

Use la herramienta CLI ipfs-car:

# Instalar
npm install -g ipfs-car

# Empaquetar un directorio en un archivo CAR
ipfs-car pack ./my-directory -o my-archive.car

# Verificar el root CID antes de subir
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Desde un nodo IPFS en ejecución

Exporte cualquier CID como archivo CAR usando el Kubo CLI:

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

Programáticamente con JavaScript

Use la 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";

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

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

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

Verificación de integridad de CID

El beneficio principal de la importación CAR es la conservación de CID. Puede verificar que el root CID coincide antes y después de la carga:

# 1. Empaquetar directorio y anotar el root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Subir a 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"
# ✓ Los CIDs coinciden — el contenido se importó exactamente como se construyó localmente

Migración desde otro proveedor

Desde Pinata

# Exportar desde Pinata usando el gateway IPFS
ipfs dag export QmYourCID > export.car

# Importar a 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}"

Desde Filebase

# Filebase soporta exportación CAR a través de su S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Importar a 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}"

Límites

Límite	Valor
Tamaño máximo de archivo CAR	100 MB
Máximo root único	Debe tener al menos un root CID
Formato CAR	CARv1 (universalmente soportado)
Disponibilidad	Todos los planes (Dharma, Bodhi, Nirvana)

Se aplican los límites de almacenamiento y cantidad de archivos de su plan. El DAG importado cuenta como una entrada de archivo, y el tamaño del archivo CAR se deduce de su cuota de almacenamiento.

Solución de problemas

"invalid CAR file: too small"

El contenido subido tiene menos de 40 bytes, lo cual es demasiado pequeño para ser un archivo CAR válido. Asegúrese de enviar el contenido CAR completo codificado en base64.

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

El archivo CAR decodificado excede los 100 MB. Divida su contenido en varios archivos CAR más pequeños usando el paquete carbites, o suba los archivos individualmente.

"dag/import did not return a root CID"

El nodo IPFS no pudo procesar el archivo CAR. Verifique que el archivo sea un archivo CARv1 válido:

ipfs-car roots my-archive.car

Si este comando falla, el archivo CAR está malformado. Regenere con ipfs-car pack o ipfs dag export.

"not enough storage"

Se ha alcanzado el límite de almacenamiento de su plan. Elimine archivos no utilizados o actualice su plan en ipfs.ninja/pricing.