CAR Import (DAG Import)

Імпортуйте цілі IPFS DAG за один запит, використовуючи файли 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-сумісний API

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

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:

# Встановлення
npm install -g ipfs-car

# Пакування каталогу у файл CAR
ipfs-car pack ./my-directory -o my-archive.car

# Перевірка кореневого CID перед завантаженням
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

З працюючого вузла IPFS

Експортуйте будь-який CID як файл CAR за допомогою Kubo CLI:

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

# Експорт з Pinata через IPFS шлюз
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 підтримує експорт CAR через свій S3 API
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. Переконайтеся, що ви надсилаєте повний контент 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.