CAR Import (DAG Import)

Impor seluruh DAG IPFS dalam satu permintaan menggunakan file CAR (Content Addressable aRchive). CID Anda dipertahankan persis sama — tanpa re-chunking atau re-hashing.

Apa itu file CAR?

File CAR mengemas seluruh pohon direktori atau DAG IPFS ke dalam satu arsip portabel. Setiap blok disimpan dengan CID aslinya, sehingga layanan mengimpor semuanya apa adanya. Ini berarti:

• Pelestarian CID — hitung CID secara lokal, verifikasi bahwa layanan mengembalikan CID yang persis sama
• Unggah massal — unggah ratusan file dalam satu permintaan alih-alih satu per satu
• Migrasi penyedia — ekspor DAG dari penyedia lain, impor ke IPFS Ninja dengan CID yang identik
• DAG kustom — unggah struktur data IPLD apa pun secara langsung

REST API

POST /upload/new

Endpoint yang sama dengan unggahan biasa — tambahkan car: true untuk menandakan impor CAR.

Isi permintaan

Parameter	Tipe	Wajib	Deskripsi
content	string	Ya	File CAR yang dienkode Base64
car	boolean	Ya	Atur ke true untuk mengaktifkan impor CAR
description	string	Tidak	Deskripsi singkat tentang impor
folderId	string	Tidak	ID folder untuk mengorganisasi konten yang diimpor
metadata	object	Tidak	Pasangan kunci-nilai kustom (aturan sama seperti unggahan biasa)

Contoh: Impor file CAR dengan curl

Langkah 1: Buat file CAR dari direktori lokal menggunakan ipfs-car:

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

Langkah 2: Unggah file 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\"
  }"

Contoh: Impor file CAR dengan 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);

Contoh: Impor file CAR dengan 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"])

Respons 200 OK

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

S3-Compatible API

Gunakan header x-amz-meta-import: car pada permintaan PutObject untuk mengimpor file CAR melalui 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" }   // ← memicu impor CAR
}));

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

MCP Server

Alat ipfs_import_car tersedia di 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...

Membuat File CAR

Dari direktori (direkomendasikan)

Gunakan alat 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

Dari node IPFS yang sedang berjalan

Ekspor CID apa pun sebagai file CAR menggunakan Kubo CLI:

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

Secara programatis dengan JavaScript

Gunakan pustaka @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);

Memverifikasi Integritas CID

Manfaat utama impor CAR adalah pelestarian CID. Anda dapat memverifikasi bahwa CID root cocok sebelum dan sesudah pengunggahan:

# 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 cocok — konten diimpor persis seperti yang dibuat secara lokal

Migrasi dari Penyedia Lain

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

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

Batasan

Batasan	Nilai
Ukuran maksimum file CAR	100 MB
Root tunggal maksimum	Harus memiliki setidaknya satu CID root
Format CAR	CARv1 (didukung secara universal)
Ketersediaan	Semua paket (Dharma, Bodhi, Nirvana)

Batasan penyimpanan dan jumlah file dari paket Anda tetap berlaku. DAG yang diimpor dihitung sebagai satu entri file, dan ukuran file CAR dikurangkan dari kuota penyimpanan Anda.

Pemecahan Masalah

"invalid CAR file: too small"

Konten yang diunggah kurang dari 40 byte, yang terlalu kecil untuk menjadi file CAR yang valid. Pastikan Anda mengirimkan konten CAR lengkap yang dienkode Base64.

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

File CAR yang didekode melebihi 100 MB. Bagi konten Anda menjadi beberapa file CAR yang lebih kecil menggunakan paket carbites, atau unggah file satu per satu.

"dag/import did not return a root CID"

Node IPFS tidak dapat memproses file CAR. Verifikasi bahwa file tersebut adalah arsip CARv1 yang valid:

ipfs-car roots my-archive.car

Jika perintah ini gagal, file CAR tersebut rusak. Buat ulang dengan ipfs-car pack atau ipfs dag export.

"not enough storage"

Batas penyimpanan paket Anda telah tercapai. Hapus file yang tidak digunakan atau tingkatkan paket Anda di ipfs.ninja/pricing.