API v2 开放接口文档
v2.0 RESTful
兔兔图床提供强大的高并发 RESTful API v2,支持文件流上传、远程 URL 抓取上传以及图片信息检索。开发者可通过简短的 HTTP 请求快速集成图床能力。
认证与鉴权 (Authentication)
所有 API 请求均需要通过请求头携带 API Key。通过密钥上传的图片会归属到您的个人账户,并在账号正常使用期间持续保存;账号删除后的数据清理规则见隐私政策。
API Key 传递方式
推荐使用
Authorization: Bearer YOUR_API_KEY 或 X-Tutu-API-Key: YOUR_API_KEY 请求头。旧表单和 Query 参数仍兼容,但密钥放在 URL 中可能进入日志和历史记录。请勿在前端客户端中公开您的私密密钥。POST
/api/2/upload— 文件流上传接口
支持二进制文件流或 base64 格式上传图片,单图最大支持 10MiB(Free)/ 30MiB(Pro)。
请求参数表:
Authorization或X-Tutu-API-Key请求头(必需):您的 API Key。source(必需): 图片文件流 (multipart File) 或 Base64 编码字符串。anonymousUpload(可选): 设为true或1以匿名上传(隐藏公开上传者身份;图片仍归 API Key 对应账户,计入该账户配额,并由该账户管理)。srcPageUrl(可选): 来源页面 URL(浏览器扩展等场景)。srcImageUrl(可选): 来源图片 URL(浏览器扩展等场景)。
cURL 示例
curl -X POST "https://tutu.to/api/2/upload" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "source=@/path/to/image.png"
POST
/api/2/urlUpload— 远程 URL 抓取上传
通过远程图片 URL 直接拉取并保存到兔兔图床 CDN 数据平面,免去本地下载再上传的繁琐步骤。
cURL 示例
curl -X POST "https://tutu.to/api/2/urlUpload" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "imgUrl=https://example.com/image.png"
POST
/api/2/d— 远程文件下载上传(同时支持 GET / POST)
通过远程 URL 下载文件并自动上传到您的个人账户,无需先保存到本地。与
/api/2/urlUpload 的区别在于:本端点会创建并托管图片,推荐使用 POST 请求。旧 GET 入口仅为已有客户端兼容保留。远程上传是否可用以站点配置为准。请求参数表:
Authorization或X-Tutu-API-Key请求头(必需):您的 API Key。url(必需): 远程图片的完整 URL(支持 Form 或 Query 参数传递)。
cURL 示例
curl -X POST "https://tutu.to/api/2/d" -H "Authorization: Bearer YOUR_API_KEY" --data-urlencode "url=https://example.com/image.png"
账号相册管理与上传归档
API Key 只管理其所属账号的相册和图片。列表支持分页;写请求要求 UUID 格式的
Idempotency-Key 与规范 UTC 秒级 X-Client-Operation-Created-At,重试同一操作时必须原样复用两个值。成功结果在 24 小时内可通过回执恢复。| 方法与路径 | 用途 |
|---|---|
GET /api/2/account | 读取账号身份及相册能力。 |
GET /api/2/albums | 查询相册;支持 page、per_page、q。 |
POST /api/2/albums | 创建相册,字段为 name、description、privacy。 |
GET /api/2/albums/{id} | 读取本人相册及 state_token。 |
PATCH /api/2/albums/{id} | 编辑相册;必须提交 state_token,放宽可见性须明确确认。 |
GET /api/2/images | 分页查询本人图片;支持 album_id 与 q。 |
POST /api/2/images/move/preview | 预览移动,提交图片 ids 与目标 album_id(未分类传 null)。 |
POST /api/2/images/move | 使用预览返回的 state_token 与确认凭据提交移动。 |
POST /api/2/albums/{id}/dissolve/preview | 预览解散影响;解散不会删除图片。 |
POST /api/2/albums/{id}/dissolve | 使用当前 state_token 执行解散。 |
POST /api/2/uploads/status | 用固定 upload_id 与 created_at 恢复上传结果。 |
创建相册示例
curl -X POST https://tutu.to/api/2/albums \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000' \
-H 'X-Client-Operation-Created-At: 2026-10-16T08:30:00Z' \
-H 'Content-Type: application/json' \
-d '{"name":"Travel","description":"2026 trip","privacy":"private_but_link"}'上传到相册
文件上传、
/urlUpload 和 POST /d 均可提交 album_id 与当前 album_privacy 快照。服务端会在图片事务内再次验证目标。目标已解散或隐私已变化时返回明确冲突,不要自动生成新上传 ID 重传。仅链接可见
private_but_link 相册不会进入公开发现;已知相册或图片链接仍按图片自身可见性访问。这不等于密码保护。公开曝光扩大须先预览并由客户端确认。标准 JSON 响应结构
成功响应包含图片元数据与查看页链接。
chain 字段的 bit0=缩略图、bit1=中图,表示已生成的缓存尺寸。Response 200 OK
{
"status_code": 200,
"success": {
"message": "image uploaded",
"code": 200
},
"image": {
"name": "example",
"extension": "png",
"width": 1920,
"height": 1080,
"url_viewer": "https://tutu.to/image/example.abc123",
"chain": 3
}
}错误码参考
| 错误码 | HTTP 状态 | 说明 |
|---|---|---|
| 230 | 400 | API KeyIcon 无效、缺失或已撤销 — 请检查 KeyIcon 格式(UUID v4)及在设置页的状态 |
| 231 | 403 | API KeyIcon 已被禁用 — 该 KeyIcon 被管理员暂停,请前往设置页查看或重新生成 |
| 250 | 429 | API 调用频率超出限制(分/时/日三窗口)— 限额因套餐而异,具体请在设置页查看 |
| 130 | 400 | 上传来源无效 — 文件为空、远程 URL 拉取失败或 URL 上传功能未启用 |
| 500 | 500 | 服务器内部错误 — 图片处理失败,可稍后重试;持续出现请联系技术支持 |
错误响应格式:
{"status_code": 400, "error": {"message": "...", "code": 230}}