Import CAR (import de DAG)

Importez des DAG IPFS entiers en une seule requête à l'aide de fichiers CAR (Content Addressable aRchive). Vos CID sont préservés exactement — pas de redécoupage ni de rehachage.

Qu'est-ce qu'un fichier CAR ?

Un fichier CAR regroupe une arborescence de répertoires IPFS ou un DAG entier dans une seule archive portable. Chaque bloc est stocké avec son CID d'origine, de sorte que le service importe tout tel quel. Cela signifie :

• Préservation des CID — calculez les CID localement, vérifiez que le service renvoie exactement le même CID
• Téléversement en lot — téléversez des centaines de fichiers en une seule requête au lieu d'un par un
• Migration de fournisseur — exportez un DAG d'un autre fournisseur, importez-le dans IPFS Ninja avec des CID identiques
• DAG personnalisés — téléversez n'importe quelle structure de données IPLD directement

Téléverser via le tableau de bord

Deux chemins de glisser-déposer sur /upload aboutissent à ce même flux d'import — aucun code requis :

• Déposez un fichier .car. La zone de téléversement détecte automatiquement l'extension, affiche une bannière « CAR archive detected » et le bouton de soumission devient « Import <filename> as CAR ». Le CID racine propre à l'archive est préservé.
• Déposez un dossier. Le tableau de bord regroupe le dossier dans un DAG UnixFS dans votre navigateur (à l'aide de ipfs-unixfs-importer avec le chunker moderne de 1 MiB selon IPIP-0499) et téléverse le CAR résultant via ce même chemin. Le CID racine est un répertoire bafybei… qui se résout à /ipfs/{cid}/{subpath}.

Les deux utilisent le flux de PUT présigné pour tout ce qui dépasse quelques Mo — la taille de fichier plafonne à 5 Go par CAR.

API REST

POST /upload/new

Même endpoint que les téléversements classiques — ajoutez car: true pour indiquer un import CAR.

Corps de la requête

Paramètre	Type	Requis	Description
content	string	Oui	Fichier CAR encodé en base64
car	boolean	Oui	Définir sur true pour activer l'import CAR
description	string	Non	Courte description de l'import
folderId	string	Non	ID de dossier pour organiser le contenu importé
metadata	object	Non	Paires clé-valeur personnalisées (mêmes règles que les téléversements classiques)

Exemple : importer un fichier CAR avec curl

Étape 1 : Créez un fichier CAR à partir d'un répertoire local avec ipfs-car :

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

Étape 2 : Téléversez le fichier 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 : importer un fichier CAR avec 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 : importer un fichier CAR avec 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"])

Réponse 200 OK

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

Comment fonctionne le comptage des fichiers

Chaque fichier à l'intérieur du CAR compte individuellement dans la limite de fichiers de votre plan. Un CAR contenant 12 fichiers utilise 13 emplacements (12 enfants + 1 entrée racine du CAR). Un CAR à un seul fichier compte pour 1 emplacement.

• Le stockage est facturé une seule fois sur l'entrée racine du CAR (la taille complète du fichier CAR)
• Les fichiers enfants individuels apparaissent dans votre liste de fichiers avec le CID racine dans leurs métadonnées (carParentCid) afin de pouvoir les regrouper
• Maximum 1000 fichiers par import CAR — les DAG plus volumineux doivent être répartis sur plusieurs imports

Si l'import du CAR dépasserait le nombre de fichiers autorisé par votre plan, la requête est rejetée avec une erreur 402 et le contenu est désépinglé automatiquement :

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

API compatible S3

Utilisez l'en-tête x-amz-meta-import: car sur une requête PutObject pour importer un fichier CAR via 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" }   // ← déclenche l'import CAR
}));

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

Serveur MCP

L'outil ipfs_import_car est disponible dans le serveur MCP (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...

Création de fichiers CAR

À partir d'un répertoire (recommandé)

Utilisez l'outil 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

À partir d'un nœud IPFS en cours d'exécution

Exportez n'importe quel CID sous forme de fichier CAR avec le CLI Kubo :

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

Par programmation avec JavaScript

Utilisez la bibliothèque @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);

Vérification de l'intégrité des CID

L'avantage clé de l'import CAR est la préservation des CID. Vous pouvez vérifier que le CID racine correspond avant et après le téléversement :

# 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

Migration depuis un autre fournisseur

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

Depuis 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	Valeur
Taille maximale du fichier CAR	100 Mo
Racine unique maximale	Au moins un CID racine requis
Format CAR	CARv1 (universellement pris en charge)
Disponibilité	Tous les plans (Dharma, Bodhi, Nirvana)

Les limites de stockage et de nombre de fichiers de votre plan s'appliquent. Le DAG importé compte comme une seule entrée de fichier, et la taille du fichier CAR est déduite de votre quota de stockage.

Dépannage

« invalid CAR file: too small »

Le contenu téléversé fait moins de 40 octets, ce qui est trop petit pour être un fichier CAR valide. Assurez-vous d'envoyer l'intégralité du contenu CAR encodé en base64.

« File too large. Maximum upload size is 100 MB. »

Le fichier CAR décodé dépasse 100 Mo. Divisez votre contenu en plusieurs fichiers CAR plus petits à l'aide du package carbites, ou téléversez les fichiers individuellement.

« dag/import did not return a root CID »

Le nœud IPFS n'a pas pu traiter le fichier CAR. Vérifiez que le fichier est une archive CARv1 valide :

ipfs-car roots my-archive.car

Si cette commande échoue, le fichier CAR est malformé. Régénérez-le avec ipfs-car pack ou ipfs dag export.

« not enough storage »

La limite de stockage de votre plan a été atteinte. Supprimez les fichiers inutilisés ou passez à un plan supérieur sur ipfs.ninja/pricing.