Fail

Muat naik, senarai dan dapatkan semula fail di IPFS. Lihat pengesahan untuk persediaan kunci API, dan ralat untuk kod status HTTP.

Muat Naik Fail ke IPFS: 3 Langkah

1. Kodkan fail anda sebagai base64 (untuk imej/PDF) atau hantar objek JSON secara terus.
2. Hantar POST ke /upload/new dengan kunci API anda dalam header X-Api-Key.
3. Simpan cid yang dikembalikan — ia mengenal pasti fail anda secara kekal di IPFS.

POST /upload/new

Muat naik sebarang fail ke IPFS. Fail disemat dan CID kekal dikembalikan.

Badan permintaan

Parameter	Jenis	Diperlukan	Penerangan
content	string | object	Ya	Objek/tatasusunan JSON, atau data fail berkod base64 (imej, PDF, HTML, atau sebarang jenis fail). Untuk import CAR, fail CAR berkod base64.
car	boolean	Tidak	Tetapkan kepada true untuk mengimport fail CAR (import DAG). Mengekalkan CID yang tepat.
description	string	Tidak	Penerangan ringkas kandungan yang dimuat naik.
metadata	object	Tidak	Pasangan kunci-nilai tersuai untuk dilampirkan pada fail. Maks 10 kunci. Kunci mestilah alfanumerik atau garis bawah, 1-64 aksara. Nilai mestilah rentetan, maks 256 aksara setiap satu. Jumlah saiz metadata tidak boleh melebihi 4 KB.

Contoh permintaan

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": { "name": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

Memuat naik imej (base64)

const fs = require("fs");
const image = fs.readFileSync("photo.png").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: image,
    description: "Profile photo"
  })
});

Respons 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

CIDv1 secara lalai

Muat naik baharu mengembalikan CIDv1 moden (bafk… untuk kandungan blok tunggal yang kecil, bafy… untuk fail dan direktori yang lebih besar) mengikut profil IPIP-0499 unixfs-v1-2025 — cebisan 1 MiB dengan raw leaves. CID Qm… lama daripada muat naik terdahulu kekal boleh diselesaikan sepenuhnya dan terus berfungsi dengan setiap endpoint.

Alternatif papan pemuka

Halaman /upload papan pemuka menerima drag-and-drop untuk fail, folder (dibungkus menjadi direktori UnixFS dalam pelayar), dan arkib .car — semuanya melalui endpoint yang sama ini. Lihat Import CAR untuk butiran laluan CAR.

Jenis fail yang disokong

API menerima objek dan tatasusunan JSON secara terus, ditambah data binari berkod base64: imej (JPEG, PNG, GIF, WebP), PDF, HTML, dan sebarang jenis fail lain. Pelayan mengesan jenis kandungan secara automatik daripada muatan.

Medan respons

cid dalam respons ialah pengecam kandungan IPFS yang kekal. sizeMB ialah saiz yang disimpan dalam megabait. Objek uris mengandungi kedua-dua URI ipfs:// asli dan URL get laluan HTTPS untuk akses pelayar.

Namakan Semula Fail

PUT /files/:cid/name

Kemas kini nama paparan yang ditunjukkan pada fail. CID tidak berubah — ia adalah hash kandungan — hanya label yang anda lihat dalam senarai fail anda yang berubah.

Badan permintaan

Parameter	Jenis	Diperlukan	Penerangan
name	string	Ya	Nama paparan baharu. 1-200 aksara. Tidak boleh mengandungi pemisah laluan (/, \). Nama yang hanya mengandungi ruang kosong ditolak.

Contoh permintaan

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

Respons 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

Papan Pemuka

Halaman Fail mempunyai entri Rename dalam menu tindakan setiap baris fail (butang tiga titik). Kesan yang sama, tanpa perlu kod.

Senaraikan Fail

GET /upload/list

Dapatkan senarai fail IPFS anda yang dimuat naik dalam julat masa.

Parameter pertanyaan

Parameter	Jenis	Diperlukan	Penerangan
from	number	Ya	Permulaan julat masa, cap masa Unix dalam milisaat.
to	number	Ya	Akhir julat masa, cap masa Unix dalam milisaat.

Contoh permintaan

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

Respons 200 OK

[
  {
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

Dapatkan Fail

GET /file/:cid

Dapatkan metadata untuk fail yang dimuat naik tertentu mengikut CID-nya.

Parameter laluan

Parameter	Jenis	Diperlukan	Penerangan
cid	string	Ya	Pengecam kandungan IPFS bagi fail tersebut.

Contoh permintaan

curl https://api.ipfs.ninja/file/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi \
  -H "X-Api-Key: bws_your_api_key_here"

Respons 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "fileName": "Test upload",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}