CAR Import (DAG Import)

Importa interi DAG IPFS in una singola richiesta utilizzando file CAR (Content Addressable aRchive). I tuoi CID vengono preservati esattamente — nessun re-chunking o re-hashing.

Cos'e un file CAR?

Un file CAR racchiude un intero albero di directory o DAG IPFS in un singolo archivio portatile. Ogni blocco viene memorizzato con il suo CID originale, quindi il servizio importa tutto cosi com'e. Questo significa:

• Preservazione dei CID — calcola i CID localmente, verifica che il servizio restituisca esattamente lo stesso CID
• Caricamento in blocco — carica centinaia di file in una sola richiesta invece che uno alla volta
• Migrazione del provider — esporta un DAG da un altro provider, importalo su IPFS Ninja con CID identici
• DAG personalizzati — carica qualsiasi struttura dati IPLD direttamente

REST API

POST /upload/new

Lo stesso endpoint dei caricamenti normali — aggiungi car: true per indicare un'importazione CAR.

Corpo della richiesta

Parametro	Tipo	Obbligatorio	Descrizione
content	string	Si	File CAR codificato in Base64
car	boolean	Si	Imposta su true per abilitare l'importazione CAR
description	string	No	Breve descrizione dell'importazione
folderId	string	No	ID della cartella in cui organizzare il contenuto importato
metadata	object	No	Coppie chiave-valore personalizzate (stesse regole dei caricamenti normali)

Esempio: Importare un file CAR con curl

Passo 1: Crea un file CAR da una directory locale usando ipfs-car:

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

Passo 2: Carica il file 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\"
  }"

Esempio: Importare un file 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);

Esempio: Importare un file 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"])

Risposta 200 OK

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

S3-Compatible API

Usa l'header x-amz-meta-import: car in una richiesta PutObject per importare un file CAR tramite l'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" }   // ← attiva l'importazione CAR
}));

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

MCP Server

Lo strumento ipfs_import_car e disponibile nel 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...

Creare File CAR

Da una directory (consigliato)

Usa lo strumento 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

Da un nodo IPFS in esecuzione

Esporta qualsiasi CID come file CAR usando il Kubo CLI:

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

Programmaticamente con JavaScript

Usa la libreria @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);

Verifica dell'Integrita dei CID

Il vantaggio principale dell'importazione CAR e la preservazione dei CID. Puoi verificare che il CID root corrisponda prima e dopo il caricamento:

# 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"
# ✓ I CID corrispondono — il contenuto e stato importato esattamente come creato localmente

Migrazione da un Altro Provider

Da 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}"

Da 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}"

Limiti

Limite	Valore
Dimensione massima file CAR	100 MB
Root singola massima	Deve avere almeno un CID root
Formato CAR	CARv1 (supportato universalmente)
Disponibilita	Tutti i piani (Dharma, Bodhi, Nirvana)

Si applicano i limiti di archiviazione e numero di file del tuo piano. Il DAG importato conta come una singola voce file, e la dimensione del file CAR viene detratta dalla tua quota di archiviazione.

Risoluzione dei Problemi

"invalid CAR file: too small"

Il contenuto caricato e inferiore a 40 byte, troppo piccolo per essere un file CAR valido. Assicurati di inviare il contenuto CAR completo codificato in Base64.

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

Il file CAR decodificato supera i 100 MB. Dividi il contenuto in piu file CAR piu piccoli usando il pacchetto carbites, oppure carica i file singolarmente.

"dag/import did not return a root CID"

Il nodo IPFS non e riuscito a elaborare il file CAR. Verifica che il file sia un archivio CARv1 valido:

ipfs-car roots my-archive.car

Se questo comando fallisce, il file CAR e malformato. Rigeneralo con ipfs-car pack o ipfs dag export.

"not enough storage"

Il limite di archiviazione del tuo piano e stato raggiunto. Elimina i file inutilizzati o aggiorna il tuo piano su ipfs.ninja/pricing.