Fixação

Fixa conteúdo IPFS existente na tua conta. Quando fixas um CID, o nosso cluster procura o conteúdo na rede IPFS e mantém-no disponível permanentemente.

Fixar por CID

POST /pin

Parâmetro	Tipo	Obrigatório	Descrição
cid	string	Sim	Identificador de conteúdo IPFS. Qualquer formato é aceite: CIDv0 (Qm…), CIDv1 em base32 (bafk…, bafy…, e outros codecs).
description	string	Não	Descrição curta para tua referência.
metadata	object	Não	Pares chave-valor personalizados para anexar à fixação. Máximo de 10 chaves. As chaves devem ser alfanuméricas ou underscore, com 1 a 64 caracteres. Os valores devem ser strings, com no máximo 256 caracteres cada. O tamanho total dos metadados não pode exceder 4 KB.
multiaddresses	string[]	Não	Pistas opcionais de swarm-connect. Até 5 multiaddresses libp2p de peers que alojam o CID. O nosso cluster executa swarm connect contra cada um em paralelo antes da fixação, para que o conteúdo em peers privados / fora da DHT fique acessível sem esperar pela descoberta via DHT. É feito com melhor esforço — uma ligação falhada não faz falhar a fixação. Consulta Fixar a partir de um nó privado.

Exemplo de pedido

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

Para DAGs grandes (>500 blocos ou >50 MB), a resposta inclui uma flag async: true:

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

Fixar a partir de um nó privado

Se o CID que queres fixar vive num peer que não participa na DHT pública — um nó de staging privado, uma máquina autoalojada numa VPN, ou uma estação de trabalho atrás de NAT — o fluxo de fixação predefinido não o vai encontrar. Passar um ou mais multiaddresses diz ao nosso cluster exatamente onde procurar.

Executamos ipfs swarm connect <multiaddr> para cada pista em paralelo antes de a fixação começar. Se a ligação for bem-sucedida, a obtenção do DAG da fixação pode comunicar diretamente com o teu peer em vez de o procurar na DHT. Se falhar, a fixação prossegue na mesma contra a rede pública (semântica de melhor esforço).

Exemplo: fixar a partir de um peer específico

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

A resposta inclui o estado por 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": { … }
}

Formatos de multiaddress aceites

São suportados os formatos comuns: transportes /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protocolos /tcp ou /udp; upgrades opcionais /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. O multiaddress tem de terminar em /p2p/<peerId>. Limite: até 5 pistas por fixação.

Obter o multiaddress do teu nó

No peer a partir do qual queres fixar, executa ipfs id e copia qualquer uma das entradas de Addresses que termine em /p2p/<PeerID>. Prefere endereços públicos roteáveis (/ip4/YOUR_PUBLIC_IP/…) ou baseados em DNS (/dnsaddr/your.domain/…) para que o nosso cluster consiga alcançar o peer a partir da AWS.

Fixar diretórios muito grandes

POST /pin destina-se a conteúdo que já vive na rede IPFS — o cluster obtém o DAG bloco a bloco a partir de peers, o que pode demorar vários minutos para diretórios com 1000+ ficheiros. Durante essa janela de obtenção, alguns ficheiros filhos podem ainda não estar disponíveis localmente e os pedidos ao gateway para eles podem expirar. Assim que o status do pai passar a pinned, todos os filhos estão disponíveis localmente e acessíveis através do teu gateway.

Se já tens os ficheiros localmente (em vez de apenas um CID), prefere a importação CAR para grandes coleções de NFT ou conjuntos de dados — ela carrega o DAG inteiro para o IPFS Ninja num único pedido atómico, pelo que não há janela de obtenção nem estado de fixação parcial. Cria um CAR com:

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

Depois importa-o via POST /upload/new com car: true.

TIP

A fixação é assíncrona. A resposta é devolvida de imediato com o estado pinning. Consulta periodicamente o endpoint de estado para verificar quando a fixação termina.

Verificar o estado da fixação

GET /pin/:cid

Parâmetro	Tipo	Obrigatório	Descrição
cid	string	Sim	O CID que estás a verificar.

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

Valores de estado

Estado	Significado
pinning	O conteúdo está a ser obtido a partir da rede IPFS. Verifica novamente daqui a uns segundos.
pinned	O conteúdo está fixado e disponível através da tua conta e gateway.
failed	O conteúdo não pôde ser encontrado na rede IPFS. O CID pode ser inválido ou o conteúdo já não está disponível.

Como funciona a fixação

1. Submetes um CID via POST /pin
2. O nosso cluster IPFS procura na rede nós que tenham o conteúdo
3. O cluster transfere e fixa o conteúdo localmente
4. Assim que fixado, o ficheiro aparece na tua lista de ficheiros e fica acessível através do gateway
5. O uso de armazenamento é registado quando a fixação termina

WARNING

O tempo de fixação depende do tamanho do ficheiro e da disponibilidade na rede. Ficheiros pequenos são geralmente fixados em segundos. Ficheiros grandes ou conteúdo raramente fixado podem demorar minutos.

Armazenamento

O conteúdo fixado conta para o limite de armazenamento do teu plano. O tamanho do ficheiro é registado quando a fixação termina. Se te aproximares do teu limite de armazenamento, podes libertar espaço eliminando ficheiros não utilizados ou fazer upgrade para mais capacidade.