CAR Import (DAG Import)

Importujte celé IPFS DAG-y jednou požiadavkou pomocou súborov CAR (Content Addressable aRchive). Vaše CID sa zachovajú presne — bez opätovného delenia alebo prehashovania.

Čo je súbor CAR?

Súbor CAR zabalí celý strom adresárov IPFS alebo DAG do jedného prenosného archívu. Každý blok je uložený s pôvodným CID, takže služba importuje všetko tak, ako je. To znamená:

• Zachovanie CID — vypočítajte CID lokálne, overte, že služba vráti presne ten istý CID
• Hromadné nahrávanie — nahrajte stovky súborov jednou požiadavkou namiesto jedného po druhom
• Migrácia od iného poskytovateľa — exportujte DAG od iného poskytovateľa, importujte do IPFS Ninja s identickými CID
• Vlastné DAG-y — nahrajte akúkoľvek dátovú štruktúru IPLD priamo

REST API

POST /upload/new

Rovnaký endpoint ako pri bežných nahrávaniach — pridajte car: true na signalizáciu importu CAR.

Telo požiadavky

Parameter	Typ	Povinný	Popis
content	string	Áno	Súbor CAR kódovaný v Base64
car	boolean	Áno	Nastavte na true pre aktiváciu importu CAR
description	string	Nie	Stručný popis importu
folderId	string	Nie	ID priečinka na organizáciu importovaného obsahu
metadata	object	Nie	Vlastné páry kľúč-hodnota (rovnaké pravidlá ako pri bežných nahrávaniach)

Príklad: Import súboru CAR pomocou curl

Krok 1: Vytvorte súbor CAR z lokálneho adresára pomocou ipfs-car:

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

Krok 2: Nahrajte súbor 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\"
  }"

Príklad: Import súboru CAR pomocou 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);

Príklad: Import súboru CAR pomocou 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"])

Odpoveď 200 OK

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

S3-Compatible API

Použite hlavičku x-amz-meta-import: car v požiadavke PutObject na import súboru CAR cez 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" }   // ← spustí import CAR
}));

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

MCP Server

Nástroj ipfs_import_car je dostupný v 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...

Vytváranie súborov CAR

Z adresára (odporúčané)

Použite CLI nástroj 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

Z bežiaceho uzla IPFS

Exportujte akýkoľvek CID ako súbor CAR pomocou CLI Kubo:

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

Programovo v JavaScript

Použite knižnicu @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);

Overenie integrity CID

Hlavnou výhodou importu CAR je zachovanie CID. Môžete overiť, že koreňový CID je rovnaký pred aj po nahraní:

# 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

Migrácia od iného poskytovateľa

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

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

Limity

Limit	Hodnota
Maximálna veľkosť súboru CAR	100 MB
Maximálny jeden koreň	Musí mať aspoň jeden koreňový CID
Formát CAR	CARv1 (univerzálne podporovaný)
Dostupnosť	Všetky plány (Dharma, Bodhi, Nirvana)

Platia limity úložiska a počtu súborov vášho plánu. Importovaný DAG sa počíta ako jeden súborový záznam a veľkosť súboru CAR sa odpočíta z vašej kvóty úložiska.

Riešenie problémov

"invalid CAR file: too small"

Nahraný obsah má menej ako 40 bajtov, čo je príliš málo na to, aby bol platným súborom CAR. Uistite sa, že odosielate úplný obsah CAR kódovaný v Base64.

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

Dekódovaný súbor CAR presahuje 100 MB. Rozdeľte obsah na viacero menších súborov CAR pomocou balíka carbites, alebo nahrajte súbory jednotlivo.

"dag/import did not return a root CID"

Uzol IPFS nedokázal spracovať súbor CAR. Overte, že súbor je platný archív CARv1:

ipfs-car roots my-archive.car

Ak tento príkaz zlyhá, súbor CAR je poškodený. Vygenerujte ho znova pomocou ipfs-car pack alebo ipfs dag export.

"not enough storage"

Limit úložiska vášho plánu bol dosiahnutý. Odstráňte nepoužívané súbory alebo inovujte svoj plán na ipfs.ninja/pricing.