認証
ダッシュボードでAPIキーを作成し、HTTP Basic認証（ユーザー名 api、パスワード = キー）を使うか、Authorization: Bearer <key> を送信します。
curl --user api:YOUR_API_KEY ... # or curl -H "Authorization: Bearer YOUR_API_KEY" ...
画像を圧縮する
画像をリクエスト本文として /api/v1/shrink にPOSTします。任意のクエリパラメーター：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"
レスポンス
成功したリクエストは通常、status が done の 201 を返します。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
キューが長いときは、status が pending の 202 Accepted を返すことがあります。Location はダウンロード先ではなくジョブの状態を指します。画像を再送せず、このURLを保存してポーリングしてください。
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 で返されたURLに、1〜2秒ごとに GET /api/v1/results/{id} を送ります。pending は待機中（queuePosition が現在の順番）、processing は圧縮中を意味します。status が 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
}結果をダウンロードする
結果は期限が切れるまでダウンロードできます。期限後、URLは410を返します。
curl -o photo.min.jpg "https://bitinz.com/api/v1/results/<id>/download"
エラーコード
{ "error": { "code": "...", "message": "..." } }
| 401 unauthorized / invalid_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 | サーバーが混雑中。しばらくしてから再試行 |