Fișiere

Încărcați, listați și accesați fișiere pe IPFS.

Încărcare fișier

POST /upload/new

Încărcați orice fișier pe IPFS. Fișierul este fixat și un CID permanent este returnat.

Corpul cererii

Parametru	Tip	Obligatoriu	Descriere
content	string | object	Da	Obiect/array JSON, sau date fișier codificate base64 (imagini, PDF-uri, HTML sau orice tip de fișier). Pentru importuri CAR, fișier CAR codificat base64.
car	boolean	Nu	Setați la true pentru a importa un fișier CAR (import DAG). Păstrează CID-urile exacte.
description	string	Nu	Descriere scurtă a conținutului încărcat.
metadata	object	Nu	Perechi cheie-valoare personalizate de atașat la fișier. Max 10 chei. Cheile trebuie să fie alfanumerice sau underscore, 1-64 caractere. Valorile trebuie să fie șiruri, max 256 caractere fiecare. Dimensiunea totală a metadatelor nu trebuie să depășească 4 KB.

Exemplu de cerere

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

Încărcarea unei imagini (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 implicit

Încărcările noi returnează CIDv1 modern (bafk… pentru conținut mic, cu un singur bloc, bafy… pentru fișiere și directoare mai mari) conform profilului IPIP-0499 unixfs-v1-2025 — bucăți de 1 MiB cu frunze brute. CID-urile vechi Qm… din încărcările anterioare rămân complet rezolvabile și continuă să funcționeze cu fiecare endpoint.

Alternativă din dashboard

Pagina /upload din dashboard acceptă tragere și plasare pentru fișiere, foldere (împachetate într-un director UnixFS în browser) și arhive .car — toate rutate prin același endpoint. Consultați Import CAR pentru detalii despre calea CAR.

Redenumirea unui fișier

PUT /files/:cid/name

Actualizați numele afișat pentru un fișier. CID-ul nu se schimbă — este un hash al conținutului — doar eticheta pe care o vedeți în lista dvs. de fișiere.

Corpul cererii

Parametru	Tip	Obligatoriu	Descriere
name	string	Da	Numele afișat nou. 1-200 caractere. Nu trebuie să conțină separatori de cale (/, \). Numele formate doar din spații albe sunt respinse.

Exemplu de cerere

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

Pagina Fișiere are o intrare Redenumire în meniul de acțiuni al fiecărui rând de fișier (butonul cu trei puncte). Același efect, fără a scrie cod.

Listare fișiere

GET /upload/list

Obțineți o listă a fișierelor IPFS încărcate într-un interval de timp.

Parametri de interogare

Parametru	Tip	Obligatoriu	Descriere
from	number	Da	Începutul intervalului de timp, timestamp Unix în milisecunde.
to	number	Da	Sfârșitul intervalului de timp, timestamp Unix în milisecunde.

Exemplu de cerere

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

Obținere fișier

GET /file/:cid

Obțineți metadatele unui fișier încărcat specific după CID-ul său.

Parametri de cale

Parametru	Tip	Obligatoriu	Descriere
cid	string	Da	Identificatorul de conținut IPFS al fișierului.

Exemplu de cerere

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