FAQ

Häufig gestellte Fragen zu IPFS Ninja.

Allgemein

Was ist IPFS Ninja?

IPFS Ninja ist ein verwalteter IPFS-Pinning-Dienst. Sie laden eine beliebige Datei über eine einfache REST API hoch oder pinnen bestehende CIDs aus dem IPFS-Netzwerk. Jede Datei erhält einen permanenten Content Identifier (CID) und ist über unser Gateway unter ipfs.ninja/ipfs/<CID> zugänglich.

Bedient ipfs.ninja/ipfs/<CID> jeden CID im IPFS-Netzwerk?

Nein. Das Apex-Gateway bedient nur CIDs, die von einem IPFS-Ninja-Nutzer hochgeladen oder gepinnt wurden. Anfragen für unbekannte CIDs geben HTTP 410 Gone zurück, mit einem Verweis auf öffentliche IPFS-Gateways (ipfs.io, dweb.link). Um einen Drittpartei-CID über unser Gateway bereitzustellen, pinnen Sie ihn zuerst mit POST /pin an Ihr Konto — nach dem Pinnen ist der CID sowohl unter der Apex-URL als auch unter Ihrer dedizierten Gateway-URL erreichbar.

Was ist der Unterschied zwischen dem Apex-Gateway und dem dedizierten Gateway?

Aspekt	Apex ipfs.ninja/ipfs/<CID>	Dediziert <slug>.gw.ipfs.ninja/ipfs/<CID>
Umfang	Für alle Nutzer geteilt	Nur Ihre CIDs
Authentifizierung	Keine	Optionaler Token / IP-Allowlist / Origin-Allowlist
SLA	Best Effort	Volle SLA
Empfohlen für	Gelegentliche Links	Produktionseinbettung (NFT, Video, Websites)
Ratenlimits	Geteilt pro IP + pro CID	Pro Plan, konfigurierbar

Beide liefern identische Inhalte. Für Produktionsverkehr verwenden Sie das dedizierte Gateway.

Welche Dateitypen werden unterstützt?

Alle Dateitypen werden unterstützt. JSON-Objekte und -Arrays können direkt gesendet werden. Alle anderen Dateien (Bilder, PDFs, HTML, Video, Audio, Binärdateien) werden als base64-kodierter Inhalt gesendet.

Gibt es eine Dateigrößenbeschränkung?

Einzelne Uploads sind durch das Speicherkontingent Ihres Plans begrenzt. Es gibt keine Dateigrößenbeschränkung pro Datei über Ihren verfügbaren Speicherplatz hinaus.

Kann ich Inhalte pinnen, die bereits auf IPFS existieren?

Ja. Verwenden Sie POST /pin mit einem beliebigen gültigen CID. Unser Cluster ruft den Inhalt aus dem IPFS-Netzwerk ab und pinnt ihn an Ihr Konto. Weitere Details finden Sie in der Pinning-API-Dokumentation.

Wie lange dauert das Pinning?

Das hängt von der Dateigröße ab und davon, wie viele IPFS-Knoten den Inhalt haben. Kleine, gut verteilte Dateien werden in Sekunden gepinnt. Große oder selten gepinnte Inhalte können einige Minuten dauern. Der Pin-Endpunkt gibt sofort den Status pinning zurück — fragen Sie GET /pin/:cid ab, um den Fortschritt zu prüfen.

Was passiert, wenn ein CID nicht gefunden werden kann?

Der Status ändert sich zu failed. Das bedeutet, dass der CID entweder ungültig ist oder der Inhalt auf keinem erreichbaren IPFS-Knoten mehr verfügbar ist.

Sind auf IPFS hochgeladene Daten öffentlich?

Ja. Alle auf IPFS gepinnten Inhalte sind öffentlich über ihren CID über jedes IPFS-Gateway zugänglich. Wenn Sie privaten Zugang benötigen, verwenden Sie ein dediziertes Gateway mit Token-Pflicht-Modus — dies beschränkt den Zugriff über Ihr Gateway, obwohl der Inhalt im breiteren IPFS-Netzwerk weiterhin verfügbar bleibt.

Warum haben sich meine neuen CIDs von Qm... zu bafy... geändert?

Neue Uploads und Pins 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: CIDv1-base32-Kodierung, 1-MiB-Chunks, Raw Leaves. Dies entspricht dem, was moderne Tools (Helia, aktuelles Kubo, ipfs-car) für denselben Inhalt erzeugen, sodass eine bei uns hochgeladene Datei denselben CID erhält, den auch jeder moderne Client für dieselben Bytes berechnen würde.

Ältere Qm…-CIDs aus früheren Uploads bleiben vollständig auflösbar — das Gateway, POST /pin, GET /file, IPNS und jeder andere Endpunkt akzeptieren beide Formate unbegrenzt weiter. Nichts, was Sie bereits haben, hört auf zu funktionieren.

Wie pinne ich Inhalte, die auf einem privaten / Nicht-DHT-Knoten liegen?

POST /pin akzeptiert optional multiaddresses[] (bis zu 5). Falls angegeben, führt unser Cluster für jeden Hinweis ipfs swarm connect <multiaddr> aus, bevor der Pin läuft, sodass Inhalte auf Peers, die nicht über die öffentliche DHT beworben werden (private Knoten, Staging-Umgebungen, VPN-lokale Maschinen), erreichbar sind. Siehe den Leitfaden Von einem privaten IPFS-Knoten pinnen.

Bleiben meine Dateien auf IPFS, wenn ich mein Konto kündige?

Wir lösen das Pinning Ihrer Dateien von unseren Knoten, wenn Sie kündigen. Wenn andere IPFS-Knoten Ihren Inhalt zwischengespeichert haben, kann er weiterhin zugänglich sein. Ohne aktives Pinning werden Dateien jedoch schließlich durch die Garbage Collection im Netzwerk entfernt.

Authentifizierung & API

Wie authentifiziere ich API-Anfragen?

Übergeben Sie Ihren API-Schlüssel über den X-Api-Key-Header. Generieren Sie Schlüssel auf der Seite API-Schlüssel in Ihrem Dashboard.

Gibt es API-Ratenbeschränkungen?

Nein. IPFS Ninja legt keine Ratenbeschränkungen für API-Anfragen fest. Sie können beliebig viele Anfragen in jedem Plan stellen.

Laufen API-Schlüssel ab?

Nein. API-Schlüssel sind gültig, bis Sie sie löschen. Sie können mehrere Schlüssel erstellen und sie einzeln widerrufen.

Was ist der Unterschied zwischen API-Schlüsseln und Gateway-Token?

API-Schlüssel (bws_) haben vollen Zugriff — hochladen, löschen, Dateien auflisten. Gateway-Token (gwt_) sind schreibgeschützt und können nur über Ihr dediziertes Gateway auf Dateien zugreifen. Gateway-Token können sicher in Frontend-Anwendungen eingebettet werden.

Dedizierte Gateways

Was ist ein dediziertes Gateway?

Ein privates IPFS-Gateway unter Ihrer eigenen Subdomain (z. B. abc123.gw.ipfs.ninja), das nur Dateien ausliefert, die an Ihr Konto gepinnt sind. Im Gegensatz zum öffentlichen Gateway werden keine CIDs anderer Benutzer aufgelöst.

Welche Pläne beinhalten ein dediziertes Gateway?

Dedizierte Gateways sind in allen kostenpflichtigen Plänen verfügbar (Bodhi 5 $/Monat, Karma 19 $/Monat, Nirvana 59 $/Monat). Das monatliche Bandbreitenkontingent jedes Plans deckt den Datenverkehr sowohl über das Apex- als auch über das dedizierte Gateway ab. Siehe „Gibt es Bandbreitengebühren?" unten für die Kontingente je Plan.

Kann ich einschränken, wer auf mein Gateway zugreift?

Ja. Sie können den Token-Pflicht-Modus aktivieren (erfordert ein gwt_-Token bei jeder Anfrage) und/oder eine IP-Whitelist einrichten (bis zu 100 Adressen).

Kann ich mein Gateway nach Origin/Domain einschränken?

Ja. Konfigurieren Sie allowedOrigins in Ihren Gateway-Einstellungen mit einer Liste von HTTPS-Origins. Nur Browseranfragen von diesen Origins werden zugelassen. Nicht-Browser-Anfragen (ohne Origin-Header) werden durchgelassen. Eine leere Liste erlaubt alle Origins.

Was sind signierte Upload-Token?

Signierte Upload-Token sind zeitlich begrenzte Anmeldeinformationen für clientseitige Uploads. Sie generieren sie auf Ihrem Server mit POST /upload/signed-url und übergeben sie an Browser oder mobile Apps. Der Client authentifiziert sich mit Authorization: Signed <token> anstatt Ihren API-Schlüssel preiszugeben. Jeder Token verfolgt die Nutzung und läuft automatisch ab. Siehe die Dokumentation zu signierten Token für Details.

Kann ich Bilder optimieren, die von IPFS bereitgestellt werden?

Ja. Verwenden Sie GET /image/:cid mit Abfrageparametern wie w, h, format und quality, um Bilder on-the-fly zu skalieren, zu konvertieren und zu komprimieren. Antworten werden basierend auf dem inhaltsadressierten CID zwischengespeichert. Dies funktioniert in allen Plänen. Siehe Bildoptimierung.

Kann ich Metadaten an Dateien anhängen?

Ja. Fügen Sie ein metadata-Objekt mit bis zu 10 Schlüssel-Wert-Paaren hinzu, wenn Sie über POST /upload/new hochladen oder über POST /pin pinnen. Metadaten werden in Dateilisten und im Dateidetail-Endpunkt zurückgegeben. Siehe die Dokumentation zu Dateien und Pinning.

Abrechnung & Pläne

Gibt es einen kostenlosen Plan?

Ja. Der Dharma-Plan ist für immer kostenlos — 1 GB Speicher, unbegrenzte API-Anfragen, keine Kreditkarte erforderlich.

Gibt es Bandbreitengebühren?

Keine verbrauchsabhängigen Bandbreitengebühren in irgendeinem Plan. Jeder Plan enthält ein monatliches Gateway-Bandbreitenkontingent, das eine feste Obergrenze darstellt — Ihr Inhalt wird über das Apex- und das dedizierte Gateway nicht mehr ausgeliefert, sobald das Kontingent erreicht ist, und die Auslieferung setzt am 1. des nächsten Monats oder nach einem Upgrade wieder ein:

Plan	Monatliche Bandbreite
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

Sie erhalten Warn-E-Mails bei 80 % und 100 % Ihres Kontingents.

Wird der Speicher zurückgesetzt?

Der Speicher wird nicht zurückgesetzt. Ihr Plan umfasst ein Gesamtspeicherkontingent (Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB). Um Platz freizugeben, löschen Sie Dateien, die Sie nicht mehr benötigen. Ein Upgrade Ihres Plans erhöht Ihr Gesamtkontingent.

Kann ich jederzeit kündigen?

Ja. Kündigen Sie Ihr Abonnement über das Abrechnungsportal — keine Bindung. Ihr Konto wird auf den kostenlosen Tarif zurückgesetzt, und bestehende gepinnte Dateien bleiben zugänglich.

Was passiert mit meinen Dateien, wenn ich downgrade?

Ihre Dateien bleiben auf IPFS gepinnt, aber Sie können nicht mehr hochladen, wenn Ihre aktuelle Nutzung das Speicherlimit des neuen Plans überschreitet. Löschen Sie Dateien, um wieder unter das Limit zu kommen.

Sicherheit

Sind meine Daten verschlüsselt?

Alle Daten werden während der Übertragung über TLS/HTTPS verschlüsselt. Die Authentifizierung verwendet JWT-Token (Cognito) und sicher gespeicherte API-Schlüssel. Dateiinhalte auf IPFS werden nicht im Ruhezustand verschlüsselt — IPFS ist designbedingt ein öffentliches Netzwerk.

Ist es sicher, API-Schlüssel in meinem serverseitigen Code zu verwenden?

Ja. API-Schlüssel sind für die serverseitige Verwendung konzipiert. Geben Sie sie niemals in clientseitigem Code preis. Verwenden Sie für den clientseitigen Dateizugriff Gateway-Token (gwt_), die schreibgeschützt sind.

Support

Wie erhalte ich Hilfe?

Senden Sie eine E-Mail an info@ipfs.ninja oder lesen Sie die Dokumentation der API-Referenz.

Gibt es ein SLA?

Wir streben eine hohe Verfügbarkeit an, bieten derzeit jedoch kein formelles SLA an. Der Dienst wird auf einer „wie besehen"-Basis bereitgestellt.