CAR Import (DAG Import)

Importuj całe DAG-i IPFS w jednym żądaniu za pomocą plików CAR (Content Addressable aRchive). Twoje CID-y są zachowywane dokładnie — bez ponownego dzielenia na fragmenty ani ponownego hashowania.

Czym jest plik CAR?

Plik CAR pakuje całe drzewo katalogów IPFS lub DAG w jedno przenośne archiwum. Każdy blok jest przechowywany z oryginalnym CID, więc usługa importuje wszystko bez zmian. Oznacza to:

• Zachowanie CID — oblicz CID-y lokalnie, zweryfikuj, że usługa zwraca dokładnie ten sam CID
• Przesyłanie zbiorcze — prześlij setki plików w jednym żądaniu zamiast pojedynczo
• Migracja dostawcy — wyeksportuj DAG od innego dostawcy, zaimportuj do IPFS Ninja z identycznymi CID-ami
• Niestandardowe DAG-i — prześlij dowolną strukturę danych IPLD bezpośrednio

Przesyłanie przez dashboard

Dwie ścieżki przeciągnij-i-upuść na /upload trafiają w ten sam przepływ importu — bez potrzeby kodu:

• Upuść plik .car. Strefa przesyłania automatycznie wykrywa rozszerzenie, pokazuje baner "CAR archive detected", a przycisk potwierdzenia zmienia się na "Import <filename> as CAR". Własny CID główny archiwum jest zachowany.
• Upuść folder. Dashboard pakuje folder do DAG-a UnixFS w Twojej przeglądarce (używając ipfs-unixfs-importer z nowoczesnym chunkerem 1 MiB zgodnie z IPIP-0499) i przesyła wynikowy plik CAR tą samą ścieżką. Główny CID to katalog bafybei…, który rozwiązuje się pod /ipfs/{cid}/{subpath}.

Obie metody używają przepływu presigned-PUT dla wszystkiego powyżej kilku MB — limit rozmiaru pliku to 5 GB na plik CAR.

REST API

POST /upload/new

Ten sam endpoint co w przypadku zwykłych przesyłań — dodaj car: true, aby wskazać import CAR.

Treść żądania

Parametr	Typ	Wymagany	Opis
content	string	Tak	Plik CAR zakodowany w Base64
car	boolean	Tak	Ustaw na true, aby włączyć import CAR
description	string	Nie	Krótki opis importu
folderId	string	Nie	ID folderu do organizacji zaimportowanej zawartości
metadata	object	Nie	Niestandardowe pary klucz-wartość (te same zasady co w zwykłych przesyłaniach)

Przykład: Import pliku CAR za pomocą curl

Krok 1: Utwórz plik CAR z lokalnego katalogu za pomocą ipfs-car:

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

Krok 2: Prześlij plik 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\"
  }"

Przykład: Import pliku CAR za 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);

Przykład: Import pliku CAR za 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"])

Odpowiedź 200 OK

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

Jak działa liczenie plików

Każdy plik wewnątrz CAR liczy się osobno do limitu plików Twojego planu. CAR zawierający 12 plików zajmuje 13 slotów (12 plików podrzędnych + 1 wpis głównego CAR). CAR z jednym plikiem liczy się jako 1 slot.

• Przechowywanie jest naliczane raz, na głównym wpisie CAR (pełny rozmiar pliku CAR)
• Poszczególne pliki podrzędne pojawiają się na Twojej liście plików z głównym CID w ich metadanych (carParentCid), dzięki czemu możesz je grupować
• Maksymalnie 1000 plików na import CAR — większe DAG-i trzeba podzielić na wiele importów

Jeśli import CAR przekroczyłby limit liczby plików Twojego planu, żądanie jest odrzucane z błędem 402, a treść zostaje automatycznie odpięta:

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

API zgodne z S3

Użyj nagłówka x-amz-meta-import: car w żądaniu PutObject, aby zaimportować plik CAR przez 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" }   // ← uruchamia import CAR
}));

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

MCP Server

Narzędzie ipfs_import_car jest dostępne w 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...

Tworzenie plików CAR

Z katalogu (zalecane)

Użyj narzędzia 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

Z działającego węzła IPFS

Wyeksportuj dowolny CID jako plik CAR za pomocą Kubo CLI:

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

Programowo za pomocą JavaScript

Użyj biblioteki @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);

Weryfikacja integralności CID

Główną zaletą importu CAR jest zachowanie CID. Możesz zweryfikować, czy główny CID jest zgodny przed i po przesłaniu:

# 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"
# ✓ CID-y są zgodne — zawartość zaimportowana dokładnie tak, jak zbudowana lokalnie

Migracja od innego dostawcy

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	Wartość
Maksymalny rozmiar pliku CAR	100 MB
Maksymalnie jeden root	Musi mieć co najmniej jeden główny CID
Format CAR	CARv1 (uniwersalnie obsługiwany)
Dostępność	Wszystkie plany (Dharma, Bodhi, Nirvana)

Obowiązują limity przechowywania i liczby plików z Twojego planu. Zaimportowany DAG jest liczony jako jeden wpis pliku, a rozmiar pliku CAR jest odejmowany od Twojego limitu przechowywania.

Rozwiązywanie problemów

"invalid CAR file: too small"

Przesłana zawartość ma mniej niż 40 bajtów, co jest zbyt mało, aby być prawidłowym plikiem CAR. Upewnij się, że wysyłasz pełną zawartość CAR zakodowaną w base64.

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

Zdekodowany plik CAR przekracza 100 MB. Podziel zawartość na kilka mniejszych plików CAR za pomocą pakietu carbites lub prześlij pliki pojedynczo.

"dag/import did not return a root CID"

Węzeł IPFS nie mógł przetworzyć pliku CAR. Sprawdź, czy plik jest prawidłowym archiwum CARv1:

ipfs-car roots my-archive.car

Jeśli to polecenie się nie powiedzie, plik CAR jest uszkodzony. Wygeneruj go ponownie za pomocą ipfs-car pack lub ipfs dag export.

"not enough storage"

Limit przechowywania Twojego planu został osiągnięty. Usuń nieużywane pliki lub ulepsz swój plan na ipfs.ninja/pricing.