固定

将现有的 IPFS 内容固定到您的账户。当您固定一个 CID 时，我们的集群会从 IPFS 网络获取内容并永久保持其可用。

通过 CID 固定

POST /pin

参数	类型	必填	描述
`cid`	string	是	IPFS 内容标识符（以 `Qm` 或 `bafy` 开头）。
`description`	string	否	供您参考的简短描述。
`metadata`	object	否	附加到固定内容的自定义键值对。最多 10 个键。键必须为字母数字或下划线，1-64 个字符。值必须为字符串，每个最多 256 个字符。元数据总大小不得超过 4 KB。

请求示例

bash

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

响应 `202 Accepted`

json

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

TIP

固定是异步的。响应会立即返回 pinning 状态。轮询状态端点以检查固定何时完成。

检查固定状态

GET /pin/:cid

参数	类型	必填	描述
`cid`	string	是	要检查的 CID。

响应 `200 OK`

json

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

状态值

状态	含义
`pinning`	正在从 IPFS 网络获取内容。几秒后再次轮询。
`pinned`	内容已固定，可通过您的账户和网关访问。
`failed`	在 IPFS 网络上找不到内容。CID 可能无效或内容已不可用。

固定的工作原理

您通过 POST /pin 提交 CID
我们的 IPFS 集群在网络中搜索拥有该内容的节点
集群下载并在本地固定内容
固定完成后，文件出现在您的文件列表中，并可通过网关访问
固定完成时记录存储使用量

WARNING

固定时间取决于文件大小和网络可用性。小文件通常在几秒内固定。大文件或很少被固定的内容可能需要几分钟。

存储

固定的内容计入您计划的存储限制。文件大小在固定完成时记录 — 即使存储接近限制您也可以发起固定，但如果固定导致超出限制，后续上传将被阻止。

固定 ​

通过 CID 固定 ​

请求示例 ​

响应 202 Accepted ​

检查固定状态 ​

响应 200 OK ​

状态值 ​

固定的工作原理 ​

存储 ​

固定