CAR Import (DAG Import)

CAR (Content Addressable aRchive) dosyalarını kullanarak tek bir istekle tam IPFS DAG'lerini içe aktarın. CID'leriniz tam olarak korunur — yeniden parçalama veya yeniden hashleme yapılmaz.

IPFS Ninja'ya CAR Dosyası Yükleme

Bir CAR dosyası, tam bir IPFS dizin ağacını veya DAG'yi tek bir taşınabilir arşivde paketler. Her blok orijinal CID'si ile saklanır, böylece hizmet her şeyi olduğu gibi içe aktarır. Bu şu anlama gelir:

• CID koruması — CID'leri yerel olarak hesaplayın, hizmetin tam olarak aynı CID'yi döndürdüğünü doğrulayın
• Toplu yükleme — tek tek yerine yüzlerce dosyayı tek bir istekle yükleyin
• Sağlayıcı göçü — başka bir sağlayıcıdan bir DAG dışa aktarın, aynı CID'lerle IPFS Ninja'ya içe aktarın
• Özel DAG'ler — herhangi bir IPLD veri yapısını doğrudan yükleyin

Dashboard üzerinden Yükleme

/upload üzerindeki iki sürükle-bırak yolu aynı içe aktarma akışına ulaşır — kod gerekmez:

• Bir .car dosyası bırakın. Yükleme alanı uzantıyı otomatik algılar, "CAR archive detected" banner'ı gösterir ve gönder düğmesi "Import <filename> as CAR" olur. Arşivin kendi kök CID'si korunur.
• Bir klasör bırakın. Dashboard, klasörü tarayıcınızda bir UnixFS DAG'ına paketler (IPIP-0499'a göre modern 1 MiB parçalayıcı ile ipfs-unixfs-importer kullanarak) ve ortaya çıkan CAR'ı aynı yol üzerinden yükler. Kök CID, /ipfs/{cid}/{subpath} üzerinde çözümlenen bir bafybei… dizinidir.

Her ikisi de birkaç MB'nin üzerindeki her şey için önceden imzalı PUT akışını kullanır — CAR başına dosya boyutu sınırı 5 GB'dir.

REST API

POST /upload/new

Normal yüklemelerle aynı endpoint — CAR içe aktarımını belirtmek için car: true ekleyin.

İstek gövdesi

Parametre	Tür	Zorunlu	Açıklama
content	string	Evet	Base64 kodlanmış CAR dosyası
car	boolean	Evet	CAR içe aktarımını etkinleştirmek için true olarak ayarlayın
description	string	Hayır	İçe aktarımın kısa açıklaması
folderId	string	Hayır	İçe aktarılan içeriği düzenlemek için klasör ID'si
metadata	object	Hayır	Özel anahtar-değer çiftleri (normal yüklemelerle aynı kurallar)

Örnek: curl ile bir CAR dosyasını içe aktarma

Adım 1: ipfs-car kullanarak yerel bir dizinden CAR dosyası oluşturun:

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

Adım 2: CAR dosyasını yükleyin:

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

Örnek: JavaScript ile bir CAR dosyasını içe aktarma

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

Örnek: Python ile bir CAR dosyasını içe aktarma

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"])

Yanıt 200 OK

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

Dosya sayımı nasıl çalışır

CAR içindeki her dosya, planınızın dosya sınırına ayrı ayrı sayılır. 12 dosya içeren bir CAR 13 slot kullanır (12 alt öğe + 1 kök CAR girişi). Tek dosyalı bir CAR 1 slot olarak sayılır.

• Depolama, kök CAR girişinde bir kez ücretlendirilir (tam CAR dosya boyutu)
• Tek tek alt dosyalar, gruplandırabilmeniz için meta verilerinde kök CID'siyle (carParentCid) dosya listenizde görünür
• CAR içe aktarımı başına maksimum 1000 dosya — daha büyük DAG'ler birden fazla içe aktarıma bölünmelidir

CAR'ı içe aktarmak planınızın dosya sayısını aşarsa, istek bir 402 hatasıyla reddedilir ve içerik otomatik olarak sabitlemeden çıkarılır:

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

S3 Uyumlu API

CAR dosyasını S3 API üzerinden içe aktarmak için PutObject isteğinde x-amz-meta-import: car başlığını kullanın.

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 içe aktarımını tetikler
}));

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

MCP Server

ipfs_import_car aracı MCP Server (v1.3.0+) içinde mevcuttur:

You: Import my-archive.car to IPFS
Claude: [calls ipfs_import_car with base64 content]
     → Root CID: bafybeig... — https://ipfs.ninja/ipfs/bafybeig...

CAR Dosyaları Oluşturma

Bir dizinden (önerilen)

ipfs-car CLI aracını kullanın:

# 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

Çalışan bir IPFS düğümünden

Kubo CLI kullanarak herhangi bir CID'yi CAR dosyası olarak dışa aktarın:

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

JavaScript ile programatik olarak

@ipld/car kütüphanesini kullanın:

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 Bütünlüğünü Doğrulama

CAR içe aktarımının temel faydası CID korumasıdır. Kök CID'nin yükleme öncesi ve sonrasında eşleştiğini doğrulayabilirsiniz:

# 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'ler eşleşiyor — içerik yerel olarak oluşturulduğu şekliyle içe aktarıldı

Başka Bir Sağlayıcıdan Göç

Pinata'dan

# 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'den

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

Limitler

Limit	Değer
Maksimum CAR dosya boyutu	100 MB
Maksimum tek kök	En az bir kök CID bulunmalıdır
CAR formatı	CARv1 (evrensel olarak desteklenir)
Erişilebilirlik	Tüm planlar (Dharma, Bodhi, Nirvana)

Planınızdaki depolama ve dosya sayısı limitleri geçerlidir. İçe aktarılan DAG tek bir dosya girişi olarak sayılır ve CAR dosya boyutu depolama kotanızdan düşülür.

Sorun Giderme

"invalid CAR file: too small"

Yüklenen içerik 40 bayttan küçüktür, bu geçerli bir CAR dosyası için çok küçüktür. Tam base64 kodlanmış CAR içeriğini gönderdiğinizden emin olun.

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

Çözümlenen CAR dosyası 100 MB'ı aşıyor. carbites paketini kullanarak içeriğinizi birden fazla küçük CAR dosyasına bölün veya dosyaları tek tek yükleyin.

"dag/import did not return a root CID"

IPFS düğümü CAR dosyasını işleyemedi. Dosyanın geçerli bir CARv1 arşivi olduğunu doğrulayın:

ipfs-car roots my-archive.car

Bu komut başarısız olursa, CAR dosyası hatalıdır. ipfs-car pack veya ipfs dag export ile yeniden oluşturun.

"not enough storage"

Planınızın depolama limiti dolmuştur. Kullanılmayan dosyaları silin veya ipfs.ninja/pricing adresinden planınızı yükseltin.