Convert and compress images with the API

Two endpoints cover almost everything you do to an image before putting it on the web:

Both take one image or up to ten in a call, and accept the same three kinds of input.

Send images the way you already have them

1. Upload files

Bash
curl -X POST "https://tools.toolsxpo.com/v1/image-converter?output=binary" \
  -H "Authorization: Bearer $TOOLSXPO_KEY" \
  -F file=@photo.png -F format=webp -F quality=80 \
  -o photo.webp

Repeat -F file=@… for a batch. Every other form field is an option.

2. Send the bytes as the body

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

3. Point at a URL, or send base64

Bash
curl -X POST "https://tools.toolsxpo.com/v1/image-converter" \
  -H "Authorization: Bearer $TOOLSXPO_KEY" -H "Content-Type: application/json" \
  -d '{"format":"avif","maxWidth":1200,"images":[{"imageUrl":"https://example.com/a.jpg"},{"imageUrl":"https://example.com/b.png"}]}'

image takes base64 or a data: URL; imageUrl takes any public http(s) URL up to 20 MB. A GET works too — ?imageUrl=…&imageUrl=…&format=webp.

In your code

JavaScript (Node 20+)

JAVASCRIPT
import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const form = new FormData();
form.append("file", await openAsBlob("photo.jpg"), "photo.jpg");
form.append("format", "webp");
form.append("quality", "80");

const res = await fetch("https://tools.toolsxpo.com/v1/image-converter?output=binary", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.TOOLSXPO_KEY}` },
  body: form,
});
if (!res.ok) throw new Error((await res.json()).error.message);
await writeFile("photo.webp", Buffer.from(await res.arrayBuffer()));
console.log("credits", res.headers.get("x-toolsxpo-credits"), "saved", res.headers.get("x-toolsxpo-saved-percent") + "%");

Python

PYTHON
import os, requests

res = requests.post(
    "https://tools.toolsxpo.com/v1/image-compressor",
    headers={"Authorization": f"Bearer {os.environ['TOOLSXPO_KEY']}"},
    files=[("file", open("a.jpg", "rb")), ("file", open("b.png", "rb"))],
    data={"quality": "70", "maxWidth": "1600"},
)
for r in res.json()["data"]["results"]:
    print(r["name"], r.get("url"), r.get("savedPercent"), r.get("error"))

What you get back

JSON with a download link, by default. data.results has one entry per image with a url — download it, put it in an <img>, store it, or hand it to the next system — and expiresAt: links are kept for your plan's file retention. Each entry also has format, width, height, inputBytes, bytes, savedPercent, quality, engine and warnings. An image that failed has ok: false and an error; the others still succeed. data.summary totals the call.

JSON
{ "ok": true,
  "data": { "results": [ { "ok": true, "format": "webp", "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 } }

Download it like any file:

Bash
curl -s -X POST "https://tools.toolsxpo.com/v1/image-converter" -H "Authorization: Bearer $TOOLSXPO_KEY" \
  -H "Content-Type: application/json" -d '{"imageUrl":"https://example.com/a.jpg","format":"webp"}' \
  | jq -r '.data.results[0].url' | xargs curl -s -o a.webp

Inline instead: send "output": "base64" and each entry carries base64 rather than a link; nothing is stored. Links are unguessable but public until they expire, so use this (or the binary response) for images that must not be stored.

The file itself with ?output=binary or Accept: image/*: a single image comes back as the image, a batch as a ZIP with a results.json describing each one. The numbers are in X-ToolsXpo-Credits, -Width, -Height, -Format, -Bytes, -Saved-Percent, -Quality and -Engine headers. Errors are always JSON.

Parameter reference

Every request needs one image source: image, imageUrl, an uploaded file, or images for a batch — never both a single source and images. All other fields are optional except the converter's format. The same names work as JSON fields, query parameters and form fields.

Image source (both endpoints)

image-converter options

image-compressor options

Query-string only

Response reference

Each entry in data.results

data.summary

meta (every tool)

Binary responses (?output=binary)

Errors

Cost

1 credit per call, plus 1 per billable unit. An image's units are 0.2 × input megapixels + output megapixels × (3 for AVIF, else 1), at least 0.25; a targetKb search counts double. A typical 1–2 MP web image costs 2–3 credits. Failed images cost nothing, and if every image in a call fails the call is refunded.

Limits and behaviour

• 10 images per call, 20 MB per image, 40 MB per call.
• The engine is chosen per image by cost: our in-Worker codecs for typical web images, Cloudflare Images for large photos. engine in the result says which.
• AVIF output is limited to roughly 1.5 MP (1,200 px per side for very large photos) — pass maxWidth for a big AVIF.
• Accepted input: JPEG, PNG, WebP, AVIF, GIF (first frame) and HEIC. SVG, TIFF and BMP are not accepted by the API.
• EXIF and GPS metadata are removed; phone photos are rotated upright first.

No code?

The Image Converter and Image Compressor pages do the same in your browser — free, nothing uploaded. And every field, including a file picker, is in the API Playground.