CAR Import (DAG Import)

Увезите читаве IPFS DAG структуре у једном захтеву користећи CAR (Content Addressable aRchive) датотеке. Ваши CID-ови се чувају тачно — без поновног дељења на делове или поновног хеширања.

Отпреми CAR датотеку у IPFS Ninja

CAR датотека пакује читаво стабло IPFS директоријума или DAG у један преносиви архив. Сваки блок се чува са својим оригиналним CID-ом, тако да сервис увози све онако како јесте. То значи:

• Очување CID-а — израчунајте CID-ове локално, проверите да сервис враћа потпуно исти CID
• Групно отпремање — отпремите стотине фајлова у једном захтеву уместо један по један
• Миграција провајдера — извезите DAG са другог провајдера, увезите на IPFS Ninja са идентичним CID-овима
• Прилагођене DAG структуре — отпремите било коју IPLD структуру података директно

Отпремање преко контролне табле

Две путање превуци-и-пусти на /upload користе исти овај ток увоза — без потребе за кодом:

• Превуците .car датотеку. Зона за отпремање аутоматски препознаје екстензију, приказује обавештење „CAR archive detected", а дугме за слање постаје „Import <filename> as CAR". Сопствени root CID архива се чува.
• Превуците фолдер. Контролна табла пакује фолдер у UnixFS DAG у вашем прегледачу (користећи ipfs-unixfs-importer са модерним chunker-ом од 1 MiB према IPIP-0499) и отпрема резултујући CAR кроз исту путању. Root CID је bafybei… директоријум који се разрешава на /ipfs/{cid}/{subpath}.

Обе користе ток presigned-PUT за све изнад неколико MB — ограничење величине фајла је 5 GB по CAR-у.

REST API

POST /upload/new

Иста крајња тачка као за обична отпремања — додајте car: true да означите CAR увоз.

Тело захтева

Параметар	Тип	Обавезно	Опис
content	string	Да	Base64-кодирана CAR датотека
car	boolean	Да	Поставите на true да омогућите CAR увоз
description	string	Не	Кратак опис увоза
folderId	string	Не	ID фолдера за организацију увезеног садржаја
metadata	object	Не	Прилагођени парови кључ-вредност (иста правила као за обична отпремања)

Пример: Увоз CAR датотеке помоћу curl

Корак 1: Направите CAR датотеку од локалног директоријума користећи ipfs-car:

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

Корак 2: Отпремите 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\"
  }"

Пример: Увоз CAR датотеке помоћу 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);

Пример: Увоз CAR датотеке помоћу 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"
  }
}

Како функционише бројање фајлова

Сваки фајл унутар CAR-а се посебно рачуна у ограничење броја фајлова вашег плана. CAR који садржи 12 фајлова користи 13 места (12 дечијих + 1 root CAR унос). CAR са једним фајлом рачуна се као 1 место.

• Складиштење се наплаћује једном на root CAR уносу (пуна величина CAR датотеке)
• Појединачни дечији фајлови се појављују у вашој листи фајлова са root CID-ом у својим метаподацима (carParentCid) тако да их можете груписати
• Максимално 1000 фајлова по CAR увозу — веће DAG структуре морају бити подељене у више увоза

Ако би увоз CAR-а премашио ограничење броја фајлова вашег плана, захтев се одбија са грешком 402, а садржај се аутоматски откачи:

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

S3-компатибилни API

Користите заглавље x-amz-meta-import: car на PutObject захтеву да увезете CAR датотеку преко 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" }   // ← покреће CAR увоз
}));

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

MCP Server

Алат ipfs_import_car доступан је у 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...

Прављење CAR датотека

Из директоријума (препоручено)

Користите 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

Са покренутог IPFS чвора

Извезите било који CID као CAR датотеку користећи Kubo CLI:

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

Програмски помоћу JavaScript

Користите библиотеку @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);

Верификација интегритета CID-а

Кључна предност CAR увоза је очување CID-а. Можете проверити да се root CID поклапа пре и после отпремања:

# 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-ovi se poklapaju — sadržaj je uvezen tačno onako kako je lokalno napravljen

Миграција са другог провајдера

Са 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}"

Са 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}"

Ограничења

Ограничење	Вредност
Максимална величина CAR датотеке	100 MB
Максимално један root	Мора имати бар један root CID
CAR формат	CARv1 (универзално подржан)
Доступност	Сви планови (Dharma, Bodhi, Nirvana)

Примењују се ограничења складиштења и броја фајлова вашег плана. Увезена DAG структура се рачуна као један унос фајла, а величина CAR датотеке се одузима од ваше квоте складиштења.

Решавање проблема

"invalid CAR file: too small"

Отпремљени садржај је мањи од 40 бајтова, што је премало за важећу CAR датотеку. Уверите се да шаљете цео base64-кодирани CAR садржај.

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

Декодирана CAR датотека прелази 100 MB. Поделите садржај на више мањих CAR датотека користећи пакет carbites, или отпремите фајлове појединачно.

"dag/import did not return a root CID"

IPFS чвор није могао да обради CAR датотеку. Проверите да је фајл важећи CARv1 архив:

ipfs-car roots my-archive.car

Ако ова команда не успе, CAR датотека је неисправна. Поново је генеришите помоћу ipfs-car pack или ipfs dag export.

"not enough storage"

Ограничење складиштења вашег плана је достигнуто. Обришите фајлове који вам нису потребни или надоградите план на ipfs.ninja/pricing.