快速入门

两分钟内将您的第一个文件上传到 IPFS。

1. 获取您的 API 密钥

使用 Google 账号在 ipfs.ninja 注册。系统会自动创建一个默认 API 密钥。前往个人资料页面查看和管理您的 API 密钥。

WARNING

注意： API 密钥不会过期。您可以创建多个密钥，并在个人资料页面单独撤销。

2. 上传文件

向 /upload/new 发送 POST 请求并附带您的内容。以下是上传 JSON 对象的示例：

curl

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": "My NFT",
      "description": "A permanent file on IPFS",
      "image": "ipfs://bafybeiExampleCID..."
    },
    "description": "NFT metadata"
  }'

JavaScript

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: {
      name: "My NFT",
      description: "A permanent file on IPFS",
      image: "ipfs://bafybeiExampleCID..."
    },
    description: "NFT metadata"
  })
});

const data = await response.json();
console.log(data.cid);       // "bafybeigdyrzt5..."
console.log(data.uris.url);  // "https://ipfs.ninja/ipfs/bafybeigdyrzt5..."

默认使用 CIDv1

新上传的内容会按照 IPIP-0499 生成现代化的 CIDv1（对于小型单区块内容为 bafk…，对于较大的文件和目录为 bafy…）。早期上传产生的旧版 Qm… CID 仍然可以在任何地方解析——两种格式都可以作为所有端点的输入。

API 返回 CID、文件大小和访问 URI：

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 0.001,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

3. 检索您的文件

通过两种方式访问您的文件：

通过 IPFS 网关（无需认证）

curl https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

TIP

apex 网关 https://ipfs.ninja/ipfs/<CID> 提供由任何 IPFS Ninja 用户上传或固定的 CID。平台未知的 CID 返回 HTTP 410 Gone — 对于这些，请使用公共网关（ipfs.io、dweb.link），或先对您的账户对该 CID 执行 POST /pin。

通过 API（返回文件元数据）

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

响应：

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

备选方案：使用 AWS SDK（S3 兼容）

已经在使用 S3？将您现有的 AWS SDK 指向 https://s3.ipfs.ninja，并使用您的 API 密钥作为凭证：

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: { accessKeyId: "bws_prefix", secretAccessKey: "bws_fullkey" },
  region: "us-east-1",
  forcePathStyle: true
});

await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-file.json",
  Body: JSON.stringify({ hello: "IPFS" })
}));

参阅 S3 兼容性 获取包含 Python、Go 示例及迁移指南的完整文档。

更喜欢点击操作？使用控制台

如果您不想编写代码，ipfs.ninja/upload 支持拖放上传，可用于：

• 任意文件 — 将其拖放到上传区域，即可完成固定并获得 CID
• 文件夹 — 在浏览器中打包为 UnixFS 目录，作为单次导入上传，每个子文件都可通过 /ipfs/{cid}/{subpath} 解析访问
• .car 归档文件 — 自动检测，根 CID 完全保留原样（参见 CAR 导入）

上传完成后，文件会出现在文件页面，您可以在此重命名、在文件夹之间移动、为整个文件夹获取一个 IPFS 目录 CID（快照），并为每个存储桶配置 S3 CORS，以便浏览器端 SDK 访问。

后续步骤

• API 参考 — 所有端点、参数和错误代码的完整文档。
• S3 兼容性 — 使用 AWS SDK 与 IPFS Ninja 交互。
• 专属网关 — 获取仅提供您文件的私有网关。