Fijación

Fija contenido IPFS existente a tu cuenta. Cuando fijas un CID, nuestro cluster busca el contenido en la red IPFS y lo mantiene disponible permanentemente.

Fijar por CID

POST /pin

Parámetro	Tipo	Requerido	Descripción
cid	string	Sí	Identificador de contenido IPFS (comienza con Qm o bafy).
description	string	No	Descripción corta para tu referencia.
metadata	object	No	Pares clave-valor personalizados para adjuntar al pin. Máximo 10 claves. Las claves deben ser alfanuméricas o guion bajo, de 1 a 64 caracteres. Los valores deben ser cadenas, máximo 256 caracteres cada uno. El tamaño total de los metadatos no debe exceder 4 KB.

Ejemplo de solicitud

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

Respuesta 202 Accepted

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

TIP

La fijación es asíncrona. La respuesta se devuelve inmediatamente con estado pinning. Consulta el endpoint de estado para verificar cuando se complete la fijación.

Verificar Estado de Fijación

GET /pin/:cid

Parámetro	Tipo	Requerido	Descripción
cid	string	Sí	El CID que estas verificando.

Respuesta 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 estado

Estado	Significado
pinning	El contenido está siendo buscado en la red IPFS. Consulta de nuevo en unos segundos.
pinned	El contenido está fijado y disponible a través de tu cuenta y gateway.
failed	El contenido no pudo encontrarse en la red IPFS. El CID puede ser inválido o el contenido ya no está disponible.

¿Cómo funciona la fijación

1. Envias un CID mediante POST /pin
2. Nuestro cluster IPFS busca en la red los nodos que tienen el contenido
3. El cluster descarga y fija el contenido localmente
4. Una vez fijado, el archivo aparece en tu lista de archivos y es accesible a través del gateway
5. El uso de almacenamiento se registra cuando la fijación se completa

WARNING

El tiempo de fijación depende del tamaño del archivo y la disponibilidad en la red. Los archivos pequeños típicamente se fijan en segundos. Los archivos grandes o contenido raramente fijado pueden tomar minutos.

Almacenamiento

El contenido fijado cuenta para el límite de almacenamiento de tu plan. El tamaño del archivo se registra cuando la fijación se completa — puedes iniciar una fijación incluso si tu almacenamiento está cerca del límite, pero las subidas posteriores serán bloqueadas si la fijación causa que excedas el límite.