认证
在控制台创建 API Key 后，用 HTTP Basic 认证（用户名 api，密码为 Key），或在请求头里加 Authorization: Bearer <Key>。
curl --user api:YOUR_API_KEY ... # or curl -H "Authorization: Bearer YOUR_API_KEY" ...
压缩图片
把图片作为请求体 POST 到 /api/v1/shrink。可选参数：level（fast / default / best）和 filename。
curl -i --user api:YOUR_API_KEY \ --data-binary @photo.jpg \ "https://bitinz.com/api/v1/shrink?level=default&filename=photo.jpg"
响应
通常成功时返回 201，status 为 done，Location 头和 output.url 指向结果的下载地址。Compression-Count 头是本月已用次数。
HTTP/1.1 201 Created
Location: https://bitinz.com/api/v1/results/<id>/download
Compression-Count: 1
{
"id": "<id>",
"status": "done",
"input": { "size": 2277375, "type": "image/jpeg" },
"output": { "size": 992450, "type": "image/jpeg", "ratio": 0.436,
"url": "https://bitinz.com/api/v1/results/<id>/download" },
"unchanged": false,
"expiresAt": "2026-10-02T12:00:00Z"
}已提交，等待结果：202
队列较长时会返回 202 Accepted，status 为 pending。此时 Location 指向任务状态地址，而不是下载地址；保留这个地址并轮询，不要重复提交图片。
HTTP/1.1 202 Accepted
Location: https://bitinz.com/api/v1/results/<id>
{
"id": "<id>",
"status": "pending",
"input": { "size": 2277375 },
"expiresAt": "2026-10-02T12:00:00Z"
}轮询任务状态
向 Location 返回的地址发送 GET /api/v1/results/{id}，每隔 1–2 秒查询一次。pending 表示排队中（queuePosition 是当前位次），processing 表示正在压缩；done 后从 downloadUrl 下载。failed 表示任务失败，请根据 failure 处理，note 提供原因。
curl "https://bitinz.com/api/v1/results/<id>"
{
"id": "<id>",
"status": "done",
"available": true,
"downloadUrl": "/api/v1/results/<id>/download",
"outputSize": 992450,
"unchanged": false
}下载结果
结果在保留期内可以直接下载，过期返回 410。
curl -o photo.min.jpg "https://bitinz.com/api/v1/results/<id>/download"
错误码
{ "error": { "code": "...", "message": "..." } }
| 401 unauthorized / invalid_key | 缺少 Key，或 Key 无效、已吊销 |
| 413 too_large | 图片超过大小上限 |
| 415 unsupported_image | 同步路径下：不是支持的 PNG、JPEG、WebP、AVIF 图片 |
| 422 image_too_large | 同步路径下：图片像素超过服务可处理的上限 |
| failed / unsupported | 排队处理时，不支持的图片会在结果中返回 status: failed、failure: unsupported |
| failed / too_large | 排队处理时，超过处理上限的图片会在结果中返回 status: failed、failure: too_large |
| 429 quota_exceeded | 本月额度已用完 |
| 503 busy | 服务器繁忙，请稍后重试 |