Datoteke

Prijenos, popis i dohvat datoteka na IPFS-u. Pogledajte autentifikacija za postavljanje API ključa, te greške za HTTP statusne kodove.

Prijenos Datoteke na IPFS: 3 Koraka

1. Kodirajte datoteku u base64 (za slike/PDF-ove) ili proslijedite izravno JSON objekt ili polje.
2. Pošaljite POST zahtjev na /upload/new s API ključem u zaglavlju X-Api-Key.
3. Sačuvajte vraćeni cid — on trajno identificira vašu datoteku na IPFS-u.

POST /upload/new

Prenesite bilo koju datoteku na IPFS. Datoteka se prikvačuje i vraća se trajni CID.

Tijelo zahtjeva

Parametar	Tip	Obavezno	Opis
content	string | object	Da	JSON objekt/polje, ili base64-kodirani podaci datoteke (slike, PDF-ovi, HTML ili bilo koji tip datoteke). Za uvoz CAR datoteka, base64-kodirana CAR datoteka.
car	boolean	Ne	Postavite na true za uvoz CAR datoteke (uvoz DAG-a). Čuva točne CID-ove.
description	string	Ne	Kratki opis prenesenog sadržaja.
metadata	object	Ne	Prilagođeni parovi ključ-vrijednost za prilaganje datoteci. Maks. 10 ključeva. Ključevi moraju biti alfanumerički ili podvlaka, 1-64 znaka. Vrijednosti moraju biti nizovi znakova, maks. 256 znakova. Ukupna veličina metapodataka ne smije premašiti 4 KB.

Primjer zahtjeva

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

Prijenos slike (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 prema zadanim postavkama

Novi prijenosi vraćaju moderni CIDv1 (bafk… za manji sadržaj u jednom bloku, bafy… za veće datoteke i direktorije) prema profilu IPIP-0499 unixfs-v1-2025 — dijelovi od 1 MiB sa sirovim listovima (raw leaves). Stariji Qm… CID-ovi iz ranijih prijenosa i dalje su u potpunosti razrješivi i nastavljaju raditi sa svakim endpointom.

Alternativa putem nadzorne ploče

Stranica /upload na nadzornoj ploči prihvaća povlačenje i ispuštanje (drag-and-drop) za datoteke, mape (pakirane u UnixFS direktorij u pregledniku) i .car arhive — sve prolazi kroz isti ovaj endpoint. Pogledajte Uvoz CAR datoteka za detalje o CAR putanji.

Podržani tipovi datoteka

API izravno prihvaća JSON objekte i polja, kao i base64-kodirane binarne datoteke: slike (JPEG, PNG, GIF, WebP), PDF-ove, HTML i bilo koji drugi tip datoteke. Poslužitelj automatski prepoznaje tip sadržaja na temelju poslanog sadržaja.

Polja odgovora

Polje cid u odgovoru je trajni IPFS identifikator sadržaja. sizeMB je pohranjena veličina u megabajtima. Objekt uris sadrži i izvorni ipfs:// URI i HTTPS gateway URL za pristup putem preglednika.

Preimenovanje datoteke

PUT /files/:cid/name

Ažurirajte prikazani naziv datoteke. CID se ne mijenja — to je hash sadržaja — mijenja se samo oznaka koju vidite u popisu datoteka.

Tijelo zahtjeva

Parametar	Tip	Obavezno	Opis
name	string	Da	Novi prikazani naziv. 1-200 znakova. Ne smije sadržavati separatore putanje (/, \). Nazivi koji sadrže samo razmake se odbijaju.

Primjer zahtjeva

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

Nadzorna ploča

Stranica Datoteke ima stavku Preimenuj u izborniku radnji svakog retka datoteke (gumb s tri točkice). Isti učinak, bez potrebe za kodom.

Popis datoteka

GET /upload/list

Dohvatite popis vaših prenesenih IPFS datoteka unutar vremenskog raspona.

Parametri upita

Parametar	Tip	Obavezno	Opis
from	number	Da	Početak vremenskog raspona, Unix vremenski žig u milisekundama.
to	number	Da	Kraj vremenskog raspona, Unix vremenski žig u milisekundama.

Primjer zahtjeva

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

Dohvat datoteke

GET /file/:cid

Dohvatite metapodatke određene prenesene datoteke prema njezinom CID-u.

Parametri putanje

Parametar	Tip	Obavezno	Opis
cid	string	Da	IPFS identifikator sadržaja datoteke.

Primjer zahtjeva

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