Fixare

Fixați conținut IPFS existent în contul dvs. Când fixați un CID, clusterul nostru preia conținutul din rețeaua IPFS și îl menține disponibil permanent.

Fixare după CID

POST /pin

Parametru	Tip	Obligatoriu	Descriere
cid	string	Da	Identificator de conținut IPFS. Orice formă este acceptată: CIDv0 (Qm…), CIDv1 base32 (bafk…, bafy… și alte codecuri).
description	string	Nu	Descriere scurtă pentru referința dvs.
metadata	object	Nu	Perechi cheie-valoare personalizate de atașat la fixare. Max 10 chei. Cheile trebuie să fie alfanumerice sau underscore, 1-64 caractere. Valorile trebuie să fie șiruri, max 256 caractere fiecare. Dimensiunea totală a metadatelor nu trebuie să depășească 4 KB.
multiaddresses	string[]	Nu	Indicii opționale de conectare swarm. Până la 5 multiadrese libp2p ale peer-ilor care găzduiesc CID-ul. Clusterul nostru execută swarm connect pentru fiecare, în paralel, înainte de fixare, astfel încât conținutul de pe peer-i privați / non-DHT devine accesibil fără a aștepta descoperirea prin DHT. Best-effort — o conectare eșuată nu blochează fixarea. Consultați Fixare de pe un nod privat.

Exemplu de cerere

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

Pentru DAG-uri mari (>500 blocuri sau >50 MB), răspunsul include un indicator async: true:

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

Fixare de pe un nod privat

Dacă CID-ul pe care doriți să-l fixați se află pe un peer care nu participă la DHT-ul public — un nod privat de staging, o mașină auto-găzduită într-un VPN sau o stație de lucru din spatele unui NAT — fluxul implicit de fixare nu îl va găsi. Transmiterea uneia sau mai multor multiaddresses spune clusterului nostru exact unde să caute.

Rulăm ipfs swarm connect <multiaddr> pentru fiecare indiciu, în paralel, înainte de a rula fixarea. Dacă conectarea reușește, preluarea DAG-ului fixării poate comunica direct cu peer-ul dvs. în loc să caute prin DHT. Dacă eșuează, fixarea continuă totuși împotriva rețelei publice (semantică best-effort).

Exemplu: fixare de la un peer specific

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

Răspunsul include starea per indiciu

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

Forme de multiadresă acceptate

Sunt acceptate formele comune: transporturi /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protocoale /tcp sau /udp; upgrade-uri opționale /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. Multiadresa trebuie să se termine cu /p2p/<peerId>. Limită: până la 5 indicii per fixare.

Obținerea multiadresei nodului dvs.

Pe peer-ul de pe care doriți să fixați, rulați ipfs id și copiați oricare dintre intrările Addresses care se termină cu /p2p/<PeerID>. Preferați adresele public rutabile (/ip4/YOUR_PUBLIC_IP/…) sau cele bazate pe DNS (/dnsaddr/your.domain/…) astfel încât clusterul nostru să poată ajunge la peer din AWS.

Fixarea directoarelor foarte mari

POST /pin este destinat conținutului care există deja pe rețeaua IPFS — clusterul preia DAG-ul bloc cu bloc de la peer-i, ceea ce poate dura câteva minute pentru directoare cu peste 1.000 de fișiere. În această fereastră de preluare, unele fișiere copil s-ar putea să nu fie încă disponibile local, iar cererile către gateway pentru acestea pot expira. Odată ce status-ul părintelui trece la pinned, fiecare copil este disponibil local și accesibil prin gateway-ul dvs.

Dacă aveți fișierele local (în loc de doar un CID), preferați importul CAR pentru colecții mari de NFT-uri sau seturi de date — acesta încarcă întregul DAG către IPFS Ninja într-o singură cerere atomică, deci nu există fereastră de preluare și nicio stare de fixare parțială. Creați un CAR cu:

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

Apoi importați-l prin POST /upload/new cu car: true.

TIP

Fixarea este asincronă. Răspunsul revine imediat cu starea pinning. Interogați endpoint-ul de stare pentru a verifica finalizarea fixării.

Verificarea stării de fixare

GET /pin/:cid

Parametru	Tip	Obligatoriu	Descriere
cid	string	Da	CID-ul pe care îl verificați.

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

Valori de stare

Status	Semnificație
pinning	Conținutul este preluat din rețeaua IPFS. Interogați din nou în câteva secunde.
pinned	Conținutul este fixat și disponibil prin contul și gateway-ul dvs.
failed	Conținutul nu a putut fi găsit în rețeaua IPFS. CID-ul poate fi invalid sau conținutul nu mai este disponibil.

Cum funcționează fixarea

1. Trimiteți un CID prin POST /pin
2. Clusterul nostru IPFS caută în rețea noduri care au conținutul
3. Clusterul descarcă și fixează conținutul local
4. Odată fixat, fișierul apare în lista dvs. de fișiere și este accesibil prin gateway
5. Utilizarea stocării este înregistrată la finalizarea fixării

WARNING

Timpul de fixare depinde de dimensiunea fișierului și de disponibilitatea rețelei. Fișierele mici se fixează de obicei în câteva secunde. Fișierele mari sau conținutul rar fixat poate dura minute.

Stocare

Conținutul fixat se numără în limita de stocare a planului dvs. Dimensiunea fișierului este înregistrată la finalizarea fixării. Dacă vă apropiați de limita de stocare, puteți elibera spațiu ștergând fișiere neutilizate sau puteți face upgrade pentru mai multă capacitate.