Fixació

Fixeu contingut IPFS existent al vostre compte. Quan fixeu un CID, el nostre clúster obté el contingut de la xarxa IPFS i el manté permanentment disponible.

Fixar per CID

POST /pin

Paràmetre	Tipus	Requerit	Descripció
cid	string	Sí	Identificador de contingut IPFS. S'accepta qualsevol forma: CIDv0 (Qm…), CIDv1 en base32 (bafk…, bafy… i altres còdecs).
description	string	No	Descripció breu per a la vostra referència.
metadata	object	No	Parells clau-valor personalitzats per adjuntar a la fixació. Màx 10 claus. Les claus han de ser alfanumèriques o guió baix, 1-64 caràcters. Els valors han de ser cadenes, màx 256 caràcters cadascun. La mida total de metadata no pot superar 4 KB.
multiaddresses	string[]	No	Pistes opcionals de swarm-connect. Fins a 5 multiadreces libp2p de peers que allotgen el CID. El nostre clúster executa swarm connect contra cadascuna en paral·lel abans de la fixació, de manera que el contingut en peers privats / que no són DHT és accessible sense esperar el descobriment via DHT. Millor esforç — una connexió fallida no fa fallar la fixació. Consulteu Fixar des d'un node privat.

Exemple de sol·licitud

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

Resposta 202 Accepted

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

Per a DAG grans (>500 blocs o >50 MB), la resposta inclou una marca async: true:

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

Fixar des d'un node privat

Si el CID que voleu fixar viu en un peer que no participa en la DHT pública — un node privat de staging, una màquina autoallotjada en una VPN, o un ordinador darrere de NAT — el flux de fixació per defecte no el trobarà. Passar una o més multiaddresses indica al nostre clúster exactament on buscar.

Executem ipfs swarm connect <multiaddr> per a cada pista en paral·lel abans que s'executi la fixació. Si la connexió té èxit, la recuperació del DAG de la fixació pot parlar directament amb el vostre peer en lloc de cercar-lo a través de la DHT. Si falla, la fixació continua igualment contra la xarxa pública (semàntica de millor esforç).

Exemple: fixar des d'un peer específic

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

La resposta inclou l'estat per cada pista

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

Formes de multiadreça acceptades

S'admeten les formes habituals: transports /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protocols /tcp o /udp; capes opcionals /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. La multiadreça ha d'acabar amb /p2p/<peerId>. Límit: fins a 5 pistes per fixació.

Obtenir la multiadreça del vostre node

Al peer des del qual voleu fixar, executeu ipfs id i copieu qualsevol de les entrades Addresses que acabi en /p2p/<PeerID>. Preferiu adreces públiques encaminables (/ip4/YOUR_PUBLIC_IP/…) o basades en DNS (/dnsaddr/your.domain/…) perquè el nostre clúster pugui arribar al peer des d'AWS.

Fixar directoris molt grans

POST /pin és per a contingut que ja viu a la xarxa IPFS — el clúster recupera el DAG bloc a bloc des dels peers, cosa que pot trigar diversos minuts per a directoris amb 1.000+ fitxers. Durant aquesta finestra de recuperació, alguns fitxers fills poden no estar encara disponibles localment i les sol·licituds al gateway per a ells poden esgotar el temps d'espera. Un cop l'status del pare canvia a pinned, tots els fills estan disponibles localment i accessibles via el vostre gateway.

Si teniu els fitxers localment (en lloc de només un CID), preferiu la importació CAR per a col·leccions NFT o conjunts de dades grans — puja tot el DAG a IPFS Ninja en una sola sol·licitud atòmica, així que no hi ha finestra de recuperació ni estat de fixació parcial. Creeu un CAR amb:

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

Després importeu-lo via POST /upload/new amb car: true.

TIP

La fixació és asíncrona. La resposta es retorna immediatament amb estat pinning. Feu polling a l'endpoint d'estat per comprovar quan finalitza la fixació.

Comprovar l'estat de la fixació

GET /pin/:cid

Paràmetre	Tipus	Requerit	Descripció
cid	string	Sí	El CID que esteu comprovant.

Resposta 200 OK

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

Valors d'estat

Estat	Significat
pinning	El contingut s'està recuperant de la xarxa IPFS. Torneu a fer polling en uns segons.
pinned	El contingut està fixat i disponible a través del vostre compte i gateway.
failed	No s'ha pogut trobar el contingut a la xarxa IPFS. El CID pot ser invàlid o el contingut ja no està disponible.

Com funciona la fixació

1. Envieu un CID via POST /pin
2. El nostre clúster IPFS cerca a la xarxa nodes que tinguin el contingut
3. El clúster descarrega i fixa el contingut localment
4. Un cop fixat, el fitxer apareix a la vostra llista de fitxers i és accessible via el gateway
5. L'ús d'emmagatzematge es registra quan la fixació es completa

WARNING

El temps de fixació depèn de la mida del fitxer i de la disponibilitat a la xarxa. Els fitxers petits normalment es fixen en segons. Els fitxers grans o el contingut rarament fixat poden trigar minuts.

Emmagatzematge

El contingut fixat compta per al límit d'emmagatzematge del vostre pla. La mida del fitxer es registra quan la fixació es completa. Si us acosteu al vostre límit d'emmagatzematge, podeu alliberar espai eliminant fitxers que no useu o actualitzar el pla per obtenir més capacitat.