CAR Import (DAG Import)

Importeu DAG sencers d'IPFS en una sola sol·licitud utilitzant fitxers CAR (Content Addressable aRchive). Els vostres CID es preserven exactament — sense re-fragmentació ni re-hashing.

Puja un fitxer CAR a IPFS Ninja

Un fitxer CAR empaqueta un arbre de directoris IPFS complet o un DAG en un sol arxiu portable. Cada bloc s'emmagatzema amb el seu CID original, de manera que el servei ho importa tot tal com és. Això significa:

• Preservació de CID — calculeu els CID localment, verifiqueu que el servei retorna exactament el mateix CID
• Càrrega per lots — carregueu centenars de fitxers en una sola sol·licitud en lloc d'un per un
• Migració de proveïdor — exporteu un DAG d'un altre proveïdor, importeu-lo a IPFS Ninja amb CID idèntics
• DAG personalitzats — carregueu qualsevol estructura de dades IPLD directament

Pujada des del tauler de control

Dos camins d'arrossegar i deixar anar a /upload fan servir aquest mateix flux d'importació — sense necessitat de codi:

• Deixeu anar un fitxer .car. La zona de pujada detecta automàticament l'extensió, mostra un rètol "CAR archive detected" i el botó d'enviament es converteix en "Import <filename> as CAR". El CID arrel propi de l'arxiu es preserva.
• Deixeu anar una carpeta. El tauler de control empaqueta la carpeta en un DAG UnixFS al vostre navegador (utilitzant ipfs-unixfs-importer amb el fragmentador modern d'1 MiB segons IPIP-0499) i puja el CAR resultant pel mateix camí. El CID arrel és un directori bafybei… que es resol a /ipfs/{cid}/{subpath}.

Ambdós utilitzen el flux de PUT prefirmat per a qualsevol cosa per sobre d'uns pocs MB — el límit de mida de fitxer és 5 GB per CAR.

REST API

POST /upload/new

El mateix endpoint que les càrregues normals — afegiu car: true per indicar una importació CAR.

Cos de la sol·licitud

Paràmetre	Tipus	Obligatori	Descripció
content	string	Sí	Fitxer CAR codificat en Base64
car	boolean	Sí	Establiu a true per activar la importació CAR
description	string	No	Breu descripció de la importació
folderId	string	No	ID de carpeta per organitzar el contingut importat
metadata	object	No	Parells clau-valor personalitzats (mateixes regles que les càrregues normals)

Exemple: Importar un fitxer CAR amb curl

Pas 1: Creeu un fitxer CAR a partir d'un directori local amb ipfs-car:

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

Pas 2: Carregueu el fitxer 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\"
  }"

Exemple: Importar un fitxer CAR amb 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);

Exemple: Importar un fitxer CAR amb 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"
  }
}

Com funciona el recompte de fitxers

Cada fitxer dins del CAR compta individualment respecte al límit de fitxers del vostre pla. Un CAR que conté 12 fitxers utilitza 13 places (12 fills + 1 entrada arrel del CAR). Un CAR d'un sol fitxer compta com a 1 plaça.

• L'emmagatzematge es cobra un cop sobre l'entrada arrel del CAR (la mida completa del fitxer CAR)
• Els fitxers fills individuals apareixen al vostre llistat de fitxers amb el CID arrel a la seva metadata (carParentCid) perquè els pugueu agrupar
• Màxim de 1.000 fitxers per importació CAR — els DAG més grans s'han de dividir en múltiples importacions

Si la importació del CAR superaria el límit de nombre de fitxers del vostre pla, la sol·licitud es rebutja amb un error 402 i el contingut es desfixa automàticament:

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

API compatible amb S3

Utilitzeu la capçalera x-amz-meta-import: car en una sol·licitud PutObject per importar un fitxer CAR a través de l'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" }   // ← activa la importació CAR
}));

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

MCP Server

L'eina ipfs_import_car està disponible al 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ó de fitxers CAR

Des d'un directori (recomanat)

Utilitzeu l'eina CLI ipfs-car:

# Instal·lació
npm install -g ipfs-car

# Empaquetar un directori en un fitxer CAR
ipfs-car pack ./my-directory -o my-archive.car

# Comprovar el CID arrel abans de carregar
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Des d'un node IPFS en execució

Exporteu qualsevol CID com a fitxer CAR amb el CLI de Kubo:

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

Programàticament amb JavaScript

Utilitzeu 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 blocs
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

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

// Recollir la sortida
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Verificació de la integritat del CID

L'avantatge principal de la importació CAR és la preservació del CID. Podeu verificar que el CID arrel coincideix abans i després de la càrrega:

# 1. Empaqueteu el directori i anoteu el CID arrel
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Carregueu 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"
# ✓ Els CID coincideixen — el contingut s'ha importat exactament com es va crear localment

Migració des d'un altre proveïdor

Des de Pinata

# Exportar des de Pinata mitjançant 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}"

Des de Filebase

# Filebase admet l'exportació CAR mitjançant la seva API S3
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ímits

Límit	Valor
Mida màxima del fitxer CAR	100 MB
Mínim d'arrels	Almenys un CID arrel
Format CAR	CARv1 (universalment compatible)
Disponibilitat	Tots els plans (Dharma, Bodhi, Nirvana)

S'apliquen els límits d'emmagatzematge i de nombre de fitxers del vostre pla. El DAG importat compta com una entrada de fitxer, i la mida del fitxer CAR es dedueix de la vostra quota d'emmagatzematge.

Resolució de problemes

"invalid CAR file: too small"

El contingut carregat és inferior a 40 bytes, massa petit per ser un fitxer CAR vàlid. Assegureu-vos que envieu el contingut CAR complet codificat en base64.

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

El fitxer CAR descodificat supera els 100 MB. Dividiu el vostre contingut en diversos fitxers CAR més petits amb el paquet carbites, o carregueu els fitxers individualment.

"dag/import did not return a root CID"

El node IPFS no ha pogut processar el fitxer CAR. Verifiqueu que el fitxer és un arxiu CARv1 vàlid:

ipfs-car roots my-archive.car

Si aquesta comanda falla, el fitxer CAR està malmès. Regenereu-lo amb ipfs-car pack o ipfs dag export.

"not enough storage"

S'ha assolit el límit d'emmagatzematge del vostre pla. Elimineu fitxers no utilitzats o actualitzeu el vostre pla a ipfs.ninja/pricing.