Pliki

Przesyłaj, wyświetlaj i pobieraj pliki na IPFS.

Prześlij plik

POST /upload/new

Prześlij dowolny plik do IPFS. Plik jest przypinany, a zwracany jest trwały CID.

Treść żądania

Parametr	Typ	Wymagany	Opis
content	string | object	Tak	Obiekt/tablica JSON lub dane pliku zakodowane w base64 (obrazy, PDF-y, HTML lub dowolny typ pliku). Dla importów CAR — plik CAR zakodowany w base64.
car	boolean	Nie	Ustaw na true, aby zaimportować plik CAR (import DAG). Zachowuje dokładne CID-y.
description	string	Nie	Krótki opis przesłanej treści.
metadata	object	Nie	Niestandardowe pary klucz-wartość dołączane do pliku. Maksymalnie 10 kluczy. Klucze muszą być alfanumeryczne lub zawierać podkreślenie, 1-64 znaki. Wartości muszą być ciągami znaków, maksymalnie 256 znaków każda. Łączny rozmiar metadanych nie może przekraczać 4 KB.

Przykładowe żądanie

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

Przesyłanie obrazu (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"
  })
});

Odpowiedź 200 OK

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

CIDv1 domyślnie

Nowe przesłania zwracają nowoczesne CIDv1 (bafk… dla małej, jednoblokowej treści, bafy… dla większych plików i katalogów) zgodnie z profilem IPIP-0499 unixfs-v1-2025 — fragmenty 1 MiB z surowymi liśćmi (raw leaves). Starsze CID-y Qm… z wcześniejszych przesłań pozostają w pełni rozwiązywalne i nadal działają z każdym endpointem.

Alternatywa: dashboard

Strona /upload w dashboardzie akceptuje przeciąganie i upuszczanie plików, folderów (pakowanych do katalogu UnixFS w przeglądarce) i archiwów .car — wszystko przechodzi przez ten sam endpoint. Zobacz Import CAR po szczegóły dotyczące ścieżki CAR.

Zmień nazwę pliku

PUT /files/:cid/name

Zaktualizuj nazwę wyświetlaną pliku. CID się nie zmienia — jest to hash treści — zmienia się tylko etykieta widoczna na liście plików.

Treść żądania

Parametr	Typ	Wymagany	Opis
name	string	Tak	Nowa nazwa wyświetlana. 1-200 znaków. Nie może zawierać separatorów ścieżki (/, \). Nazwy składające się wyłącznie z białych znaków są odrzucane.

Przykładowe żądanie

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

Odpowiedź 200 OK

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

Dashboard

Strona Pliki ma pozycję Zmień nazwę w menu akcji każdego wiersza pliku (przycisk z trzema kropkami). Ten sam efekt, bez potrzeby kodu.

Lista plików

GET /upload/list

Pobierz listę przesłanych plików IPFS w danym przedziale czasu.

Parametry zapytania

Parametr	Typ	Wymagany	Opis
from	number	Tak	Początek przedziału czasu, znacznik czasu Unix w milisekundach.
to	number	Tak	Koniec przedziału czasu, znacznik czasu Unix w milisekundach.

Przykładowe żądanie

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

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

Pobierz plik

GET /file/:cid

Pobierz metadane konkretnego przesłanego pliku po jego CID.

Parametry ścieżki

Parametr	Typ	Wymagany	Opis
cid	string	Tak	Identyfikator treści IPFS danego pliku.

Przykładowe żądanie

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

Odpowiedź 200 OK

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