CAR Import (DAG Import)

CAR (Content Addressable aRchive) ファイルを使用して、IPFS DAG 全体を単一のリクエストでインポートします。CID は正確に保持されます — 再チャンク化や再ハッシュ化は行われません。

CAR ファイルとは？

CAR ファイルは、IPFS のディレクトリツリーまたは DAG 全体を単一のポータブルアーカイブにパッケージ化します。各ブロックは元の CID とともに保存されるため、サービスはすべてをそのままインポートします。これにより：

CID の保持 — CID をローカルで計算し、サービスがまったく同じ CID を返すことを確認できます
一括アップロード — 1つずつではなく、1回のリクエストで数百のファイルをアップロード
プロバイダーの移行 — 別のプロバイダーから DAG をエクスポートし、同一の CID で IPFS Ninja にインポート
カスタム DAG — 任意の IPLD データ構造を直接アップロード

REST API

POST /upload/new

通常のアップロードと同じ endpoint です — CAR インポートを示すために car: true を追加します。

リクエストボディ

パラメータ	型	必須	説明
`content`	string	はい	Base64 エンコードされた CAR ファイル
`car`	boolean	はい	CAR インポートを有効にするには `true` に設定
`description`	string	いいえ	インポートの短い説明
`folderId`	string	いいえ	インポートしたコンテンツを整理するフォルダ ID
`metadata`	object	いいえ	カスタムキーと値のペア（通常のアップロードと同じルール）

例: curl で CAR ファイルをインポート

ステップ 1: ipfs-car を使用してローカルディレクトリから CAR ファイルを作成します：

bash

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

ステップ 2: CAR ファイルをアップロードします：

bash

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 ファイルをインポート

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

例: Python で 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"])

レスポンス `200 OK`

json

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

S3-Compatible API

S3 API 経由で CAR ファイルをインポートするには、PutObject リクエストで x-amz-meta-import: car ヘッダーを使用します。

javascript

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 ツールを使用します：

bash

# 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 ノードから

Kubo CLI を使用して任意の CID を CAR ファイルとしてエクスポートします：

bash

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

JavaScript でプログラム的に

@ipld/car ライブラリを使用します：

javascript

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 の保持です。アップロード前後でルート CID が一致することを確認できます：

bash

# 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 が一致 — コンテンツはローカルで構築したものと全く同じようにインポートされました

別のプロバイダーからの移行

Pinata から

bash

# 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 から

bash

# 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
単一ルートの最大数	少なくとも1つのルート CID が必要
CAR フォーマット	CARv1（普遍的にサポート）
利用可能プラン	すべてのプラン（Dharma、Bodhi、Nirvana）

プランのストレージおよびファイル数の制限が適用されます。インポートされた DAG は1つのファイルエントリとしてカウントされ、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 アーカイブであることを確認してください：

bash

ipfs-car roots my-archive.car

このコマンドが失敗した場合、CAR ファイルが不正です。ipfs-car pack または ipfs dag export で再生成してください。

"not enough storage"

プランのストレージ制限に達しました。未使用のファイルを削除するか、ipfs.ninja/pricing でプランをアップグレードしてください。

CAR Import (DAG Import) ​

CAR ファイルとは？ ​

REST API ​

リクエストボディ ​

例: curl で CAR ファイルをインポート ​

例: JavaScript で CAR ファイルをインポート ​

例: Python で CAR ファイルをインポート ​

レスポンス 200 OK ​

S3-Compatible API ​

MCP Server ​

CAR ファイルの作成 ​

ディレクトリから（推奨） ​

実行中の IPFS ノードから ​

JavaScript でプログラム的に ​

CID 整合性の検証 ​

別のプロバイダーからの移行 ​

Pinata から ​

Filebase から ​

制限事項 ​

トラブルシューティング ​

"invalid CAR file: too small" ​

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

"dag/import did not return a root CID" ​

"not enough storage" ​

CAR Import (DAG Import)

CAR ファイルとは？

REST API

リクエストボディ

例: curl で CAR ファイルをインポート

例: JavaScript で CAR ファイルをインポート

例: Python で CAR ファイルをインポート

レスポンス `200 OK`

S3-Compatible API

MCP Server

CAR ファイルの作成

ディレクトリから（推奨）

実行中の IPFS ノードから

JavaScript でプログラム的に

CID 整合性の検証

別のプロバイダーからの移行

Pinata から

Filebase から

制限事項

トラブルシューティング

"invalid CAR file: too small"

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

"dag/import did not return a root CID"

"not enough storage"