文件

上传、列出和检索 IPFS 上的文件。

上传文件

POST /upload/new

上传任何文件到 IPFS。文件会被固定，并返回一个永久 CID。

请求正文

参数	类型	必填	描述
content	string | object	是	JSON 对象/数组，或 base64 编码的文件数据（图片、PDF、HTML 或任何文件类型）。对于 CAR 导入，为 base64 编码的 CAR 文件。
car	boolean	否	设为 true 以导入 CAR 文件（DAG 导入）。保留精确的 CID。
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": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.042,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

默认使用 CIDv1

新上传的文件会按照 IPIP-0499 unixfs-v1-2025 规范返回现代 CIDv1（小型单区块内容为 bafk…，较大文件和目录为 bafy…）——采用 1 MiB 分块并使用原始叶子节点（raw leaves）。早期上传产生的旧版 Qm… CID 仍可完全解析，并可在所有端点正常使用。

仪表盘替代方式

仪表盘的 /upload 页面支持拖放上传文件、文件夹（会在浏览器中打包为 UnixFS 目录）以及 .car 归档文件——这些操作都通过同一个端点处理。CAR 路径的详细说明请参阅 CAR 导入。

重命名文件

PUT /files/:cid/name

更新文件显示的名称。CID 不会改变——它是内容的哈希值——只有您在文件列表中看到的标签会改变。

请求正文

参数	类型	必填	描述
name	string	是	新的显示名称。1-200 个字符。不得包含路径分隔符（/、\）。仅包含空白字符的名称将被拒绝。

请求示例

curl -X PUT https://api.ipfs.ninja/files/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/name \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Season 1 promo art" }'

响应 200 OK

{
  "success": true,
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "name": "Season 1 promo art"
}

仪表盘

文件页面中，每个文件行的操作菜单（三点按钮）里都有一个重命名选项。效果相同，无需编写代码。

列出文件

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": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "fileName": "Test upload",
    "fileType": "json",
    "sizeMB": 0.001,
    "createdAt": 1711036800000,
    "metadata": {
      "project": "my-app",
      "environment": "production"
    },
    "uris": {
      "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
      "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
    }
  }
]

获取文件

GET /file/:cid

通过 CID 检索特定已上传文件的元数据。

路径参数

参数	类型	必填	描述
cid	string	是	文件的 IPFS 内容标识符。

请求示例

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

响应 200 OK

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