CAR Import (DAG Import)

Importujte celé IPFS DAG struktury jedním požadavkem pomocí souborů CAR (Content Addressable aRchive). Vaše CID se zachovají přesně — bez opětovného dělení nebo přepočítávání hashů.

Co je soubor CAR?

Soubor CAR zabalí celý adresářový strom IPFS nebo DAG do jediného přenositelného archivu. Každý blok je uložen se svým původním CID, takže služba vše importuje tak, jak je. To znamená:

• Zachování CID — vypočítejte CID lokálně, ověřte, že služba vrátí přesně stejné CID
• Hromadné nahrávání — nahrajte stovky souborů jedním požadavkem místo jednoho po druhém
• Migrace poskytovatele — exportujte DAG od jiného poskytovatele, importujte do IPFS Ninja se stejnými CID
• Vlastní DAG — nahrajte jakoukoli IPLD datovou strukturu přímo

REST API

POST /upload/new

Stejný endpoint jako běžné nahrávání — přidejte car: true pro signalizaci CAR importu.

Tělo požadavku

Parametr	Typ	Povinný	Popis
content	string	Ano	Soubor CAR zakódovaný v Base64
car	boolean	Ano	Nastavte na true pro aktivaci CAR importu
description	string	Ne	Krátký popis importu
folderId	string	Ne	ID složky pro organizaci importovaného obsahu
metadata	object	Ne	Vlastní páry klíč-hodnota (stejná pravidla jako u běžných nahrávání)

Příklad: Import souboru CAR pomocí curl

Krok 1: Vytvořte soubor CAR z lokálního adresáře pomocí ipfs-car:

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

Krok 2: Nahrajte soubor 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\"
  }"

Příklad: Import souboru CAR pomocí 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);

Příklad: Import souboru CAR pomocí 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"])

Odpověď 200 OK

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

S3-kompatibilní API

Použijte hlavičku x-amz-meta-import: car v požadavku PutObject pro import souboru CAR přes S3 API.

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í CAR import
}));

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áření souborů CAR

Z adresáře (doporučeno)

Použijte CLI nástroj ipfs-car:

# Instalace
npm install -g ipfs-car

# Zabalení adresáře do souboru CAR
ipfs-car pack ./my-directory -o my-archive.car

# Kontrola kořenového CID před nahráním
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Z běžícího IPFS uzlu

Exportujte jakékoli CID jako soubor CAR pomocí Kubo CLI:

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

Programově pomocí JavaScript

Použijte knihovnu @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";

// Vytvoření bloků
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

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

// Shromáždění výstupu
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Ověření integrity CID

Klíčovou výhodou CAR importu je zachování CID. Můžete ověřit, že kořenové CID odpovídá před i po nahrání:

# 1. Zabalte adresář a zaznamenejte kořenové CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Nahrajte na 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"
# ✓ CID se shodují — obsah byl importován přesně tak, jak byl vytvořen lokálně

Migrace od jiného poskytovatele

Z Pinata

# Export z Pinata přes IPFS gateway
ipfs dag export QmYourCID > export.car

# Import do 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 podporuje CAR export přes své S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Import do 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ální velikost souboru CAR	100 MB
Minimální počet kořenů	Alespoň jedno kořenové CID
Formát CAR	CARv1 (univerzálně podporovaný)
Dostupnost	Všechny plány (Dharma, Bodhi, Nirvana)

Platí limity úložiště a počtu souborů vašeho plánu. Importovaný DAG se počítá jako jeden záznam souboru a velikost souboru CAR se odečítá z vaší kvóty úložiště.

Řešení problémů

"invalid CAR file: too small"

Nahraný obsah má méně než 40 bajtů, což je příliš málo pro platný soubor CAR. Ujistěte se, že odesíláte kompletní obsah CAR zakódovaný v base64.

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

Dekódovaný soubor CAR překračuje 100 MB. Rozdělte obsah na více menších souborů CAR pomocí balíčku carbites, nebo nahrajte soubory jednotlivě.

"dag/import did not return a root CID"

IPFS uzel nemohl zpracovat soubor CAR. Ověřte, že soubor je platný archiv CARv1:

ipfs-car roots my-archive.car

Pokud tento příkaz selže, soubor CAR je poškozený. Vygenerujte jej znovu pomocí ipfs-car pack nebo ipfs dag export.

"not enough storage"

Byl dosažen limit úložiště vašeho plánu. Smažte nepoužívané soubory nebo upgradujte svůj plán na ipfs.ninja/pricing.