Připínání

Připněte existující IPFS obsah ke svému účtu. Když připnete CID, náš cluster načte obsah ze sítě IPFS a trvale ho udržuje dostupný.

Připnout podle CID

POST /pin

Parametr	Typ	Povinný	Popis
cid	string	Ano	IPFS identifikátor obsahu. Přijímá se libovolná forma: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… a další kodeky).
description	string	Ne	Krátký popis pro vaši referenci.
metadata	object	Ne	Vlastní páry klíč-hodnota k připojení k připnutí. Max 10 klíčů. Klíče musí být alfanumerické nebo podtržítko, 1-64 znaků. Hodnoty musí být řetězce, max 256 znaků. Celková velikost metadat nesmí přesáhnout 4 KB.
multiaddresses	string[]	Ne	Volitelné nápovědy pro swarm-connect. Až 5 multiadres libp2p peerů, kteří CID hostují. Náš cluster proti každé z nich paralelně spustí swarm connect před samotným připnutím, takže obsah na privátních / non-DHT peerech je dostupný, aniž by bylo nutné čekat na objevení přes DHT. Best-effort — neúspěšné připojení připnutí nezastaví. Viz Připínání z privátního uzlu.

Příklad požadavku

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

U velkých DAG struktur (>500 bloků nebo >50 MB) odpověď obsahuje příznak async: true:

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

Připínání z privátního uzlu

Pokud CID, který chcete připnout, žije na peerovi, který se neúčastní veřejné DHT — privátní staging uzel, vlastní hostovaný stroj na VPN, nebo pracovní stanice za NAT — výchozí postup připínání ho nenajde. Předání jedné nebo více multiaddresses řekne našemu clusteru přesně, kde hledat.

Pro každou nápovědu spustíme paralelně ipfs swarm connect <multiaddr> před samotným připnutím. Pokud se připojení podaří, načítání DAG struktury pro připnutí může komunikovat přímo s vaším peerem místo prohledávání DHT. Pokud se nepodaří, připnutí i tak pokračuje proti veřejné síti (best-effort sémantika).

Příklad: připnutí z konkrétního 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"
    ]
  }'

Odpověď obsahuje stav pro každou nápovědu

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

Přijímané tvary multiadres

Podporovány jsou běžné tvary: transporty /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protokoly /tcp nebo /udp; volitelná rozšíření /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiadresa musí končit /p2p/<peerId>. Limit: až 5 nápověd na jedno připnutí.

Zjištění multiadresy vašeho uzlu

Na peerovi, ze kterého chcete připínat, spusťte ipfs id a zkopírujte kteroukoli z položek Addresses, která končí /p2p/<PeerID>. Upřednostněte veřejně směrovatelné adresy (/ip4/YOUR_PUBLIC_IP/…) nebo adresy založené na DNS (/dnsaddr/your.domain/…), aby náš cluster mohl peera dosáhnout z AWS.

Připínání velmi velkých adresářů

POST /pin je určeno pro obsah, který už žije v síti IPFS — cluster stahuje DAG blok po bloku od peerů, což může u adresářů s 1 000+ soubory trvat několik minut. Během tohoto okna může být část podřízených souborů ještě lokálně nedostupná a požadavky na gateway na ně mohou vypršet. Jakmile se status nadřazeného záznamu změní na pinned, je každý podřízený soubor lokálně dostupný a přístupný přes vaši gateway.

Pokud soubory máte lokálně (namísto pouhého CID), pro velké NFT kolekce nebo datové sady dejte přednost importu CAR — nahraje celou DAG strukturu do IPFS Ninja jako jeden atomický požadavek, takže neexistuje žádné okno stahování ani stav částečného připnutí. CAR vytvoříte pomocí:

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

Poté ho importujte přes POST /upload/new s car: true.

TIP

Připínání je asynchronní. Odpověď se vrátí okamžitě se stavem pinning. Pro kontrolu dokončení připínání dotazujte endpoint stavu.

Kontrola stavu připnutí

GET /pin/:cid

Parametr	Typ	Povinný	Popis
cid	string	Ano	CID, který 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 se načítá ze sítě IPFS. Dotazujte se znovu za několik sekund.
pinned	Obsah je připnut a dostupný přes váš účet a gateway.
failed	Obsah nebyl nalezen v síti IPFS. CID může být neplatný nebo obsah již není dostupný.

Jak připínání funguje

1. Odešlete CID přes POST /pin
2. Náš IPFS cluster vyhledá v síti uzly, které mají obsah
3. Cluster stáhne a připne obsah lokálně
4. Po připnutí se soubor objeví ve vašem seznamu souborů a je přístupný přes gateway
5. Využití úložiště se zaznamenává po dokončení připnutí

WARNING

Doba připínání závisí na velikosti souboru a dostupnosti sítě. Malé soubory se typicky připnou za sekundy. Velké soubory nebo zřídka připínaný obsah může trvat minuty.

Úložiště

Připnutý obsah se počítá do limitu úložiště vašeho plánu. Velikost souboru se zaznamenává po dokončení připínání. Pokud se blížíte limitu úložiště, můžete uvolnit místo smazáním nepoužívaných souborů nebo upgradovat na vyšší kapacitu.