Fixação

Fixe conteúdo IPFS existente na sua conta. Quando você fixa um CID, nosso cluster busca o conteúdo na rede IPFS é o mantem disponível permanentemente.

Fixar por CID

POST /pin

Parâmetro	Tipo	Obrigatório	Descrição
cid	string	Sim	Identificador de conteúdo IPFS (começa com Qm ou bafy).
description	string	Não	Descrição curta para sua referência.
metadata	object	Não	Pares chave-valor personalizados para anexar ao pin. Máximo 10 chaves. As chaves devem ser alfanuméricas ou underscore, de 1 a 64 caracteres. Os valores devem ser strings, máximo 256 caracteres cada. O tamanho total dos metadados não deve exceder 4 KB.

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": "QmXk7VRz4qoG5Dg8sFL4bYWHpKe4F",
    "description": "NFT metadata",
    "metadata": {
      "collection": "my-nfts",
      "token_id": "42"
    }
  }'

Resposta 202 Accepted

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

TIP

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

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": "QmXk7VRz4qoG5Dg8sFL4bYWHpKe4F",
  "status": "pinned",
  "sizeMB": 0.042,
  "fileName": "NFT metadata",
  "pinnedAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://QmXk7VRz4qoG5Dg8sFL4bYWHpKe4F",
    "url": "https://ipfs.ninja/ipfs/QmXk7VRz4qoG5Dg8sFL4bYWHpKe4F"
  }
}

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 pela sua conta e gateway.
failed	O conteúdo não pode 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 os 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 é acessacessível pelo gateway
5. O uso de armazenamento é registrregistrado quando a fixação é concluconcluida

WARNING

O tempo de fixação depende do tamanho do arquivo e da disponibilidade na rede. Arquivos pequenos tipicamente 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 é registrregistrado quando a fixação é concluconcluida — você pode iniciar uma fixação mesmo que seu armazenamento esteja próximo do limite, mas uploads posteriores serão bloqueados se a fixação fizer você exceder o limite.