CAR Import (DAG Import)

Importieren Sie ganze IPFS DAGs in einer einzigen Anfrage mithilfe von CAR-Dateien (Content Addressable aRchive). Ihre CIDs bleiben exakt erhalten — kein Re-Chunking oder Re-Hashing.

Was ist eine CAR-Datei?

Eine CAR-Datei verpackt einen gesamten IPFS-Verzeichnisbaum oder DAG in ein einzelnes portables Archiv. Jeder Block wird mit seiner ursprünglichen CID gespeichert, sodass der Dienst alles unverändert importiert. Das bedeutet:

• CID-Erhaltung — berechnen Sie CIDs lokal und überprüfen Sie, ob der Dienst exakt dieselbe CID zurückgibt
• Batch-Upload — laden Sie hunderte Dateien in einer einzigen Anfrage hoch, statt einzeln
• Anbietermigration — exportieren Sie einen DAG von einem anderen Anbieter und importieren Sie ihn mit identischen CIDs zu IPFS Ninja
• Benutzerdefinierte DAGs — laden Sie beliebige IPLD-Datenstrukturen direkt hoch

REST API

POST /upload/new

Derselbe endpoint wie bei regulären Uploads — fügen Sie car: true hinzu, um einen CAR Import zu signalisieren.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
content	string	Ja	Base64-codierte CAR-Datei
car	boolean	Ja	Auf true setzen, um den CAR Import zu aktivieren
description	string	Nein	Kurze Beschreibung des Imports
folderId	string	Nein	Ordner-ID, um den importierten Inhalt einzuordnen
metadata	object	Nein	Benutzerdefinierte Schlüssel-Wert-Paare (dieselben Regeln wie bei regulären Uploads)

Beispiel: CAR-Datei mit curl importieren

Schritt 1: Erstellen Sie eine CAR-Datei aus einem lokalen Verzeichnis mit ipfs-car:

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

Schritt 2: Laden Sie die CAR-Datei hoch:

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

Beispiel: CAR-Datei mit JavaScript importieren

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

Beispiel: CAR-Datei mit Python importieren

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"])

Antwort 200 OK

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

S3-kompatible API

Verwenden Sie den Header x-amz-meta-import: car bei einer PutObject-Anfrage, um eine CAR-Datei über die S3 API zu importieren.

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" }   // ← löst CAR Import aus
}));

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

MCP Server

Das Tool ipfs_import_car ist im MCP Server (v1.3.0+) verfügbar:

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

CAR-Dateien erstellen

Aus einem Verzeichnis (empfohlen)

Verwenden Sie das CLI-Tool ipfs-car:

# Installieren
npm install -g ipfs-car

# Ein Verzeichnis in eine CAR-Datei packen
ipfs-car pack ./my-directory -o my-archive.car

# Die Root-CID vor dem Upload prüfen
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Von einem laufenden IPFS-Knoten

Exportieren Sie eine beliebige CID als CAR-Datei mit der Kubo-CLI:

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

Programmatisch mit JavaScript

Verwenden Sie die Bibliothek @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";

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

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

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

CID-Integrität überprüfen

Der Hauptvorteil des CAR Imports ist die CID-Erhaltung. Sie können die Root-CID vor und nach dem Upload überprüfen:

# 1. Verzeichnis packen und die Root-CID notieren
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Zu IPFS Ninja hochladen
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 stimmen überein — Inhalt wurde exakt wie lokal erstellt importiert

Von einem anderen Anbieter migrieren

Von Pinata

# Von Pinata über das IPFS-Gateway exportieren
ipfs dag export QmYourCID > export.car

# Zu IPFS Ninja importieren
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}"

Von Filebase

# Filebase unterstützt CAR-Export über ihre S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Zu IPFS Ninja importieren
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}"

Limits

Limit	Wert
Maximale CAR-Dateigröße	100 MB
Maximale einzelne Root	Muss mindestens eine Root-CID haben
CAR-Format	CARv1 (universell unterstützt)
Verfügbarkeit	Alle Pläne (Dharma, Bodhi, Nirvana)

Speicher- und Dateianzahl-Limits Ihres Plans gelten weiterhin. Der importierte DAG zählt als ein Dateieintrag, und die CAR-Dateigröße wird von Ihrem Speicherkontingent abgezogen.

Fehlerbehebung

"invalid CAR file: too small"

Der hochgeladene Inhalt ist weniger als 40 Bytes groß, was zu klein für eine gültige CAR-Datei ist. Stellen Sie sicher, dass Sie den vollständigen base64-codierten CAR-Inhalt senden.

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

Die decodierte CAR-Datei überschreitet 100 MB. Teilen Sie Ihren Inhalt in mehrere kleinere CAR-Dateien mit dem Paket carbites auf, oder laden Sie Dateien einzeln hoch.

"dag/import did not return a root CID"

Der IPFS-Knoten konnte die CAR-Datei nicht verarbeiten. Überprüfen Sie, ob die Datei ein gültiges CARv1-Archiv ist:

ipfs-car roots my-archive.car

Wenn dieser Befehl fehlschlägt, ist die CAR-Datei fehlerhaft. Erstellen Sie sie neu mit ipfs-car pack oder ipfs dag export.

"not enough storage"

Das Speicherlimit Ihres Plans wurde erreicht. Löschen Sie ungenutzte Dateien oder aktualisieren Sie Ihren Plan unter ipfs.ninja/pricing.