CAR Import (DAG Import)

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

Завантажити CAR-файл в IPFS Ninja

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

• Збереження CID — обчислюйте CID локально, перевіряйте, що сервіс повертає точно такий самий CID
• Пакетне завантаження — завантажуйте сотні файлів одним запитом замість одного за одним
• Міграція від провайдера — експортуйте DAG від іншого провайдера, імпортуйте в IPFS Ninja з ідентичними CID
• Власні DAG — завантажуйте будь-яку структуру даних IPLD напряму

Завантаження через dashboard

Два шляхи drag-and-drop на /upload використовують той самий потік імпорту — код не потрібен:

• Перетягніть файл .car. Зона завантаження автоматично визначає розширення, показує банер "CAR archive detected", і кнопка відправлення стає "Import <filename> as CAR". Власний кореневий CID архіву зберігається.
• Перетягніть папку. Dashboard пакує папку в DAG UnixFS у вашому браузері (використовуючи ipfs-unixfs-importer із сучасним чанкером 1 MiB відповідно до IPIP-0499) і завантажує отриманий CAR через той самий шлях. Кореневий CID — це директорія bafybei…, яка розв'язується за адресою /ipfs/{cid}/{subpath}.

Обидва варіанти використовують потік presigned-PUT для будь-чого понад кілька MB — обмеження розміру файлу становить 5 ГБ на CAR.

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

Як працює підрахунок файлів

Кожен файл всередині CAR рахується окремо проти ліміту файлів вашого плану. CAR, що містить 12 файлів, використовує 13 слотів (12 дочірніх + 1 кореневий запис CAR). Однофайловий CAR рахується як 1 слот.

• Сховище стягується один раз за кореневий запис CAR (повний розмір CAR-файлу)
• Окремі дочірні файли з'являються у вашому списку файлів з кореневим CID у своїх метаданих (carParentCid), щоб ви могли їх групувати
• Максимум 1000 файлів на один імпорт CAR — більші DAG потрібно розділити на кілька імпортів

Якщо імпорт CAR перевищить ліміт кількості файлів вашого плану, запит відхиляється з помилкою 402, а контент автоматично відкріплюється:

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

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.