CAR Import (DAG Import)

Uvezite citave IPFS DAG-ove u jednom zahtevu koristeci CAR (Content Addressable aRchive) datoteke. Vasi CID-ovi su sacuvani tacno -- bez ponovnog deljenja ili ponovnog hesiranja.

Sta je CAR datoteka?

CAR datoteka pakuje citavo IPFS stablo direktorijuma ili DAG u jedan prenosivi arhiv. Svaki blok je sacuvan sa svojim originalnim CID-om, tako da servis uvozi sve kakvo jeste. To znaci:

• Ocuvanje CID-a -- izracunajte CID-ove lokalno, proverite da servis vraca potpuno isti CID
• Grupno otpremanje -- otpremite stotine datoteka u jednom zahtevu umesto jednu po jednu
• Migracija provajdera -- izvezite DAG od drugog provajdera, uvezite u IPFS Ninja sa identicnim CID-ovima
• Prilagodjeni DAG-ovi -- otpremite bilo koju IPLD strukturu podataka direktno

REST API

POST /upload/new

Ista krajnja tacka kao za obicna otpremanja -- dodajte car: true da oznacite CAR uvoz.

Telo zahteva

Parametar	Tip	Obavezno	Opis
content	string	Da	Base64-kodirana CAR datoteka
car	boolean	Da	Postavite na true da omogucite CAR uvoz
description	string	Ne	Kratak opis uvoza
folderId	string	Ne	ID foldera za organizaciju uvezenog sadrzaja
metadata	object	Ne	Prilagodjeni parovi kljuc-vrednost (ista pravila kao za obicna otpremanja)

Primer: Uvoz CAR datoteke sa curl

Korak 1: Kreirajte CAR datoteku od lokalnog direktorijuma koristeci ipfs-car:

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

Korak 2: Otpremite CAR datoteku:

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

Primer: Uvoz CAR datoteke sa 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);

Primer: Uvoz CAR datoteke sa 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"])

Odgovor 200 OK

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

S3-Compatible API

Koristite zaglavlje x-amz-meta-import: car na PutObject zahtevu da uvezete CAR datoteku preko 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" }   // ← pokrece CAR uvoz
}));

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

MCP Server

Alat ipfs_import_car je dostupan u 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...

Kreiranje CAR datoteka

Iz direktorijuma (preporuceno)

Koristite CLI alat ipfs-car:

# Instalacija
npm install -g ipfs-car

# Pakujte direktorijum u CAR datoteku
ipfs-car pack ./my-directory -o my-archive.car

# Proverite korenski CID pre otpremanja
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Iz pokrenutog IPFS cvora

Izvezite bilo koji CID kao CAR datoteku koristeci Kubo CLI:

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

Programski sa JavaScript

Koristite biblioteku @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);

Verifikacija integriteta CID-a

Kljucna prednost CAR uvoza je ocuvanje CID-a. Mozete proveriti da se korenski CID poklapa pre i posle otpremanja:

# 1. Pakujte direktorijum i zabelezite korenski CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Otpremite 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-ovi se poklapaju -- sadrzaj je uvezen tacno onako kako je lokalno napravljen

Migracija sa drugog provajdera

Sa Pinata

# Izvoz sa Pinata preko IPFS gateway-a
ipfs dag export QmYourCID > export.car

# Uvoz u 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}"

Sa Filebase

# Filebase podrzava CAR izvoz preko svog S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Uvoz u 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}"

Ogranicenja

Ogranicenje	Vrednost
Maksimalna velicina CAR datoteke	100 MB
Maksimalno jedan koren	Mora imati najmanje jedan korenski CID
CAR format	CARv1 (univerzalno podrzan)
Dostupnost	Svi planovi (Dharma, Bodhi, Nirvana)

Ogranicenja skladistenja i broja datoteka vaseg plana se primenjuju. Uvezeni DAG se racuna kao jedan unos datoteke, a velicina CAR datoteke se oduzima od vase kvote skladistenja.

Resavanje problema

"invalid CAR file: too small"

Otpremljeni sadrzaj je manji od 40 bajtova, sto je premalo za validnu CAR datoteku. Uverite se da saljete ceo base64-kodirani CAR sadrzaj.

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

Dekodirana CAR datoteka prelazi 100 MB. Podelite sadrzaj na vise manjih CAR datoteka koristeci paket carbites ili otpremite datoteke pojedinacno.

"dag/import did not return a root CID"

IPFS cvor nije mogao da obradi CAR datoteku. Proverite da je datoteka validan CARv1 arhiv:

ipfs-car roots my-archive.car

Ako ova komanda ne uspe, CAR datoteka je neispravna. Ponovo je generisajte sa ipfs-car pack ili ipfs dag export.

"not enough storage"

Ogranicenje skladistenja vaseg plana je dostignuto. Obrisite nekoriscene datoteke ili nadogradite plan na ipfs.ninja/pricing.