Fixação

Fixe conteúdo IPFS existente na sua conta. Quando você fixa um CID, nosso cluster busca o conteúdo na rede IPFS e o mantém 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 é aceito: CIDv0 (Qm…), CIDv1 em base32 (bafk…, bafy… e outros codecs).
description	string	Não	Descrição curta para sua 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, de 1 a 64 caracteres. Os valores devem ser strings, com no máximo 256 caracteres cada. O tamanho total dos metadados não deve exceder 4 KB.
multiaddresses	string[]	Não	Dicas opcionais de swarm-connect. Até 5 multiendereços libp2p de peers que hospedam o CID. Nosso cluster executa swarm connect em cada um deles em paralelo antes da fixação, para que conteúdo em peers privados / fora da DHT fique acessível sem esperar pela descoberta via DHT. Melhor esforço — uma falha de conexão não faz a fixação falhar. Veja Fixando a partir de um nó privado.

Exemplo de requisição

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 (mais de 500 blocos ou mais de 50 MB), a resposta inclui um sinalizador async: true:

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

Fixando a partir de um nó privado

Se o CID que você quer fixar está em um peer que não participa da DHT pública — um nó de staging privado, uma máquina auto-hospedada em uma VPN, ou uma estação de trabalho atrás de NAT — o fluxo padrão de fixação não vai encontrá-lo. Passar um ou mais multiaddresses diz ao nosso cluster exatamente onde procurar.

Executamos ipfs swarm connect <multiaddr> para cada dica em paralelo antes da fixação. Se a conexão for bem-sucedida, a busca do DAG da fixação pode falar diretamente com o seu peer em vez de procurar pela DHT. Se falhar, a fixação continua mesmo assim 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 status de cada dica

{
  "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 multiendereço aceitos

Formatos comuns são suportados: transportes /ip4, /ip6, /dns4, /dns6, /dns, /dnsaddr; protocolos /tcp ou /udp; upgrades opcionais /quic-v1, /quic, /ws, /wss, /http, /https, /webtransport, /webrtc-direct. O multiendereço precisa terminar com /p2p/<peerId>. Limite: até 5 dicas por fixação.

Obtendo o multiendereço do seu nó

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

Fixando diretórios muito grandes

POST /pin é para conteúdo que já existe na rede IPFS — o cluster busca o DAG bloco por bloco a partir de peers, o que pode levar vários minutos para diretórios com mais de 1.000 arquivos. Durante essa janela de busca, alguns arquivos filhos podem ainda não estar disponíveis localmente e requisições ao gateway para eles podem expirar. Assim que o status do pai mudar para pinned, todos os filhos estarão disponíveis localmente e acessíveis pelo seu gateway.

Se você tem os arquivos localmente (em vez de apenas um CID), prefira a importação de CAR para grandes coleções de NFT ou conjuntos de dados — ela envia o DAG inteiro para o IPFS Ninja em uma única requisição atômica, então não há janela de busca nem estado de fixação parcial. Crie um CAR com:

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

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

TIP

A fixação é assíncrona. A resposta retorna imediatamente com status pinning. Consulte o endpoint de status para verificar quando a fixação for concluída.

Verificar status da fixação

GET /pin/:cid

Parâmetro	Tipo	Obrigatório	Descrição
cid	string	Sim	O CID que você está verificando.

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 status

Status	Significado
pinning	O conteúdo está sendo buscado na rede IPFS. Consulte novamente em alguns segundos.
pinned	O conteúdo está fixado e disponível através da sua conta e do gateway.
failed	O conteúdo não pôde ser encontrado na rede IPFS. O CID pode ser inválido ou o conteúdo não está mais disponível.

Como a fixação funciona

1. Você envia um CID via POST /pin
2. Nosso cluster IPFS procura na rede por nós que possuem o conteúdo
3. O cluster baixa e fixa o conteúdo localmente
4. Uma vez fixado, o arquivo aparece na sua lista de arquivos e fica acessível pelo gateway
5. O uso de armazenamento é registrado quando a fixação é concluída

WARNING

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

Armazenamento

O conteúdo fixado conta para o limite de armazenamento do seu plano. O tamanho do arquivo é registrado quando a fixação é concluída. Se você estiver se aproximando do seu limite de armazenamento, pode liberar espaço excluindo arquivos não utilizados ou fazer upgrade para mais capacidade.