Pripínanie

Pripnite existujúci IPFS obsah k svojmu účtu. Keď pripnete CID, náš cluster načíta obsah zo siete IPFS a trvalo ho udržiava dostupným.

Pripnúť podľa CID

POST /pin

Parameter	Typ	Povinný	Popis
cid	string	Áno	IPFS identifikátor obsahu. Akceptovaná je ľubovoľná forma: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… a ďalšie kodeky).
description	string	Nie	Krátky popis pre vašu referenciu.
metadata	object	Nie	Vlastné páry kľúč-hodnota na pripojenie k pripnutiu. Max 10 kľúčov. Kľúče musia byť alfanumerické alebo podčiarkovník, 1-64 znakov. Hodnoty musia byť reťazce, max 256 znakov. Celková veľkosť metadát nesmie presiahnuť 4 KB.
multiaddresses	string[]	Nie	Voliteľné swarm-connect tipy. Až 5 libp2p multiadries peerov, ktoré hostia daný CID. Náš cluster proti každej z nich paralelne vykoná swarm connect pred pripnutím, takže obsah na súkromných / non-DHT peeroch je dosiahnuteľný bez čakania na DHT discovery. Best-effort — neúspešné pripojenie nespôsobí zlyhanie pripnutia. Pozri Pripínanie zo súkromného uzla.

Príklad požiadavky

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

Response 202 Accepted

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

Pre veľké DAG (>500 blokov alebo >50 MB) odpoveď obsahuje flag async: true:

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

Pripínanie zo súkromného uzla

Ak sa CID, ktoré chcete pripnúť, nachádza na peeri, ktorý sa nezúčastňuje na verejnom DHT — súkromný staging uzol, samo-hostovaný stroj na VPN, alebo pracovná stanica za NAT — predvolený postup pripínania ho nenájde. Zadanie jednej alebo viacerých multiaddresses presne povie nášmu clusteru, kam sa má pozrieť.

Pre každý zadaný tip paralelne vykonáme ipfs swarm connect <multiaddr> pred samotným pripnutím. Ak pripojenie uspeje, DAG fetch pripnutia môže komunikovať priamo s vaším peerom namiesto prehľadávania DHT. Ak zlyhá, pripnutie aj tak pokračuje proti verejnej sieti (best-effort sémantika).

Príklad: pripnutie z konkrétneho peeru

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

Odpoveď obsahuje stav pre každý tip

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

Akceptované tvary multiadries

Podporované sú bežné tvary: transporty /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protokoly /tcp alebo /udp; voliteľné upgrady /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiadresa musí končiť na /p2p/<peerId>. Limit: až 5 tipov na pripnutie.

Getting your node's multiaddress

Na peeri, z ktorého chcete pripínať, spustite ipfs id a skopírujte ktorýkoľvek záznam z Addresses, ktorý končí na /p2p/<PeerID>. Uprednostnite verejne smerovateľné adresy (/ip4/YOUR_PUBLIC_IP/…) alebo adresy založené na DNS (/dnsaddr/your.domain/…), aby náš cluster mohol peer dosiahnuť z AWS.

Pinning very large directories

POST /pin je určené pre obsah, ktorý sa už nachádza v sieti IPFS — cluster fetchuje DAG blok po bloku od peerov, čo môže pre priečinky s 1 000+ súbormi trvať niekoľko minút. Počas tohto fetch okna niektoré vnorené súbory ešte nemusia byť lokálne dostupné a požiadavky na gateway voči nim môžu vypršať. Keď sa status rodičovského priečinka zmení na pinned, každý vnorený súbor je lokálne dostupný a prístupný cez vašu gateway.

Ak máte súbory lokálne (namiesto iba CID), pre veľké NFT kolekcie alebo datasety uprednostnite CAR import — nahrá celý DAG do IPFS Ninja v jednej atomickej požiadavke, takže neexistuje žiadne fetch okno ani stav čiastočného pripnutia. Vytvorte CAR pomocou:

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

Následne ho importujte cez POST /upload/new s car: true.

TIP

Pripínanie je asynchrónne. Odpoveď sa vráti okamžite so stavom pinning. Pre kontrolu dokončenia pripnutia dopytujte endpoint stavu.

Kontrola stavu pripnutia

GET /pin/:cid

Parameter	Typ	Povinný	Popis
cid	string	Áno	CID, ktorý kontrolujete.

Response 200 OK

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

Hodnoty stavu

Status
pinning	Obsah sa načítava zo siete IPFS. Dopytujte sa znova za niekoľko sekúnd.
pinned	Obsah je pripnutý a dostupný cez váš účet a gateway.
failed	Obsah nebol nájdený v sieti IPFS. CID môže byť neplatný alebo obsah už nie je dostupný.

Ako pripínanie funguje

1. Odošlete CID cez POST /pin
2. Náš IPFS cluster vyhľadá v sieti uzly, ktoré majú obsah
3. Cluster stiahne a pripne obsah lokálne
4. Po pripnutí sa súbor objaví vo vašom zozname súborov a je prístupný cez gateway
5. Využitie úložiska sa zaznamenáva po dokončení pripnutia

WARNING

Doba pripínania závisí od veľkosti súboru a dostupnosti siete. Malé súbory sa typicky pripnú za sekundy. Veľké súbory alebo zriedka pripínaný obsah môže trvať minúty.

Úložisko

Pripnutý obsah sa počíta do limitu úložiska vášho plánu. Veľkosť súboru sa zaznamenáva po dokončení pripnutia. Ak sa blížite k limitu úložiska, môžete uvoľniť miesto vymazaním nepoužívaných súborov alebo prejsť na vyšší plán s väčšou kapacitou.