驗證
在控制台建立 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 | 伺服器忙碌中，請稍後重試 |