Przypinanie

Przypnij istniejącą treść IPFS do swojego konta. Gdy przypinasz CID, nasz klaster pobiera treść z sieci IPFS i utrzymuje ją stale dostępną.

Przypnij po CID

POST /pin

Parametr	Typ	Wymagany	Opis
cid	string	Tak	Identyfikator treści IPFS. Akceptowana jest dowolna forma: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… i inne kodeki).
description	string	Nie	Krótki opis do własnego użytku.
metadata	object	Nie	Niestandardowe pary klucz-wartość dołączane do przypięcia. 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.
multiaddresses	string[]	Nie	Opcjonalne wskazówki swarm-connect. Do 5 multiadresów libp2p peerów przechowujących dany CID. Nasz klaster wykonuje swarm connect na każdym z nich równolegle przed przypięciem, dzięki czemu treść na prywatnych / nie-DHT peerach jest osiągalna bez czekania na odkrycie przez DHT. Działanie best-effort — nieudane połączenie nie powoduje niepowodzenia przypięcia. Zobacz Przypinanie z prywatnego węzła.

Przykładowe żądanie

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

Odpowiedź 202 Accepted

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

Dla dużych DAG-ów (>500 bloków lub >50 MB) odpowiedź zawiera flagę async: true:

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

Przypinanie z prywatnego węzła

Jeśli CID, który chcesz przypiąć, znajduje się na peerze, który nie uczestniczy w publicznym DHT — prywatnym węźle stagingowym, samodzielnie hostowanej maszynie w VPN, lub stacji roboczej za NAT — domyślny przepływ przypinania go nie znajdzie. Przekazanie jednego lub więcej multiaddresses mówi naszemu klastrowi dokładnie, gdzie szukać.

Uruchamiamy ipfs swarm connect <multiaddr> dla każdej wskazówki równolegle przed przypięciem. Jeśli połączenie się powiedzie, pobieranie DAG-a przypięcia może komunikować się bezpośrednio z twoim peerem zamiast przeszukiwać DHT. Jeśli się nie powiedzie, przypięcie i tak przebiega względem sieci publicznej (semantyka best-effort).

Przykład: przypnij z konkretnego peera

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

Odpowiedź zawiera status dla każdej wskazówki

{
  "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": { … }
}

Akceptowane formy multiadresów

Obsługiwane są typowe formy: transporty /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protokoły /tcp lub /udp; opcjonalne ulepszenia /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiadres musi kończyć się na /p2p/<peerId>. Limit: do 5 wskazówek na przypięcie.

Uzyskiwanie multiadresu twojego węzła

Na peerze, z którego chcesz przypinać, uruchom ipfs id i skopiuj dowolny z wpisów Addresses kończący się na /p2p/<PeerID>. Preferuj publiczne, routowalne adresy (/ip4/YOUR_PUBLIC_IP/…) lub oparte na DNS (/dnsaddr/your.domain/…), aby nasz klaster mógł dotrzeć do peera z AWS.

Przypinanie bardzo dużych katalogów

POST /pin służy do treści, która już znajduje się w sieci IPFS — klaster pobiera DAG blok po bloku od peerów, co może zająć kilka minut dla katalogów z 1000+ plikami. W tym oknie pobierania niektóre pliki podrzędne mogą nie być jeszcze lokalnie dostępne, a żądania do bramki dla nich mogą przekroczyć limit czasu. Gdy status nadrzędnego elementu zmieni się na pinned, każdy plik podrzędny jest lokalnie dostępny i osiągalny przez twoją bramkę.

Jeśli masz pliki lokalnie (zamiast tylko CID), preferuj import CAR dla dużych kolekcji NFT lub zbiorów danych — przesyła cały DAG do IPFS Ninja w jednym atomowym żądaniu, więc nie ma okna pobierania ani stanu częściowego przypięcia. Utwórz CAR za pomocą:

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

Następnie zaimportuj go przez POST /upload/new z car: true.

TIP

Przypinanie jest asynchroniczne. Odpowiedź jest zwracana natychmiast ze statusem pinning. Odpytuj endpoint statusu, aby sprawdzić, kiedy przypinanie się zakończy.

Sprawdź status przypięcia

GET /pin/:cid

Parametr	Typ	Wymagany	Opis
cid	string	Tak	CID, który sprawdzasz.

Odpowiedź 200 OK

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

Wartości statusu

Status	Znaczenie
pinning	Treść jest pobierana z sieci IPFS. Odpytaj ponownie za kilka sekund.
pinned	Treść jest przypięta i dostępna przez twoje konto i bramkę.
failed	Nie znaleziono treści w sieci IPFS. CID może być nieprawidłowy lub treść nie jest już dostępna.

Jak działa przypinanie

1. Wysyłasz CID przez POST /pin
2. Nasz klaster IPFS przeszukuje sieć w poszukiwaniu węzłów posiadających treść
3. Klaster pobiera i przypina treść lokalnie
4. Po przypięciu plik pojawia się na twojej liście plików i jest dostępny przez bramkę
5. Wykorzystanie przestrzeni jest rejestrowane po zakończeniu przypinania

WARNING

Czas przypinania zależy od rozmiaru pliku i dostępności sieci. Małe pliki zazwyczaj przypinają się w ciągu kilku sekund. Duże pliki lub rzadko przypinana treść mogą zająć kilka minut.

Przechowywanie

Przypięta treść liczy się do limitu przechowywania twojego planu. Rozmiar pliku jest rejestrowany po zakończeniu przypinania. Jeśli zbliżasz się do limitu przechowywania, możesz zwolnić miejsce, usuwając nieużywane pliki, lub ulepszyć plan, aby uzyskać więcej pojemności.