Pinning

Pinnen Sie bestehende IPFS-Inhalte an Ihr Konto. Wenn Sie einen CID pinnen, ruft unser Cluster den Inhalt aus dem IPFS-Netzwerk ab und hält ihn permanent verfügbar.

Nach CID pinnen

POST /pin

Parameter	Typ	Erforderlich	Beschreibung
cid	string	Ja	IPFS Content Identifier. Jede Form wird akzeptiert: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… und andere Codecs).
description	string	Nein	Kurze Beschreibung als Referenz.
metadata	object	Nein	Benutzerdefinierte Schlüssel-Wert-Paare, die an den Pin 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.
multiaddresses	string[]	Nein	Optionale Swarm-Connect-Hinweise. Bis zu 5 libp2p-Multiadressen von Peers, die den CID hosten. Unser Cluster führt swarm connect gegen jede davon parallel aus, bevor gepinnt wird, sodass Inhalte auf privaten / Nicht-DHT-Peers erreichbar sind, ohne auf die DHT-Erkennung zu warten. Best-effort — ein fehlgeschlagener Connect lässt den Pin nicht scheitern. Siehe Pinnen von einem privaten Knoten.

Beispielanfrage

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Antwort 202 Accepted

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "description": "NFT metadata",
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Bei großen DAGs (>500 Blöcke oder >50 MB) enthält die Antwort ein async: true-Flag:

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "async": true,
  "note": "Large DAG detected — pin running in background. Check status via GET /pin/bafybei…",
  "uris": { ... }
}

Pinnen von einem privaten Knoten

Wenn der CID, den Sie pinnen möchten, auf einem Peer liegt, der nicht an der öffentlichen DHT teilnimmt — ein privater Staging-Knoten, eine selbst gehostete Maschine in einem VPN oder ein Arbeitsplatzrechner hinter NAT —, findet der Standard-Pin-Ablauf ihn nicht. Die Übergabe einer oder mehrerer multiaddresses teilt unserem Cluster genau mit, wo gesucht werden soll.

Wir führen ipfs swarm connect <multiaddr> für jeden Hinweis parallel aus, bevor der Pin läuft. Gelingt der Connect, kann der DAG-Abruf des Pins direkt mit Ihrem Peer sprechen, statt die DHT zu durchsuchen. Schlägt er fehl, läuft der Pin trotzdem gegen das öffentliche Netzwerk weiter (Best-effort-Semantik).

Beispiel: von einem bestimmten Peer pinnen

curl -X POST https://api.ipfs.ninja/pin \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

Antwort enthält Status pro Hinweis

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinning",
  "swarmConnected": [
    { "multiaddr": "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooW…", "ok": true,  "strings": ["connect 12D3KooW… success"] },
    { "multiaddr": "/dns4/node.internal.example/tcp/443/…",   "ok": false, "error": "dial to peer: no route" }
  ],
  "uris": { … }
}

Akzeptierte Multiadress-Formen

Gängige Formen werden unterstützt: /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr-Transporte; /tcp- oder /udp-Protokolle; optionale /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct-Upgrades. Die Multiadresse muss mit /p2p/<peerId> enden. Obergrenze: bis zu 5 Hinweise pro Pin.

Die Multiadresse Ihres Knotens ermitteln

Führen Sie auf dem Peer, von dem Sie pinnen möchten, ipfs id aus und kopieren Sie einen der Addresses-Einträge, der auf /p2p/<PeerID> endet. Bevorzugen Sie öffentlich routbare Adressen (/ip4/YOUR_PUBLIC_IP/…) oder DNS-basierte (/dnsaddr/your.domain/…), damit unser Cluster den Peer von AWS aus erreichen kann.

Pinnen sehr großer Verzeichnisse

POST /pin ist für Inhalte gedacht, die bereits im IPFS-Netzwerk vorhanden sind — der Cluster ruft den DAG Block für Block von Peers ab, was bei Verzeichnissen mit 1.000+ Dateien mehrere Minuten dauern kann. Während dieses Abruffensters sind einige untergeordnete Dateien möglicherweise noch nicht lokal verfügbar, und Gateway-Anfragen dazu können in ein Timeout laufen. Sobald der status des übergeordneten Elements auf pinned wechselt, ist jede untergeordnete Datei lokal verfügbar und über Ihr Gateway zugänglich.

Wenn Sie die Dateien lokal vorliegen haben (statt nur einen CID), bevorzugen Sie für große NFT-Sammlungen oder Datensätze den CAR Import — er lädt den gesamten DAG in einer einzigen atomaren Anfrage zu IPFS Ninja hoch, sodass es kein Abruffenster und keinen teilweise gepinnten Zustand gibt. Erstellen Sie eine CAR-Datei mit:

npx ipfs-car pack ./my-collection -o collection.car

Importieren Sie sie dann über POST /upload/new mit car: true.

TIP

Pinning ist asynchron. Die Antwort wird sofort mit dem Status pinning zurückgegeben. Fragen Sie den Status-Endpunkt ab, um zu prüfen, wann das Pinning abgeschlossen ist.

Pin-Status prüfen

GET /pin/:cid

Parameter	Typ	Erforderlich	Beschreibung
cid	string	Ja	Der CID, den Sie prüfen.

Antwort 200 OK

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

Statuswerte

Status	Bedeutung
pinning	Inhalt wird aus dem IPFS-Netzwerk abgerufen. Fragen Sie in einigen Sekunden erneut ab.
pinned	Inhalt ist gepinnt und über Ihr Konto und Gateway verfügbar.
failed	Inhalt konnte im IPFS-Netzwerk nicht gefunden werden. Der CID ist möglicherweise ungültig oder der Inhalt ist nicht mehr verfügbar.

Wie Pinning funktioniert

1. Sie senden einen CID über POST /pin
2. Unser IPFS-Cluster durchsucht das Netzwerk nach Knoten, die den Inhalt haben
3. Der Cluster lädt den Inhalt herunter und pinnt ihn lokal
4. Sobald gepinnt, erscheint die Datei in Ihrer Dateiliste und ist über das Gateway zugänglich
5. Die Speichernutzung wird nach Abschluss des Pinnings erfasst

WARNING

Die Pinning-Zeit hängt von der Dateigröße und der Netzwerkverfügbarkeit ab. Kleine Dateien werden typischerweise in Sekunden gepinnt. Große Dateien oder selten gepinnte Inhalte können Minuten dauern.

Speicher

Gepinnter Inhalt zählt zum Speicherlimit Ihres Plans. Die Dateigröße wird erfasst, wenn das Pinning abgeschlossen ist. Wenn Sie sich Ihrem Speicherlimit nähern, können Sie Platz freigeben, indem Sie nicht mehr benötigte Dateien löschen, oder für mehr Kapazität upgraden.