Image Converter API

How to use the Image Converter API

Convert JPEG, PNG, WebP, AVIF, GIF and HEIC images to WebP, AVIF, JPEG or PNG — one image or up to ten per call, at the quality you choose, optionally resized.

Options

• format (required) — webp, avif, jpeg (or jpg), png.
• quality — 1–100. Defaults: JPEG 82, WebP 80, AVIF 60. Ignored for PNG and lossless output.
• lossless — true for exact-pixel WebP or AVIF (larger files).
• maxWidth / maxHeight — shrink to fit, keeping the aspect ratio. Never enlarges.
• background — the colour behind transparent areas when converting to JPEG, which has no transparency (default #ffffff). Without it transparent pixels would turn black.

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-converter?output=binary" \
  -H "Authorization: Bearer $image-converterSXPO_KEY" \
  -F file=@photo.png -F format=webp -F quality=80 -o photo.webp

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

Bash
curl -X POST "https://tools.toolsxpo.com/v1/image-converter?format=avif&maxWidth=1200&output=binary" \
  -H "Authorization: Bearer $image-converterSXPO_KEY" -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg -o photo.webp

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-converter", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.image-converterSXPO_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ images: [{ imageUrl: "https://example.com/a.jpg" }, { imageUrl: "https://example.com/b.png" }], format: "webp", quality: 80 }),
});
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.

Choosing a format

• WebP — the safe default: much smaller than JPEG/PNG, supports transparency, works in every current browser.
• AVIF — usually the smallest at the same visual quality; slower to encode (it counts 3× toward billing).
• JPEG — maximum compatibility for photos; no transparency.
• PNG — lossless; best for screenshots, logos and anything you will edit again.