API 参考

所有端点、参数、请求/响应格式和错误代码。

基础 URL

https://api.ipfs.ninja

所有请求需要通过 X-Api-Key 头传递 API 密钥。详情请参阅认证。

端点

方法	路径	描述	页面
POST	/upload/new	上传文件到 IPFS	文件
GET	/upload/list	列出已上传的文件	文件
GET	/file/:cid	通过 CID 获取文件元数据	文件
PUT	/files/:cid/name	重命名文件	文件
PUT	/files/:cid/move	将文件移动到文件夹	文件夹
POST	/pin	从 IPFS 网络固定现有 CID（支持 swarm-connect 提示）	固定
GET	/pin/:cid	检查固定状态	固定
POST	/folders	创建文件夹	文件夹
GET	/folders	列出文件夹	文件夹
PUT	/folders/:folderId	更新文件夹	文件夹
DELETE	/folders/:folderId	删除文件夹	文件夹
POST	/folders/:folderId/snapshot	将文件夹快照为目录 CID	文件夹
PUT	/folders/:folderId/cors	设置存储桶级 CORS 配置	文件夹
GET	/folders/:folderId/cors	获取存储桶级 CORS 配置	文件夹
DELETE	/folders/:folderId/cors	移除存储桶级 CORS 配置	文件夹
GET	/user/profile	获取用户资料	个人资料
POST	/apikeys	创建 API 密钥	API 密钥
GET	/apikeys	列出 API 密钥	API 密钥
DELETE	/apikeys/:key	删除 API 密钥	API 密钥
GET	/analytics	使用情况分析	分析
PUT	/gateway-settings	更新网关设置	网关
POST	/gateway-tokens	创建网关令牌	网关
GET	/gateway-tokens	列出网关令牌	网关
DELETE	/gateway-tokens/:prefix	删除网关令牌	网关
POST	/upload/signed-url	生成签名上传令牌	签名令牌
GET	/signed-tokens	列出签名令牌	签名令牌
DELETE	/signed-tokens/:tokenId	撤销签名令牌	签名令牌
GET	/image/:cid	实时优化图片	图片优化

默认使用 CIDv1

上传和固定操作会按照 IPIP-0499 unixfs-v1-2025 规范返回现代 CIDv1（较小的单区块内容使用 bafk…，较大的文件和目录使用 bafy…）。早期上传产生的旧版 Qm… CID 在任何地方仍可完全解析 — Qm… 对任何接受 CID 的端点都是有效输入。

S3 兼容 API

使用任意 AWS SDK 即可在 IPFS Ninja 上传和管理文件。将您的 S3 客户端指向 https://s3.ipfs.ninja，并使用您的 API 密钥作为凭证。

https://s3.ipfs.ninja

S3 操作	描述
PutObject	上传文件到 IPFS
GetObject	下载文件
HeadObject	获取文件元数据
DeleteObject	取消固定并删除文件
ListObjectsV2	按前缀筛选列出文件
CreateMultipartUpload	开始分段上传（最大 5 GB）
UploadPart	上传分段
CompleteMultipartUpload	完成分段上传
ListBuckets	列出您的网关
CreateBucket	创建网关（存储桶名称全局唯一 — 若已被占用则返回 BucketAlreadyExists）
DeleteBucket	删除网关
PutBucketCors	配置存储桶级 CORS 规则（浏览器 SDK 使用时必需）
GetBucketCors	读取存储桶当前的 CORS 配置
DeleteBucketCors	移除存储桶的所有 CORS 规则

完整文档、代码示例和迁移指南请参阅 S3 兼容性。