Dateien

Dateien auf IPFS hochladen, auflisten und abrufen.

Datei hochladen

POST /upload/new

Laden Sie eine beliebige Datei auf IPFS hoch. Die Datei wird gepinnt und ein permanenter CID wird zurückgegeben.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
content	string | object	Ja	JSON-Objekt/-Array oder base64-kodierte Dateidaten (Bilder, PDFs, HTML oder jeder andere Dateityp). Für CAR-Importe: base64-kodierte CAR-Datei.
car	boolean	Nein	Auf true setzen, um eine CAR-Datei (DAG-Import) zu importieren. Erhält exakte CIDs.
description	string	Nein	Kurze Beschreibung des hochgeladenen Inhalts.
metadata	object	Nein	Benutzerdefinierte Schlüssel-Wert-Paare, die an die Datei angehängt werden. Max. 10 Schlüssel. Schlüssel müssen alphanumerisch oder Unterstrich sein, 1-64 Zeichen. Werte müssen Strings sein, max. 256 Zeichen pro Wert. Gesamte Metadatengröße darf 4 KB nicht überschreiten.

Beispielanfrage

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

Ein Bild hochladen (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"
  })
});

Antwort 200 OK

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

CIDv1 standardmäßig

Neue Uploads geben moderne CIDv1 zurück (bafk… für kleine Einzelblock-Inhalte, bafy… für größere Dateien und Verzeichnisse) gemäß dem IPIP-0499 unixfs-v1-2025-Profil — 1-MiB-Chunks mit Raw Leaves. Ältere Qm…-CIDs aus früheren Uploads bleiben vollständig auflösbar und funktionieren weiterhin mit jedem Endpunkt.

Alternative über das Dashboard

Die /upload-Seite des Dashboards akzeptiert Drag-and-Drop für Dateien, Ordner (im Browser zu einem UnixFS-Verzeichnis gepackt) und .car-Archive — alle laufen über denselben Endpunkt. Siehe CAR Import für Details zum CAR-Pfad.

Datei umbenennen

PUT /files/:cid/name

Aktualisiert den bei einer Datei angezeigten Namen. Der CID ändert sich nicht — er ist ein Hash des Inhalts — nur die Bezeichnung, die Sie in Ihrer Dateiliste sehen.

Anfragekörper

Parameter	Typ	Erforderlich	Beschreibung
name	string	Ja	Neuer Anzeigename. 1-200 Zeichen. Darf keine Pfadtrennzeichen enthalten (/, \). Namen, die nur aus Leerzeichen bestehen, werden abgelehnt.

Beispielanfrage

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

Antwort 200 OK

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

Dashboard

Die Dateien-Seite hat einen Umbenennen-Eintrag im Aktionsmenü jeder Dateizeile (Drei-Punkte-Schaltfläche). Gleicher Effekt, kein Code erforderlich.

Dateien auflisten

GET /upload/list

Rufen Sie eine Liste Ihrer hochgeladenen IPFS-Dateien innerhalb eines Zeitraums ab.

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
from	number	Ja	Beginn des Zeitraums, Unix-Zeitstempel in Millisekunden.
to	number	Ja	Ende des Zeitraums, Unix-Zeitstempel in Millisekunden.

Beispielanfrage

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

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

Datei abrufen

GET /file/:cid

Rufen Sie Metadaten für eine bestimmte hochgeladene Datei anhand ihres CID ab.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
cid	string	Ja	Der IPFS Content Identifier der Datei.

Beispielanfrage

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

Antwort 200 OK

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