Image Compressor API

How to use the Image Compressor API

Make images smaller — by quality, or down to a target file size — keeping each image's format unless you choose another. One image or up to ten per call.

Options

• quality — 1–100, lower is smaller. Defaults: JPEG 75, WebP 75, AVIF 55. PNG is compressed losslessly.
• targetKb — aim for at most this many KB. The quality is lowered from quality until the file fits, and the result reports the quality it settled on. Counts 2× toward billing (it encodes several times).
• format — auto (default) keeps each image's format (GIF becomes PNG, HEIC becomes JPEG); or force jpeg, png, webp, avif.
• maxWidth / maxHeight — shrink to fit first. Often the biggest saving of all.
• background — fill for transparency when the output is JPEG.

Three ways to send images

Upload files (multipart) — the way most code already sends a file. Repeat -F file=@… for up to 10 images; any other field is an option:

Bash
curl -X POST "https://tools.toolsxpo.com/v1/image-compressor?output=binary" \
  -H "Authorization: Bearer $image-compressorSXPO_KEY" \
  -F file=@photo.png -F targetKb=200 -o smaller.jpg

A raw body — the image bytes, options in the query string:

Bash
curl -X POST "https://tools.toolsxpo.com/v1/image-compressor?quality=70&output=binary" \
  -H "Authorization: Bearer $image-compressorSXPO_KEY" -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg -o smaller.jpg

A URL or base64, as JSON — imageUrl (we fetch it, up to 20 MB) or image (base64 or a data: URL). For a batch, send images: [{ imageUrl }, { image }, …] — mix both freely:

JAVASCRIPT
const res = await fetch("https://tools.toolsxpo.com/v1/image-compressor", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.image-compressorSXPO_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ images: [{ imageUrl: "https://example.com/a.jpg" }, { imageUrl: "https://example.com/b.png" }], targetKb: 200 }),
});
const { data } = await res.json();
for (const r of data.results) if (r.ok) console.log(r.format, r.bytes, r.savedPercent);

A GET works too: ?imageUrl=…&imageUrl=…&OPTION=… (repeat imageUrl for a batch).

What comes back

• A download link (default): data.results[] has one entry per image with a url you can download, embed or pass on, and expiresAt — links last for your plan's file retention. Each entry also has format, contentType, width, height, inputBytes, bytes, savedPercent, quality, engine and warnings. Failed images have ok: false and an error, and cost nothing. data.summary totals the call.
• Base64 instead: send output: "base64" and each entry carries the image as base64 rather than a link — nothing is stored.
• The file itself: add ?output=binary to the URL (or send Accept: image/*). One image comes back as the image; a batch as a ZIP with a results.json inside. Credits, size and format are in X-ToolsXpo-* response headers. Errors are always JSON.

JSON
{ "ok": true,
  "data": { "results": [ { "ok": true, "format": "webp", "width": 1600, "height": 1067, "bytes": 143210,
                           "savedPercent": 82.4, "url": "https://ai-cdn.toolsxpo.com/…/9f2c….webp",
                           "expiresAt": "2026-10-11T09:30:00.000Z" } ],
            "summary": { "succeeded": 1, "failed": 0 } },
  "meta": { "credits": 3 } }

Links are unguessable but public: anyone holding one can open it until it expires. Use output: "base64" or ?output=binary for images that must not be stored.

Cost

A base price per call plus a charge per billable unit — both are shown in the price box on this page and returned in meta.credits with every response. An image's units are 0.2 × input megapixels + output megapixels × (3 for AVIF, else 1), at least 0.25 — so a typical 1–2 MP web image is about 2 units, and shrinking a big photo is cheap because the output is small. If every image in a call fails, the call is refunded.

Limits

• Up to 10 images per call, 20 MB each, 40 MB per call.
• Large photos (roughly over 3–4 megapixels) are processed by Cloudflare Images instead of our in-Worker codecs — engine tells you which. You do not need to do anything; the cheapest engine that can handle the image is chosen automatically.
• AVIF output is limited to about 1.5 MP in the Worker and 1,200 px per side on Cloudflare Images. For a large AVIF, pass maxWidth.
• HEIC and GIF input are accepted (GIF: first frame only). SVG, TIFF and BMP are not accepted by the API — convert those in the browser at toolsxpo.com.
• Metadata (EXIF, GPS) is removed; phone photos are rotated upright first.

In automations

Add the tool as a step. Its images are saved as files and the step output carries a url for each, so a later step can use {{previous_step.results.0.url}} — in an email, a webhook, or another image step's imageUrl. After a Source Files step, put {{previous_step}} in images to process every uploaded file.

Try it without code

Every field is available in the API Playground — including a file picker — and the web tool does the same thing in your browser for free, with nothing uploaded.

Never bigger than the original

If no smaller version exists at your settings — the image is already well compressed — the original is returned unchanged, with unchanged: true and a warning. You never get a "compressed" file that is larger.

Getting the most out of it

• Resize first. A 4000 px photo shown at 1200 px wastes ~90% of its bytes; maxWidth=1600 fixes that before quality matters.
• For the smallest files, combine format=webp (or avif) with a quality around 70.