固定

將現有的 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 ​

狀態值 ​

固定的運作方式 ​

儲存 ​

固定