CAR Import (DAG Import)

Uvezite cijele IPFS DAG strukture u jednom zahtjevu koristeći CAR (Content Addressable aRchive) datoteke. Vaši CID-ovi su sačuvani točno — bez ponovnog dijeljenja ili ponovnog hashiranja.

Što je CAR datoteka?

CAR datoteka pakira cijelo IPFS stablo direktorija ili DAG u jednu prenosivu arhivu. Svaki blok je pohranjen sa svojim izvornim CID-om, tako da servis uvozi sve točno kako jest. To znači:

• Očuvanje CID-a — izračunajte CID-ove lokalno, provjerite da servis vraća točno isti CID
• Grupni upload — učitajte stotine datoteka u jednom zahtjevu umjesto jednu po jednu
• Migracija pružatelja — izvezite DAG od drugog pružatelja, uvezite u IPFS Ninja s identičnim CID-ovima
• Prilagođeni DAG-ovi — učitajte bilo koju IPLD strukturu podataka izravno

REST API

POST /upload/new

Isti endpoint kao i obični uploadi — dodajte car: true za označavanje CAR uvoza.

Tijelo zahtjeva

Parametar	Tip	Obavezno	Opis
content	string	Da	Base64-kodirana CAR datoteka
car	boolean	Da	Postavite na true za omogućavanje CAR uvoza
description	string	Ne	Kratki opis uvoza
folderId	string	Ne	ID mape za organiziranje uvezenog sadržaja
metadata	object	Ne	Prilagođeni parovi ključ-vrijednost (ista pravila kao kod običnih uploada)

Primjer: Uvoz CAR datoteke s curl-om

Korak 1: Stvorite CAR datoteku iz lokalnog direktorija koristeći ipfs-car:

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

Korak 2: Učitajte 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\"
  }"

Primjer: Uvoz CAR datoteke s JavaScriptom

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

Primjer: Uvoz CAR datoteke s Pythonom

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-kompatibilni API

Koristite zaglavlje x-amz-meta-import: car na PutObject zahtjevu za uvoz CAR datoteke putem S3 API-ja.

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" }   // ← pokreće CAR uvoz
}));

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

MCP Server

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

Stvaranje CAR datoteka

Iz direktorija (preporučeno)

Koristite ipfs-car CLI alat:

# Instalirajte
npm install -g ipfs-car

# Zapakirajte direktorij u CAR datoteku
ipfs-car pack ./my-directory -o my-archive.car

# Provjerite korijenski CID prije učitavanja
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Iz pokrenutog IPFS čvora

Izvezite bilo koji CID kao CAR datoteku koristeći Kubo CLI:

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

Programski s JavaScriptom

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

Provjera integriteta CID-a

Ključna prednost CAR uvoza je očuvanje CID-a. Možete provjeriti da se korijenski CID podudara prije i nakon učitavanja:

# 1. Zapakirajte direktorij i zabilježite korijenski CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Učitajte 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 podudaraju — sadržaj je uvezen točno onako kako je lokalno izgrađen

Migracija s drugog pružatelja

S Pinate

# Izvezite s Pinate putem IPFS pristupnika
ipfs dag export QmYourCID > export.car

# Uvezite 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}"

S Filebasea

# Filebase podržava CAR izvoz putem svog S3 API-ja
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Uvezite 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}"

Ograničenja

Ograničenje	Vrijednost
Maksimalna veličina CAR datoteke	100 MB
Maksimalni pojedinačni korijen	Potreban je barem jedan korijenski CID
CAR format	CARv1 (univerzalno podržan)
Dostupnost	Svi planovi (Dharma, Bodhi, Nirvana)

Primjenjuju se ograničenja pohrane i broja datoteka vašeg plana. Uvezeni DAG broji se kao jedan unos datoteke, a veličina CAR datoteke oduzima se od vaše kvote pohrane.

Rješavanje problema

"invalid CAR file: too small"

Učitani sadržaj je manji od 40 bajtova, što je premalo za valjanu CAR datoteku. Provjerite da šaljete potpuni base64-kodirani CAR sadržaj.

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

Dekodirana CAR datoteka prelazi 100 MB. Podijelite svoj sadržaj u više manjih CAR datoteka koristeći paket carbites, ili učitajte datoteke pojedinačno.

"dag/import did not return a root CID"

IPFS čvor nije mogao obraditi CAR datoteku. Provjerite da je datoteka valjana CARv1 arhiva:

ipfs-car roots my-archive.car

Ako ova naredba ne uspije, CAR datoteka je neispravna. Regenerirajte je s ipfs-car pack ili ipfs dag export.

"not enough storage"

Dosegnuto je ograničenje pohrane vašeg plana. Obrišite nekorištene datoteke ili nadogradite svoj plan na ipfs.ninja/pricing.