檔案

上傳、列出和擷取 IPFS 上的檔案。

上傳檔案

POST /upload/new

上傳任何檔案至 IPFS。檔案會被固定，並傳回一個永久 CID。

請求正文

參數	類型	必填	描述
content	string | object	是	JSON 物件/陣列，或 base64 編碼的檔案資料（圖片、PDF、HTML 或任何檔案類型）。
description	string	否	上傳內容的簡短描述。
metadata	object	否	附加到檔案的自訂鍵值對。最多 10 個鍵。鍵必須為英數字或底線，1-64 個字元。值必須為字串，每個最多 256 個字元。中繼資料總大小不得超過 4 KB。

請求範例

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "name": "example", "value": 42 },
    "description": "Test upload",
    "metadata": {
      "project": "my-app",
      "environment": "production"
    }
  }'

上傳圖片（base64）

const fs = require("fs");
const image = fs.readFileSync("photo.png").toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: image,
    description: "Profile photo"
  })
});

回應 200 OK

{
  "cid": "QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN",
    "url": "https://ipfs.ninja/ipfs/QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN"
  }
}

列出檔案

GET /upload/list

擷取指定時間範圍內已上傳的 IPFS 檔案清單。

查詢參數

參數	類型	必填	描述
from	number	是	時間範圍開始，Unix 毫秒時間戳記。
to	number	是	時間範圍結束，Unix 毫秒時間戳記。

請求範例

curl "https://api.ipfs.ninja/upload/list?from=1704067200000&to=1735689600000" \
  -H "X-Api-Key: bws_your_api_key_here"

回應 200 OK

[
  {
    "cid": "QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN",
      "url": "https://ipfs.ninja/ipfs/QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN"
    }
  }
]

取得檔案

GET /file/:cid

透過 CID 擷取特定已上傳檔案的中繼資料。

路徑參數

參數	類型	必填	描述
cid	string	是	檔案的 IPFS 內容識別碼。

請求範例

curl https://api.ipfs.ninja/file/QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN \
  -H "X-Api-Key: bws_your_api_key_here"

回應 200 OK

{
  "cid": "QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN",
  "fileName": "Test upload",
  "fileType": "json",
  "sizeMB": 0.001,
  "createdAt": 1711036800000,
  "uris": {
    "ipfs": "ipfs://QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN",
    "url": "https://ipfs.ninja/ipfs/QmXmCX9S6ANVjYJh3rJmXjqgYtYv7WZLUDL2XCwdPrvUwN"
  }
}