Soubory

Nahrávání, seznam a získávání souborů na IPFS.

Nahrát soubor

POST /upload/new

Nahrajte jakýkoli soubor na IPFS. Soubor je připnut a vrácen trvalý CID.

Tělo požadavku

Parametr	Typ	Povinný	Popis
content	string | object	Ano	JSON objekt/pole, nebo data souboru kódovaná v base64 (obrázky, PDF, HTML nebo jakýkoli typ souboru). Pro import CAR jde o CAR soubor kódovaný v base64.
car	boolean	Ne	Nastavte na true pro import CAR souboru (import DAG struktury). Zachovává přesná CID.
description	string	Ne	Krátký popis nahraného obsahu.
metadata	object	Ne	Vlastní páry klíč-hodnota k připojení k souboru. Max 10 klíčů. Klíče musí být alfanumerické nebo podtržítko, 1-64 znaků. Hodnoty musí být řetězce, max 256 znaků. Celková velikost metadat nesmí přesáhnout 4 KB.

Příklad požadavku

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

Nahrání obrázku (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"
  }
}

Výchozí formát CIDv1

Nová nahrání vrací moderní CIDv1 (bafk… pro malý jednoblokový obsah, bafy… pro větší soubory a adresáře) podle profilu IPIP-0499 unixfs-v1-2025 — bloky po 1 MiB se surovými listy (raw leaves). Starší CID Qm… z dřívějších nahrání zůstávají plně přeložitelné a nadále fungují u každého endpointu.

Alternativa přes řídicí panel

Stránka /upload v řídicím panelu přijímá přetažením soubory, složky (zabalené v prohlížeči do UnixFS adresáře) i archivy .car — vše prochází přes tentýž endpoint. Podrobnosti o cestě CAR naleznete v Import CAR.

Přejmenování souboru

PUT /files/:cid/name

Aktualizujte zobrazovaný název souboru. CID se nemění — je to hash obsahu — mění se pouze štítek, který vidíte ve svém seznamu souborů.

Tělo požadavku

Parametr	Typ	Povinný	Popis
name	string	Ano	Nový zobrazovaný název. 1-200 znaků. Nesmí obsahovat oddělovače cest (/, \). Názvy tvořené pouze mezerami jsou odmítnuty.

Příklad požadavku

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

Řídicí panel

Stránka Soubory má v nabídce akcí každého řádku souboru (tlačítko se třemi tečkami) položku Přejmenovat. Stejný efekt, žádný kód není potřeba.

Seznam souborů

GET /upload/list

Získejte seznam vašich nahraných IPFS souborů v časovém rozsahu.

Parametry dotazu

Parametr	Typ	Povinný	Popis
from	number	Ano	Začátek časového rozsahu, Unix časové razítko v milisekundách.
to	number	Ano	Konec časového rozsahu, Unix časové razítko v milisekundách.

Příklad požadavku

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

Získat soubor

GET /file/:cid

Získejte metadata konkrétního nahraného souboru podle jeho CID.

Parametry cesty

Parametr	Typ	Povinný	Popis
cid	string	Ano	IPFS identifikátor obsahu souboru.

Příklad požadavku

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