Pinning

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

通过 CID 固定

POST /pin

参数	类型	必填	描述
`cid`	string	是	IPFS 内容标识符。接受任何形式：CIDv0（`Qm…`）、CIDv1 base32（`bafk…`、`bafy…`，以及其他编解码器）。
`description`	string	否	供您参考的简短描述。
`metadata`	object	否	附加到固定内容的自定义键值对。最多 10 个键。键必须为字母数字或下划线，1-64 个字符。值必须为字符串，每个最多 256 个字符。元数据总大小不得超过 4 KB。
`multiaddresses`	string[]	否	可选的 swarm-connect 提示。最多 5 个托管该 CID 的对等节点的 libp2p multiaddress。我们的集群会在固定操作之前并行对每一个地址执行 `swarm connect`，这样私有 / 非 DHT 对等节点上的内容无需等待 DHT 发现即可被访问到。这是尽力而为（best-effort）的操作——连接失败不会导致固定失败。参见从私有节点固定。

请求示例

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

响应 `202 Accepted`

json

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

对于大型 DAG（超过 500 个区块或超过 50 MB），响应中会包含 async: true 标志：

json

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

从私有节点固定

如果您要固定的 CID 存在于一个未参与公共 DHT 的对等节点上——例如私有的预发布节点、VPN 上的自托管机器，或位于 NAT 之后的工作站——默认的固定流程将无法找到它。传入一个或多个 multiaddresses 可以准确告诉我们的集群该到哪里去查找。

我们会在固定操作运行之前，并行地为每个提示执行一次 ipfs swarm connect <multiaddr>。如果连接成功，固定操作的 DAG 拉取就可以直接与您的对等节点通信，而不必在 DHT 中搜寻。如果连接失败，固定操作仍会针对公共网络继续进行（尽力而为语义）。

示例：从指定对等节点固定

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": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "description": "internal staging build",
    "multiaddresses": [
      "/ip4/203.0.113.42/tcp/4001/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3",
      "/dns4/node.internal.example/tcp/443/wss/p2p/12D3KooWH3uVF6wv47WnArKHk5p6cvgCJEb74UTmxztmQDc298L3"
    ]
  }'

响应中包含每个提示的连接状态

json

{
  "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": { … }
}

支持的 multiaddress 形式

支持常见的形式：/ip4、/ip6、/dns4、/dns6、/dns、/dnsaddr 传输方式；/tcp 或 /udp 协议；可选的 /quic-v1、/quic、/ws、/wss、/http、/https、/webtransport、/webrtc-direct 升级层。multiaddress 必须以 /p2p/<peerId> 结尾。上限：每次固定最多 5 个提示。

获取您节点的 multiaddress

在您想要固定的对等节点上运行 ipfs id，复制 Addresses 中任意一个以 /p2p/<PeerID> 结尾的条目。请优先选择公共可路由地址（/ip4/YOUR_PUBLIC_IP/…）或基于 DNS 的地址（/dnsaddr/your.domain/…），以便我们的集群能够从 AWS 访问到该对等节点。

固定超大目录

POST /pin 适用于已经存在于 IPFS 网络上的内容——集群会逐块地从对等节点获取 DAG，对于拥有 1,000 个以上文件的目录，这可能需要几分钟时间。在此获取窗口期间，部分子文件可能尚未在本地可用，对它们的网关请求可能会超时。一旦父级的 status 变为 pinned，所有子项都将在本地可用，并可通过您的网关访问。

如果您在本地拥有这些文件（而不仅仅是一个 CID），对于大型 NFT 集合或数据集，建议优先使用 CAR 导入——它会在一次原子请求中将整个 DAG 上传至 IPFS Ninja，因此不存在获取窗口，也不会出现部分固定状态。使用以下命令创建 CAR：

bash

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

然后通过 POST /upload/new 并设置 car: true 来导入它。

TIP

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

检查固定状态

GET /pin/:cid

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

响应 `200 OK`

json

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

状态值

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

固定的工作原理

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

WARNING

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

存储

固定的内容计入您计划的存储限制。文件大小在固定完成时记录。如果您接近存储限制，可以通过删除不再使用的文件来释放空间，或升级计划以获得更多容量。

Pinning ​

通过 CID 固定 ​

请求示例 ​

响应 202 Accepted ​

从私有节点固定 ​

示例：从指定对等节点固定 ​

响应中包含每个提示的连接状态 ​

支持的 multiaddress 形式 ​

检查固定状态 ​

响应 200 OK ​

状态值 ​

固定的工作原理 ​

存储 ​

Pinning

通过 CID 固定

请求示例

响应 `202 Accepted`

从私有节点固定

示例：从指定对等节点固定

响应中包含每个提示的连接状态

支持的 multiaddress 形式

检查固定状态

响应 `200 OK`

状态值

固定的工作原理

存储