CAR Import (DAG Import)

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
• Envoi groupé — téléchargez 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échargez n'importe quelle structure de données IPLD directement

REST API

POST /upload/new

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

Corps de la requête

Paramètre	Type	Obligatoire	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	Identifiant du dossier pour organiser le contenu importé
metadata	object	Non	Paires clé-valeur personnalisées (mêmes règles que les téléchargements 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échargez 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,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

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

MCP Server

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

Création de fichiers CAR

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

Utilisez l'outil CLI ipfs-car :

# Installer
npm install -g ipfs-car

# Empaqueter un répertoire dans un fichier CAR
ipfs-car pack ./my-directory -o my-archive.car

# Vérifier le CID racine avant le téléchargement
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échargement :

# 1. Empaqueter le répertoire et noter le CID racine
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Télécharger vers 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"
# ✓ Les CID correspondent — le contenu a été importé exactement tel que construit localement

Migration depuis un autre fournisseur

Depuis Pinata

# Exporter depuis Pinata via la passerelle IPFS
ipfs dag export QmYourCID > export.car

# Importer vers 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 prend en charge l'export CAR via leur API S3
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Importer vers 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échargé 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échargez 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 mettez à niveau votre plan sur ipfs.ninja/pricing.