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ů.

Nahrát CAR soubor do IPFS Ninja

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

Nahrání přes řídicí panel

Dva postupy přetažením na stránce /upload používají tentýž importní tok — bez nutnosti psát kód:

• Přetáhněte soubor .car. Nahrávací zóna automaticky rozpozná příponu, zobrazí banner „CAR archiv rozpoznán" a tlačítko odeslání se změní na „Importovat <filename> jako CAR". Zachová se vlastní kořenové CID archivu.
• Přetáhněte složku. Řídicí panel zabalí složku do UnixFS DAG struktury přímo ve vašem prohlížeči (pomocí ipfs-unixfs-importer s moderním chunkerem 1 MiB podle IPIP-0499) a nahraje výsledný CAR přes tentýž tok. Kořenové CID je adresář bafybei…, který se rozřeší na /ipfs/{cid}/{subpath}.

Obě cesty používají presigned-PUT tok pro cokoli nad pár MB — limit velikosti souboru je 5 GB na jeden CAR.

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"])

Response 200 OK

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

Jak funguje počítání souborů

Každý soubor uvnitř CAR se počítá jednotlivě do limitu souborů vašeho plánu. CAR obsahující 12 souborů zabere 13 slotů (12 podřízených souborů + 1 kořenový záznam CAR). Jednosouborový CAR se počítá jako 1 slot.

• Úložiště je účtováno jednou na kořenovém záznamu CAR (velikost celého CAR souboru)
• Jednotlivé podřízené soubory se objeví ve vašem seznamu souborů s kořenovým CID ve svých metadatech (carParentCid), takže je můžete seskupovat
• Maximum 1000 souborů na import CAR — větší DAG struktury musí být rozděleny do více importů

Pokud by import CAR překročil počet souborů vašeho plánu, požadavek je odmítnut s chybou 402 a obsah je automaticky odpojen:

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

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:

# 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 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";

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

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. 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

Migrace od jiného poskytovatele

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á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.