Prikvačivanje

Prikvačite postojeći IPFS sadržaj na svoj račun. Kada prikvačite CID, naš klaster dohvaća sadržaj s IPFS mreže i trajno ga održava dostupnim.

Prikvačivanje prema CID-u

POST /pin

Parametar	Tip	Obavezno	Opis
cid	string	Da	IPFS identifikator sadržaja. Prihvaćen je svaki oblik: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy…, i drugi kodeci).
description	string	Ne	Kratki opis za vašu referencu.
metadata	object	Ne	Prilagođeni parovi ključ-vrijednost za prilaganje prikvačenju. Maks. 10 ključeva. Ključevi moraju biti alfanumerički ili podvlaka, 1-64 znaka. Vrijednosti moraju biti nizovi znakova, maks. 256 znakova. Ukupna veličina metapodataka ne smije premašiti 4 KB.
multiaddresses	string[]	Ne	Opcionalni savjeti za swarm-connect. Do 5 libp2p multiadresa čvorova koji imaju CID. Naš klaster paralelno pokreće swarm connect prema svakoj od njih prije prikvačivanja, tako da je sadržaj na privatnim / ne-DHT čvorovima dostupan bez čekanja na DHT otkrivanje. Best-effort — neuspjelo povezivanje ne uzrokuje neuspjeh prikvačivanja. Pogledajte Prikvačivanje s privatnog čvora.

Primjer zahtjeva

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

Za velike DAG-ove (>500 blokova ili >50 MB), odgovor uključuje oznaku async: true:

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

Prikvačivanje s privatnog čvora

Ako se CID koji želite prikvačiti nalazi na čvoru koji ne sudjeluje u javnom DHT-u — privatni staging čvor, samostalno hostirani stroj na VPN-u ili radna stanica iza NAT-a — zadani tijek prikvačivanja neće ga pronaći. Prosljeđivanjem jedne ili više multiaddresses govorite našem klasteru točno gdje treba tražiti.

Za svaki savjet paralelno pokrećemo ipfs swarm connect <multiaddr> prije samog prikvačivanja. Ako je povezivanje uspješno, dohvat DAG-a za prikvačivanje može komunicirati izravno s vašim čvorom umjesto da traži kroz DHT. Ako ne uspije, prikvačivanje se svejedno nastavlja prema javnoj mreži (best-effort semantika).

Primjer: prikvačivanje s određenog čvora

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

Odgovor uključuje status za svaki savjet

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

Podržani oblici multiadresa

Podržani su uobičajeni oblici: transporti /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protokoli /tcp ili /udp; opcionalne nadogradnje /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiadresa mora završavati s /p2p/<peerId>. Ograničenje: do 5 savjeta po prikvačenju.

Dobivanje multiadrese vašeg čvora

Na čvoru s kojeg želite prikvačivati pokrenite ipfs id i kopirajte bilo koji unos iz Addresses koji završava s /p2p/<PeerID>. Preferirajte javno dostupne adrese (/ip4/YOUR_PUBLIC_IP/…) ili one temeljene na DNS-u (/dnsaddr/your.domain/…) kako bi naš klaster mogao doći do čvora iz AWS-a.

Prikvačivanje vrlo velikih direktorija

POST /pin namijenjen je sadržaju koji već postoji na IPFS mreži — klaster dohvaća DAG blok po blok od čvorova, što za direktorije s 1000+ datoteka može potrajati nekoliko minuta. Tijekom tog razdoblja dohvaćanja, neke podređene datoteke možda još nisu lokalno dostupne, pa zahtjevi prema gatewayu za njih mogu isteći (timeout). Kada se status nadređenog elementa promijeni u pinned, svaka podređena datoteka je lokalno dostupna i dohvatljiva putem vašeg gatewaya.

Ako datoteke već imate lokalno (umjesto samo CID-a), za velike NFT kolekcije ili skupove podataka preferirajte CAR uvoz — cijeli DAG učitava se na IPFS Ninja u jednom atomskom zahtjevu, pa nema razdoblja dohvaćanja niti stanja djelomičnog prikvačivanja. CAR datoteku napravite ovako:

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

Zatim je uvezite putem POST /upload/new s car: true.

TIP

Prikvačivanje je asinkrono. Odgovor se vraća odmah sa statusom pinning. Za provjeru završetka prikvačivanja provjeravajte endpoint statusa.

Provjera statusa prikvačivanja

GET /pin/:cid

Parametar	Tip	Obavezno	Opis
cid	string	Da	CID koji provjeravate.

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

Vrijednosti statusa

Status	Značenje
pinning	Sadržaj se dohvaća s IPFS mreže. Provjerite ponovo za nekoliko sekundi.
pinned	Sadržaj je prikvačen i dostupan putem vašeg računa i gatewaya.
failed	Sadržaj nije pronađen na IPFS mreži. CID može biti nevažeći ili sadržaj više nije dostupan.

Kako prikvačivanje radi

1. Pošaljete CID putem POST /pin
2. Naš IPFS klaster pretražuje mrežu tražeći čvorove koji imaju sadržaj
3. Klaster preuzima i prikvačuje sadržaj lokalno
4. Jednom prikvačena, datoteka se pojavljuje u vašem popisu datoteka i dostupna je putem gatewaya
5. Korištenje pohrane bilježi se po završetku prikvačivanja

WARNING

Vrijeme prikvačivanja ovisi o veličini datoteke i dostupnosti mreže. Male datoteke se obično prikvače u sekundama. Velike datoteke ili rijetko prikvačeni sadržaj mogu potrajati minutama.

Pohrana

Prikvačeni sadržaj ubraja se u limit pohrane vašeg plana. Veličina datoteke bilježi se po završetku prikvačivanja. Ako se približavate limitu pohrane, možete osloboditi prostor brisanjem nekorištenih datoteka ili nadograditi plan za veći kapacitet.