Mga File

Mag-upload, maglista, at kumuha ng mga file sa IPFS. Tingnan ang authentication para sa setup ng API key, at errors para sa mga HTTP status code.

Mag-upload ng File sa IPFS: 3 Hakbang

1. I-encode ang iyong file bilang base64 (para sa mga imahe/PDF) o direktang magpasa ng JSON object.
2. Mag-POST sa /upload/new gamit ang iyong API key sa X-Api-Key header.
3. I-save ang naibalik na cid — ito ang permanenteng nagtatakda ng identidad ng iyong file sa IPFS.

POST /upload/new

Mag-upload ng anumang file sa IPFS. Napi-pin ang file at ibinabalik ang permanenteng CID.

Request body

Parameter	Uri	Kinakailangan	Paglalarawan
content	string | object	Oo	JSON object/array, o base64-encoded file data (imahe, PDF, HTML, o anumang uri ng file). Para sa mga CAR import, base64-encoded na CAR file.
car	boolean	Hindi	Itakda sa true para mag-import ng CAR file (DAG import). Pinapanatili ang eksaktong mga CID.
description	string	Hindi	Maikling paglalarawan ng na-upload na nilalaman.
metadata	object	Hindi	Custom key-value pairs na ila-attach sa file. Max 10 key. Ang mga key ay dapat alphanumeric o underscore, 1-64 character. Ang mga value ay dapat string, max 256 character bawat isa. Ang kabuuang laki ng metadata ay hindi dapat lumagpas sa 4 KB.

Halimbawang request

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

Pag-upload ng imahe (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"
  })
});

Response 200 OK

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

CIDv1 bilang default

Ang mga bagong upload ay nagbabalik ng modernong CIDv1 (bafk… para sa maliit na single-block na nilalaman, bafy… para sa mas malalaking file at directory) ayon sa IPIP-0499 unixfs-v1-2025 profile — 1 MiB na chunks na may raw leaves. Ang legacy Qm… na mga CID mula sa mga naunang upload ay nananatiling ganap na resolvable at patuloy na gumagana sa bawat endpoint.

Alternatibong Dashboard

Ang /upload page ng dashboard ay tumatanggap ng drag-and-drop para sa mga file, folder (pinapackage sa isang UnixFS directory sa browser), at mga .car archive — lahat ay dumadaan sa parehong endpoint na ito. Tingnan ang CAR Import para sa mga detalye tungkol sa CAR path.

Mga uri ng file na sinusuportahan

Tinatanggap ng API ang JSON object at array nang direkta, kasama ang mga base64-encoded na binary file: imahe (JPEG, PNG, GIF, WebP), PDF, HTML, at anumang iba pang uri ng file. Awtomatikong nade-detect ng server ang content type mula sa payload.

Mga field sa response

Ang cid sa response ay ang permanenteng IPFS content identifier. Ang sizeMB ay ang na-store na laki sa megabytes. Ang uris object ay naglalaman ng parehong native ipfs:// URI at isang HTTPS gateway URL para sa browser access.

Palitan ang Pangalan ng File

PUT /files/:cid/name

I-update ang display name na ipinapakita sa isang file. Hindi nagbabago ang CID — ito ay hash ng nilalaman — ang label lamang na nakikita mo sa iyong file list ang nagbabago.

Request body

Parameter	Uri	Kinakailangan	Paglalarawan
name	string	Oo	Bagong display name. 1-200 character. Hindi dapat maglaman ng path separators (/, \). Tinatanggihan ang mga pangalan na puro whitespace lang.

Halimbawang request

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

Response 200 OK

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

Dashboard

Ang Files page ay may Rename na entry sa action menu ng bawat file row (three-dot button). Parehong epekto, walang kailangang code.

Ilista ang mga File

GET /upload/list

Kunin ang listahan ng iyong na-upload na IPFS file sa loob ng isang time range.

Mga query parameter

Parameter	Uri	Kinakailangan	Paglalarawan
from	number	Oo	Simula ng time range, Unix timestamp sa milliseconds.
to	number	Oo	Katapusan ng time range, Unix timestamp sa milliseconds.

Halimbawang request

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

Response 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"
    }
  }
]

Kunin ang File

GET /file/:cid

Kunin ang metadata para sa isang partikular na na-upload na file gamit ang CID nito.

Mga path parameter

Parameter	Uri	Kinakailangan	Paglalarawan
cid	string	Oo	Ang IPFS content identifier ng file.

Halimbawang request

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

Response 200 OK

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