Compress an image to a target size

POST/v1/compress

Authorization

AuthorizationBearer token · headerrequired

ikb_live_… keys are issued manually — see /api/authentication. Ask for one at privacy@imagekbreducer.com.

Request body

requiredmultipart/form-data

filestringrequired

JPEG, PNG, or WebP. HEIC and AVIF are refused with 415 before any decode is attempted — this Worker cannot decode either (see /api/errors and /api/limits). Use the CLI or the web app for HEIC sources; for AVIF, convert first — the CLI runs this same wasm backend and refuses AVIF too, and the web app decodes AVIF only where the browser itself does.

targetstringrequired

1024-based: 50kb is 51 200 bytes.

formatstring

default: "keep"

Allowed:keepjpegpngwebp

allow_downscaleboolean

May the search shrink pixel dimensions to reach the target? With false, dimensions win and target-unreachable is possible.

default: true

Responses

200The compressed image.

string

400Error

errorstringrequired

Allowed:bad-requestempty-fileunauthorizedlength-requiredinput-too-largeunsupported-formatdecode-faileddimension-exceededtarget-unreachablerate-limitedrate-limiter-unavailableprocessing-timeoutnot-foundinternal

messagestringrequired

401Error

errorstringrequired

messagestringrequired

411Error

errorstringrequired

messagestringrequired

413Error

errorstringrequired

messagestringrequired

415Error

errorstringrequired

messagestringrequired

422target-unreachable (an answer, not a failure), decode-failed, or dimension-exceeded.

errorstringrequired

messagestringrequired

reasonstring

Allowed:FIXED_DIMENSIONSMIN_DIMENSIONFORMAT_FLOORBUDGET_EXHAUSTED

closestinteger

Bytes of the smallest file the search produced.

suggestionsobject[]

Show properties

Array of object

kindstringrequired

Allowed:allow-downscaleswitch-formatraise-targetaccept-closestkeep-searchinglower-min-quality

formatstring

bytesinteger

additionalEncodesinteger

minQualityinteger

429Error

errorstringrequired

messagestringrequired

500Error

errorstringrequired

messagestringrequired

503Error

errorstringrequired

messagestringrequired

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Bodymultipart/form-data

filestring*JPEG, PNG, or WebP. HEIC and AVIF are refused with 415 before any decode is attempted — this Worker cannot decode either (see /api/errors and /api/limits). Use the CLI or the web app for HEIC sources; for AVIF, convert first — the CLI runs this same wasm backend and refuses AVIF too, and the web app decodes AVIF only where the browser itself does.targetstring*1024-based: 50kb is 51 200 bytes.formatstringallow_downscalebooleanMay the search shrink pixel dimensions to reach the target? With false, dimensions win and target-unreachable is possible.

Request

curl -X POST "https://api.imagekbreducer.com/v1/compress" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -d '{
  "file": "string",
  "target": "50kb",
  "format": "keep",
  "allow_downscale": true
}'

const response = await fetch("https://api.imagekbreducer.com/v1/compress", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "multipart/form-data"
  },
  body: "{\n  \"file\": \"string\",\n  \"target\": \"50kb\",\n  \"format\": \"keep\",\n  \"allow_downscale\": true\n}"
});

Response

"string"

{
  "error": "bad-request",
  "message": "string"
}

{
  "error": "bad-request",
  "message": "string"
}

{
  "error": "bad-request",
  "message": "string"
}

{
  "error": "bad-request",
  "message": "string"
}

{
  "error": "bad-request",
  "message": "string"
}

{
  "error": "bad-request",
  "message": "string",
  "reason": "FIXED_DIMENSIONS",
  "closest": 0,
  "suggestions": [
    {
      "kind": "allow-downscale",
      "format": "string",
      "bytes": 0,
      "additionalEncodes": 0,
      "minQuality": 0
    }
  ]
}

{
  "error": "bad-request",
  "message": "string"
}

{
  "error": "bad-request",
  "message": "string"
}

{
  "error": "bad-request",
  "message": "string"
}