CAR Import (DAG Import)

Импортируйте целые DAG-графы IPFS одним запросом, используя файлы CAR (Content Addressable aRchive). Ваши CID сохраняются в точности — без повторного разбиения или перехеширования.

Что такое файл CAR?

Файл CAR упаковывает всё дерево каталогов IPFS или DAG в один переносимый архив. Каждый блок хранится с оригинальным CID, поэтому сервис импортирует всё как есть. Это означает:

• Сохранение CID — вычислите CID локально, убедитесь, что сервис возвращает точно такой же CID
• Пакетная загрузка — загрузите сотни файлов одним запросом вместо поочерёдной загрузки
• Миграция от другого провайдера — экспортируйте DAG у другого провайдера, импортируйте в IPFS Ninja с идентичными CID
• Пользовательские DAG — загрузите любую структуру данных IPLD напрямую

REST API

POST /upload/new

Тот же endpoint, что и для обычных загрузок — добавьте car: true, чтобы указать на импорт CAR.

Тело запроса

Параметр	Тип	Обязательный	Описание
content	string	Да	Файл CAR в кодировке Base64
car	boolean	Да	Установите true для активации импорта CAR
description	string	Нет	Краткое описание импорта
folderId	string	Нет	ID папки для организации импортированного содержимого
metadata	object	Нет	Пользовательские пары ключ-значение (те же правила, что и для обычных загрузок)

Пример: Импорт файла CAR с помощью curl

Шаг 1: Создайте файл CAR из локального каталога с помощью ipfs-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\"
  }"

Пример: Импорт файла 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);

Пример: Импорт файла 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

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

S3-Compatible API

Используйте заголовок x-amz-meta-import: car в запросе PutObject для импорта файла CAR через API S3.

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

Из каталога (рекомендуется)

Используйте 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

Из работающего узла IPFS

Экспортируйте любой CID как файл CAR с помощью CLI Kubo:

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

// 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 совпадает до и после загрузки:

# 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

# 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

# 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. Убедитесь, что вы отправляете полное содержимое CAR в кодировке Base64.

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

Декодированный файл CAR превышает 100 MB. Разделите содержимое на несколько файлов CAR меньшего размера с помощью пакета carbites или загружайте файлы по отдельности.

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