CAR Import (DAG Import)

Mag-import ng buong IPFS DAG sa isang request gamit ang mga CAR (Content Addressable aRchive) file. Nananatiling eksakto ang iyong mga CID — walang muling paghahati o muling pag-hash.

Mag-upload ng CAR File sa IPFS Ninja

Pinapackage ng CAR file ang buong IPFS directory tree o DAG sa isang portable na archive. Bawat block ay naka-store kasama ang orihinal nitong CID, kaya ini-import ng serbisyo ang lahat nang walang pagbabago. Ibig sabihin nito:

• Preserbasyon ng CID — kalkulahin ang mga CID nang lokal, i-verify na ibinabalik ng serbisyo ang eksaktong parehong CID
• Batch na pag-upload — mag-upload ng daan-daang file sa isang request sa halip na isa-isa
• Paglipat ng provider — i-export ang isang DAG mula sa ibang provider, i-import sa IPFS Ninja na may magkakaparehong CID
• Custom na mga DAG — direktang mag-upload ng anumang IPLD na data structure

Mag-upload sa pamamagitan ng Dashboard

Dalawang drag-and-drop na path sa /upload ang dumadaan sa parehong import flow na ito — walang kailangang code:

• I-drop ang isang .car file. Awtomatikong nade-detect ng upload zone ang extension, nagpapakita ng "CAR archive detected" banner, at nagiging "Import <filename> as CAR" ang submit button. Napapanatili ang sariling root CID ng archive.
• I-drop ang isang folder. Pinapackage ng dashboard ang folder sa isang UnixFS DAG sa iyong browser (gamit ang ipfs-unixfs-importer na may modernong 1 MiB na chunker ayon sa IPIP-0499) at ini-upload ang resultang CAR sa parehong path. Ang root CID ay isang bafybei… na directory na nire-resolve sa /ipfs/{cid}/{subpath}.

Gumagamit pareho ng presigned-PUT na flow para sa anumang mas malaki sa ilang MB — ang limitasyon sa laki ng file ay 5 GB bawat CAR.

REST API

POST /upload/new

Parehong endpoint sa mga regular na upload — magdagdag ng car: true para ipahiwatig ang CAR import.

Request body

Parameter	Uri	Kinakailangan	Paglalarawan
content	string	Oo	Base64-encoded na CAR file
car	boolean	Oo	Itakda sa true para paganahin ang CAR import
description	string	Hindi	Maikling paglalarawan ng import
folderId	string	Hindi	Folder ID para ayusin ang na-import na nilalaman
metadata	object	Hindi	Custom na key-value pairs (parehong mga patakaran sa regular na mga upload)

Halimbawa: Mag-import ng CAR file gamit ang curl

Hakbang 1: Gumawa ng CAR file mula sa lokal na direktoryo gamit ang ipfs-car:

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

Hakbang 2: I-upload ang CAR file:

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\"
  }"

Halimbawa: Mag-import ng CAR file gamit ang 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);

Halimbawa: Mag-import ng CAR file gamit ang 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"])

Response 200 OK

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

Paano gumagana ang pagbilang ng file

Bawat file sa loob ng CAR ay binibilang nang isa-isa laban sa file limit ng iyong plan. Ang isang CAR na may 12 file ay gumagamit ng 13 slot (12 child + 1 root CAR entry). Ang isang single-file na CAR ay binibilang bilang 1 slot.

• Sinisingil ang storage nang isang beses sa root CAR entry (ang buong laki ng CAR file)
• Lumalabas ang mga indibidwal na child file sa iyong file listing na may root CID sa kanilang metadata (carParentCid) para magrupo mo ang mga ito
• Maximum na 1000 file bawat CAR import — kailangang hatiin sa maraming import ang mas malalaking DAG

Kung lalampas sa file count ng iyong plan ang pag-import ng CAR, tinatanggihan ang request na may 402 error at awtomatikong nauunpin ang nilalaman:

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

S3-Compatible API

Gamitin ang x-amz-meta-import: car header sa isang PutObject na request para mag-import ng CAR file sa pamamagitan ng 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" }   // ← nagti-trigger ng CAR import
}));

console.log("Root CID:", result.ETag);

MCP Server

Available ang tool na ipfs_import_car sa 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...

Paggawa ng mga CAR File

Mula sa isang direktoryo (inirerekomenda)

Gamitin ang CLI tool na ipfs-car:

# I-install
npm install -g ipfs-car

# I-pack ang direktoryo sa isang CAR file
ipfs-car pack ./my-directory -o my-archive.car

# Suriin ang root CID bago mag-upload
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Mula sa isang tumatakbong IPFS node

I-export ang anumang CID bilang CAR file gamit ang Kubo CLI:

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

Sa pamamagitan ng programa gamit ang JavaScript

Gamitin ang library na @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);

Pag-verify ng Integridad ng CID

Ang pangunahing benepisyo ng CAR import ay ang preserbasyon ng CID. Maaari mong i-verify na magkatugma ang root CID bago at pagkatapos ng pag-upload:

# 1. I-pack ang direktoryo at itala ang root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. I-upload sa 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"
# ✓ Magkatugma ang mga CID — na-import ang nilalaman nang eksakto gaya ng pagkakagawa nito nang lokal

Paglipat Mula sa Ibang Provider

Mula sa Pinata

# I-export mula sa Pinata gamit ang IPFS gateway
ipfs dag export QmYourCID > export.car

# I-import sa 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}"

Mula sa Filebase

# Sinusuportahan ng Filebase ang CAR export sa pamamagitan ng kanilang S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# I-import sa 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}"

Mga Limitasyon

Limitasyon	Halaga
Maximum na laki ng CAR file	100 MB
Maximum na isang root	Dapat may kahit isang root CID
Format ng CAR	CARv1 (universally supported)
Availability	Lahat ng plan (Dharma, Bodhi, Nirvana)

Nalalapat ang mga limitasyon sa storage at bilang ng file mula sa iyong plan. Ang na-import na DAG ay binibilang bilang isang file entry, at ang laki ng CAR file ay ibinabawas mula sa iyong storage quota.

Pag-troubleshoot

"invalid CAR file: too small"

Ang na-upload na nilalaman ay mas mababa sa 40 bytes, na masyadong maliit para maging valid na CAR file. Siguraduhing ipinapadala mo ang buong base64-encoded na CAR na nilalaman.

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

Ang na-decode na CAR file ay lumampas sa 100 MB. Hatiin ang iyong nilalaman sa maraming mas maliliit na CAR file gamit ang package na carbites, o mag-upload ng mga file nang isa-isa.

"dag/import did not return a root CID"

Hindi naproseso ng IPFS node ang CAR file. I-verify na ang file ay isang valid na CARv1 archive:

ipfs-car roots my-archive.car

Kung nabigo ang command na ito, may mali ang format ng CAR file. Muling gawin ito gamit ang ipfs-car pack o ipfs dag export.

"not enough storage"

Naabot na ang limitasyon ng storage ng iyong plan. Magtanggal ng mga hindi ginagamit na file o mag-upgrade ng iyong plan sa ipfs.ninja/pricing.