개발자

이미지 압축 API

Bitinz 이미지 압축 API로 JPG, PNG, WebP, AVIF를 압축하세요. 워크플로의 이미지를 더 작게, 모든 계정에 무료 월간 할당량을 제공합니다.

인증

대시보드에서 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	서버가 바쁨, 잠시 후 다시 시도