CAR Import (DAG Import)

Importați DAG-uri IPFS întregi într-o singură cerere folosind fișiere CAR (Content Addressable aRchive). CID-urile dvs. sunt păstrate exact — fără re-chunking sau re-hashing.

Ce este un fișier CAR?

Un fișier CAR împachetează un arbore de directoare IPFS întreg sau un DAG într-o singură arhivă portabilă. Fiecare bloc este stocat cu CID-ul său original, astfel încât serviciul importă totul exact așa cum este. Aceasta înseamnă:

• Păstrarea CID-ului — calculați CID-urile local, verificați că serviciul returnează exact același CID
• Încărcare în lot — încărcați sute de fișiere într-o singură cerere în loc de unul câte unul
• Migrare de la alt furnizor — exportați un DAG de la alt furnizor, importați în IPFS Ninja cu CID-uri identice
• DAG-uri personalizate — încărcați orice structură de date IPLD direct

Încărcare prin Dashboard

Două căi de tragere și plasare pe /upload folosesc același flux de import — fără a scrie cod:

• Plasați un fișier .car. Zona de încărcare detectează automat extensia, afișează un banner „Arhivă CAR detectată" și butonul de trimitere devine „Importă <filename> ca CAR". CID-ul rădăcină propriu al arhivei este păstrat.
• Plasați un folder. Dashboard-ul împachetează folderul într-un DAG UnixFS chiar în browserul dvs. (folosind ipfs-unixfs-importer cu chunker-ul modern de 1 MiB conform IPIP-0499) și încarcă CAR-ul rezultat prin aceeași cale. CID-ul rădăcină este un director bafybei… care se rezolvă la /ipfs/{cid}/{subpath}.

Ambele folosesc fluxul PUT presemnat pentru orice depășește câțiva MB — limita de dimensiune a fișierului este 5 GB per CAR.

API REST

POST /upload/new

Același endpoint ca pentru încărcările obișnuite — adăugați car: true pentru a semnala un import CAR.

Corpul cererii

Parametru	Tip	Obligatoriu	Descriere
content	string	Da	Fișier CAR codificat Base64
car	boolean	Da	Setați la true pentru a activa importul CAR
description	string	Nu	Scurtă descriere a importului
folderId	string	Nu	ID-ul folderului pentru organizarea conținutului importat
metadata	object	Nu	Perechi cheie-valoare personalizate (aceleași reguli ca pentru încărcările obișnuite)

Exemplu: importarea unui fișier CAR cu curl

Pasul 1: Creați un fișier CAR dintr-un director local folosind ipfs-car:

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

Pasul 2: Încărcați fișierul 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\"
  }"

Exemplu: importarea unui fișier CAR cu 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);

Exemplu: importarea unui fișier CAR cu 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"])

Response 200 OK

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

Cum funcționează numărarea fișierelor

Fiecare fișier din interiorul CAR-ului contează individual în limita de fișiere a planului dvs. Un CAR care conține 12 fișiere folosește 13 sloturi (12 fișiere copil + 1 intrare CAR rădăcină). Un CAR cu un singur fișier contează ca 1 slot.

• Stocarea este taxată o singură dată pe intrarea CAR rădăcină (dimensiunea completă a fișierului CAR)
• Fișierele copil individuale apar în lista dvs. de fișiere cu CID-ul rădăcină în metadatele lor (carParentCid) astfel încât să le puteți grupa
• Maximum 1000 de fișiere per import CAR — DAG-urile mai mari trebuie împărțite în mai multe importuri

Dacă importarea CAR-ului ar depăși numărul de fișiere al planului dvs., cererea este respinsă cu o eroare 402 și conținutul este defixat automat:

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

API compatibil S3

Folosiți antetul x-amz-meta-import: car într-o cerere PutObject pentru a importa un fișier CAR prin API-ul 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" }   // ← triggers CAR import
}));

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

MCP Server

Instrumentul ipfs_import_car este disponibil în 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...

Crearea fișierelor CAR

Dintr-un director (recomandat)

Folosiți instrumentul 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

De la un nod IPFS în execuție

Exportați orice CID ca fișier CAR folosind CLI-ul Kubo:

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

Programatic cu JavaScript

Folosiți 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";

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

Verificarea integrității CID

Beneficiul cheie al importului CAR este păstrarea CID-ului. Puteți verifica dacă CID-ul rădăcină se potrivește înainte și după încărcare:

# 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

Migrare de la alt furnizor

De la 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}"

De la 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}"

Limite

Limită	Valoare
Dimensiune maximă fișier CAR	100 MB
Rădăcină unică maximă	Trebuie să aibă cel puțin un CID rădăcină
Format CAR	CARv1 (suportat universal)
Disponibilitate	Toate planurile (Dharma, Bodhi, Nirvana)

Limitele de stocare și de număr de fișiere ale planului dvs. se aplică. DAG-ul importat contează ca o singură intrare de fișier, iar dimensiunea fișierului CAR este dedusă din cota dvs. de stocare.

Depanare

"invalid CAR file: too small"

Conținutul încărcat are mai puțin de 40 de octeți, ceea ce este prea mic pentru a fi un fișier CAR valid. Asigurați-vă că trimiteți conținutul CAR complet codificat Base64.

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

Fișierul CAR decodificat depășește 100 MB. Împărțiți conținutul în mai multe fișiere CAR mai mici folosind pachetul carbites, sau încărcați fișierele individual.

"dag/import did not return a root CID"

Nodul IPFS nu a putut procesa fișierul CAR. Verificați dacă fișierul este o arhivă CARv1 validă:

ipfs-car roots my-archive.car

Dacă această comandă eșuează, fișierul CAR este malformat. Regenerați-l cu ipfs-car pack sau ipfs dag export.

"not enough storage"

Limita de stocare a planului dvs. a fost atinsă. Ștergeți fișierele neutilizate sau faceți upgrade la planul dvs. pe ipfs.ninja/pricing.