CAR Import (DAG Import)

使用 CAR（Content Addressable aRchive）文件在单个请求中导入完整的 IPFS DAG。您的 CID 会被精确保留——不会重新分块，也不会重新哈希。

将 CAR 文件上传到 IPFS Ninja

CAR 文件将完整的 IPFS 目录树或 DAG 打包成一个可移植的归档文件。每个区块都以其原始 CID 存储，因此服务会原样导入所有内容。这意味着：

CID 保留 — 在本地计算 CID，验证服务返回的是完全相同的 CID
批量上传 — 在一个请求中上传数百个文件，而不是逐个上传
提供商迁移 — 从其他提供商导出 DAG，以相同的 CID 导入到 IPFS Ninja
自定义 DAG — 直接上传任意 IPLD 数据结构

通过控制台上传

/upload 页面上有两条拖放路径都会进入同一个导入流程——无需编写代码：

拖放一个 .car 文件。 上传区域会自动检测扩展名，显示"检测到 CAR 归档"提示条，提交按钮会变为"将 <filename> 导入为 CAR"。归档自身的根 CID 会被保留。
拖放一个文件夹。 控制台会在您的浏览器中把该文件夹打包成一个 UnixFS DAG（使用 ipfs-unixfs-importer，并按照 IPIP-0499 采用现代的 1 MiB 分块器），再通过相同的路径上传生成的 CAR 文件。根 CID 是一个 bafybei… 目录，可通过 /ipfs/{cid}/{subpath} 解析。

对于超过几 MB 的内容，两种方式都会使用预签名 PUT 流程——每个 CAR 的文件大小上限为 5 GB。

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 文件：

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,
  "fileCount": 12,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

文件计数的工作原理

CAR 内的每个文件都会单独计入您计划的文件数量限制。一个包含 12 个文件的 CAR 会占用 13 个名额（12 个子文件 + 1 个根 CAR 条目）。单文件 CAR 计为 1 个名额。

存储空间仅在根 CAR 条目上收取一次（完整的 CAR 文件大小）
各个子文件会出现在您的文件列表中，其元数据中会带有根 CID（carParentCid），方便您对它们进行分组
每次 CAR 导入最多支持 1000 个文件 — 更大的 DAG 必须拆分为多次导入

如果导入该 CAR 会超出您计划的文件数量限制，请求将被拒绝并返回 402 错误，同时内容会被自动取消固定：

json

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

S3 兼容 API

在 PutObject 请求中使用 x-amz-meta-import: car 头来通过 S3 API 导入 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" }   // ← triggers CAR import
}));

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"
# ✓ CIDs match — content imported exactly as built locally

从其他提供商迁移

从 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
最大单根	必须至少有一个根 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 归档：

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 文件上传到 IPFS Ninja ​

通过控制台上传 ​

REST API ​

请求体 ​

示例：使用 curl 导入 CAR 文件 ​

示例：使用 JavaScript 导入 CAR 文件 ​

示例：使用 Python 导入 CAR 文件 ​

响应 200 OK ​

文件计数的工作原理 ​

S3 兼容 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 文件上传到 IPFS Ninja

通过控制台上传

REST API

请求体

示例：使用 curl 导入 CAR 文件

示例：使用 JavaScript 导入 CAR 文件

示例：使用 Python 导入 CAR 文件

响应 `200 OK`

文件计数的工作原理

S3 兼容 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"