CAR Import (DAG Import)

使用 CAR (Content Addressable aRchive) 檔案在單一請求中匯入完整的 IPFS DAG。您的 CID 會被精確保留——不會重新分塊或重新雜湊。

什麼是 CAR 檔案？

CAR 檔案將完整的 IPFS 目錄樹或 DAG 封裝成單一可攜式歸檔檔案。每個區塊都以其原始 CID 儲存，因此服務會原樣匯入所有內容。這意味著：

• CID 保留 — 在本機計算 CID，驗證服務傳回完全相同的 CID
• 批次上傳 — 在一個請求中上傳數百個檔案，而不是逐一上傳
• 提供商遷移 — 從其他提供商匯出 DAG，以相同的 CID 匯入到 IPFS Ninja
• 自訂 DAG — 直接上傳任何 IPLD 資料結構

REST API

POST /upload/new

與一般上傳使用相同的 endpoint — 新增 car: true 以表示 CAR 匯入。

請求主體

參數	類型	必填	描述
content	string	是	Base64 編碼的 CAR 檔案
car	boolean	是	設定為 true 以啟用 CAR 匯入
description	string	否	匯入的簡短描述
folderId	string	否	用於組織匯入內容的資料夾 ID
metadata	object	否	自訂鍵值對（與一般上傳相同的規則）

範例：使用 curl 匯入 CAR 檔案

步驟 1： 使用 ipfs-car 從本機目錄建立 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\"
  }"

範例：使用 JavaScript 匯入 CAR 檔案

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

範例：使用 Python 匯入 CAR 檔案

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

回應 200 OK

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

S3 相容 API

在 PutObject 請求中使用 x-amz-meta-import: car 標頭，透過 S3 API 匯入 CAR 檔案。

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 檔案

從目錄建立（建議）

使用 ipfs-car CLI 工具：

# 安裝
npm install -g ipfs-car

# 將目錄封裝成 CAR 檔案
ipfs-car pack ./my-directory -o my-archive.car

# 上傳前檢查根 CID
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

從執行中的 IPFS 節點

使用 Kubo CLI 將任何 CID 匯出為 CAR 檔案：

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

// 建立區塊
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// 寫入 CAR
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// 收集輸出
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

驗證 CID 完整性

CAR 匯入的關鍵優勢是 CID 保留。您可以驗證根 CID 在上傳前後是否一致：

# 1. 封裝目錄並記錄根 CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. 上傳到 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 一致 — 內容完全按照本機建立的方式匯入

從其他提供商遷移

從 Pinata

# 透過 IPFS 閘道從 Pinata 匯出
ipfs dag export QmYourCID > export.car

# 匯入到 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 支援透過其 S3 API 匯出 CAR
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# 匯入到 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
最大單一根	必須至少有一個根 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。使用 carbites 套件將內容拆分為多個較小的 CAR 檔案，或逐一上傳檔案。

"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 升級您的方案。