Качење

Закачите постојећи IPFS садржај на свој налог. Када закачите CID, наш кластер преузима садржај са IPFS мреже и трајно га одржава доступним.

Качење по CID

POST /pin

Параметар	Тип	Обавезно	Опис
cid	string	Да	IPFS идентификатор садржаја. Прихвата се сваки облик: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… и остали кодеци).
description	string	Не	Кратак опис за вашу референцу.
metadata	object	Не	Прилагођени парови кључ-вредност за прикачивање. Макс. 10 кључева. Кључеви морају бити алфанумерички или доња црта, 1-64 карактера. Вредности морају бити стрингови, макс. 256 карактера. Укупна величина метаподатака не сме премашити 4 KB.
multiaddresses	string[]	Не	Опциони наговештаји за swarm-connect. До 5 libp2p мултиадреса чворова који хостују CID. Наш кластер извршава swarm connect над сваком паралелно пре качења, тако да је садржај на приватним чворовима / чворовима ван DHT доступан без чекања на DHT откриће. Настоји се да успе — неуспела конекција не блокира качење. Погледајте Качење са приватног чвора.

Пример захтева

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

За велике DAG структуре (>500 блокова или >50 MB), одговор укључује ознаку async: true:

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

Качење са приватног чвора

Ако се CID који желите да закачите налази на чвору који не учествује у јавном DHT-у — приватни staging чвор, самостално хостована машина на VPN-у или радна станица иза NAT-а — подразумевани ток качења неће га пронаћи. Прослеђивање једне или више multiaddresses говори нашем кластеру тачно где да тражи.

Извршавамо ipfs swarm connect <multiaddr> за сваки наговештај паралелно пре него што качење почне. Ако конекција успе, преузимање DAG-а за качење може директно комуницирати са вашим чвором уместо претраге кроз DHT. Ако не успе, качење се и даље наставља на јавној мрежи (настоји се да успе, без гаранције).

Пример: качење са одређеног чвора

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

Одговор укључује статус по сваком наговештају

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

Прихваћени облици мултиадреса

Подржани су уобичајени облици: транспорти /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; протоколи /tcp или /udp; опционе надоградње /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Мултиадреса мора да се завршава са /p2p/<peerId>. Ограничење: до 5 наговештаја по качењу.

Преузимање мултиадресе вашег чвора

На чвору са кога желите да качите, покрените ipfs id и копирајте било који унос из Addresses који се завршава са /p2p/<PeerID>. Дајте предност јавно рутабилним адресама (/ip4/YOUR_PUBLIC_IP/…) или DNS адресама (/dnsaddr/your.domain/…) како би наш кластер могао да достигне чвор из AWS-а.

Качење веома великих директоријума

POST /pin је намењено садржају који већ живи на IPFS мрежи — кластер преузима DAG блок по блок од чворова, што може трајати неколико минута за директоријуме са 1.000+ фајлова. Током тог прозора преузимања, неки дечији фајлови можда још нису локално доступни, па захтеви ка gateway-у за њих могу истећи. Када статус родитеља пређе у pinned, сваки дечији елемент је локално доступан и приступачан преко вашег gateway-а.

Ако имате фајлове локално (уместо само CID-а), за велике NFT колекције или скупове података дајте предност CAR увозу — он отпрема читав DAG на IPFS Ninja у једном атомском захтеву, тако да нема прозора преузимања ни стања делимичног качења. Направите CAR помоћу:

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

Затим га увезите преко POST /upload/new са car: true.

TIP

Качење је асинхроно. Одговор се враћа одмах са статусом pinning. За проверу завршетка качења проверавајте крајњу тачку статуса.

Провера статуса качења

GET /pin/:cid

Параметар	Тип	Обавезно	Опис
cid	string	Да	CID који проверавате.

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

Вредности статуса

Status	Значење
pinning	Садржај се преузима са IPFS мреже. Проверите поново за неколико секунди.
pinned	Садржај је закачен и доступан преко вашег налога и gateway-а.
failed	Садржај није могао бити пронађен на IPFS мрежи. CID може бити неважећи или садржај више није доступан.

Како качење ради

1. Шаљете CID преко POST /pin
2. Наш IPFS кластер претражује мрежу тражећи чворове који имају садржај
3. Кластер преузима и качи садржај локално
4. Једном закачен, фајл се појављује у вашој листи фајлова и доступан је преко gateway-а
5. Коришћење складиштења се бележи по завршетку качења

WARNING

Време качења зависи од величине фајла и доступности мреже. Мали фајлови се типично закаче за секунде. Велики фајлови или ретко качени садржај може трајати минутима.

Складиштење

Закачени садржај се рачуна у ограничење складиштења вашег плана. Величина фајла се бележи по завршетку качења — можете покренути качење чак и ако је ваше складиштење близу ограничења, али даља отпремања ће бити блокирана ако качење узрокује његово премашивање.