Image API and MCP server

Quick start

Send the image as the request body and get the result back as the response body.

curl -X POST "https://imagecompressor.si/api/v1/compress?format=webp&target_bytes=100000" \  -H "Authorization: Bearer $IMAGECOMPRESSOR_API_KEY" \  --data-binary @photo.jpg \  -o photo.webp

The same call in three languages

import { ImageCompressor } from "@imagecompressor/sdk";import { readFile, writeFile } from "node:fs/promises"; const client = new ImageCompressor({ apiKey: process.env.IMAGECOMPRESSOR_API_KEY });const result = await client.compress(await readFile("photo.jpg"), {  format: "webp",  targetBytes: 100000,});await writeFile("photo.webp", result.data);

import osfrom imagecompressor import ImageCompressor client = ImageCompressor(os.environ["IMAGECOMPRESSOR_API_KEY"])with open("photo.jpg", "rb") as handle:    result = client.compress(handle.read(), format="webp", target_bytes=100000)result.save("photo.webp")

SDKs and command-line tool

Official clients with no dependencies: TypeScript/JavaScript and Python. The JavaScript package also installs the imagecompressor command for terminals and build scripts.

npm install @imagecompressor/sdk     # the client and the imagecompressor commandpip install imagecompressor          # the Python client export IMAGECOMPRESSOR_API_KEY=ic_live_...imagecompressor compress photos/ --recursive --out optimizedimagecompressor pipeline products/ --preset product-square

Endpoints

POST/api/v1/compress

Compress, convert, resize, crop, rotate or flip. Query: the options below, in any combination.

POST/api/v1/inspect

Facts about an image: format, dimensions, colour, EXIF, GPS position and fingerprints. Changes nothing.

POST/api/v1/remove-background

Remove the background. Query: background (transparent, a colour, gradient, blur or image), feather, refine, format, output. A picture background is sent as multipart parts image and background_image (Pro).

POST/api/v1/id-photo

Make an ID or passport photo. Query: preset or width_mm and height_mm (or width and height in pixels), dpi, crop, format, min_bytes, max_bytes, background, remove_background, sheet, output. GET lists the presets with their official sources.

POST/api/v1/favicon

Make a favicon pack as a ZIP: favicon.ico, PNG icons from 16 to 512 pixels, a maskable icon, site.webmanifest and favicon.html. Query: name, short_name, theme_color, background, padding, output.

POST/api/v1/gif

Edit an animated GIF. Query: crop, width, trim_start, trim_end, speed, reverse, every, colours, loop, format (gif or webp), output.

POST/api/v1/faces

Find the faces in a picture. Returns width, height and faces (x, y, width, height, score), largest first. Nothing is stored.

POST/api/v1/blur-faces

Blur or pixelate faces. Query: effect (blur or pixelate), strength, boxes (x,y,width,height;… to cover only those areas; without it every face found is covered), format, output.

POST/api/v1/upscale

Double an image's size with a super-resolution model. Query: format, output. Up to 1 megapixel free, 2.25 on Pro.

POST/api/v1/ocr

Read the text in an image. Query: lang (eng, slv, or both). Returns text and confidence as JSON.

POST/api/v1/sites/optimize

Scan a website's pages and convert their images to WebP. Body: url, quality, max_pages. Free scans 5 pages, Pro 50. Returns a job to poll.

GET/api/v1/sites/optimize/{id}

The job's status and, when done, the report with zip_url and replacements.

GET/api/v1/files/{id}

Download a stored result (when you asked for output=json).

GET/api/v1/formats

The formats this service reads and writes.

GET/api/v1/usage

This month's usage and your limits.

Compress options

format

auto, jpeg, png, webp, avif, gif, tiff, bmp, ico, jxl, pdf, tga or psd. Default auto keeps the input format. ico holds the image at 16 to 256 pixels. pdf is one page holding a JPEG. psd is a flat picture, with one layer when it has transparency.

mode

quality (default) uses quality. smart finds the smallest file that still looks like the original. lossless keeps every pixel (png, webp, avif, tiff, jxl, bmp, ico, tga, psd).

quality

1 to 100. Default 75.

target_bytes

Compress to at most this many bytes. Replaces quality.

crop, crop_ratio, crop_shape

x,y,width,height in pixels, or crop_ratio such as 16:9 for a centred crop. crop_shape=circle clears the corners.

rotate, flip

rotate: whole degrees clockwise, -359 to 359. A quarter turn is exact; any other angle grows the image and leaves its new corners transparent (the background colour in JPEG and BMP). flip: h, v or hv. Flips are applied before the rotation, both after the crop.

width, height, percent, fit, enlarge

width and height in pixels, or percent. fit: inside (default), exact, cover or contain. enlarge=true allows making an image larger.

print_width, print_height, dpi

print_width and print_height in millimetres with dpi (72 to 1200, default 300) resize to a size on paper and record the resolution in the file. Without enlarge=true a small image keeps its pixels and gets the lower resolution that prints it at that size, with the warning print_resolution_low. dpi alone only records the resolution.

max_width, max_height

Resize to fit, keeping the aspect ratio. Never enlarges.

background

A colour such as #ffffff, painted behind transparent pixels when the output is JPEG or BMP. Default white.

brightness … border

brightness, contrast, saturation, exposure: -100 to 100. grayscale=true. blur: 0 to 100. border in pixels with border_color (a colour or transparent).

enhance, sharpen, denoise, score

enhance=true, sharpen and denoise (0 to 100). crop_gravity=attention places a ratio crop on the subject. score=true adds X-IC-Similarity, how close the result is to the original.

watermark_*

watermark_text with watermark_color, watermark_opacity, watermark_size and watermark_position (tl, tc, tr, cl, c, cr, bl, bc, br or tile). A logo is sent as the multipart part watermark_image (Pro).

metadata

strip (default), keep, no_gps (keep camera and date, drop the location) or color (colour profile only).

fingerprint

true adds X-IC-Fingerprint, a perceptual hash for finding duplicates.

output

binary (default) returns the image. json stores it for an hour and returns a link.

Response headers: X-IC-Original-Bytes, X-IC-Bytes, X-IC-Width, X-IC-Height, X-IC-Format, X-IC-Outcome, X-IC-Warnings and X-IC-Duration-Ms (processing time).

Limits

• Free: 1,000 requests and 100 AI requests a month, 120 a minute, files up to 20 MB.
• Pro: 20,000 requests and 2,000 AI requests a month, 600 a minute, files up to 200 MB.
• One request is one credit, whatever options it uses. The website optimizer counts one request per image it converts.
• Background removal, upscaling and image to text are AI requests and count against the AI allowance, not the ordinary one. A pipeline that runs a model counts as one request of each kind. X-Quota-Meter says which allowance a response was counted against.
• Test keys (ic_test_…) are for building and CI: they never use your quota, take files of up to 1 MB and allow 50 requests a day. Their responses carry X-IC-Test-Mode: true.
• A live key can have a monthly limit of its own, set when you create it, so that one integration cannot use up the whole account's quota.
• We email the account owner once when 80% of a monthly quota is used and once when it is used up.
• We never store what you upload. Results you ask for as a link are deleted after one hour.

Errors

Errors are JSON with a code and a message. 429 and 503 responses carry a Retry-After header.

{ "error": { "code": "file_too_large", "message": "…" } }

Pipelines and jobs

A pipeline runs several steps on one image in one request: remove the background, resize, convert, compress. Steps can carry conditions, a dry run shows what would happen, and a job runs a pipeline over many images in the background. Pipelines and jobs need a Pro plan; a free account gets upgrade_required (403).

curl -X POST "https://imagecompressor.si/api/v1/jobs" \  -H "Authorization: Bearer $IMAGECOMPRESSOR_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: order-1001" \  -d '{    "inputs": [{ "url": "https://example.com/a.jpg" }, { "url": "https://example.com/b.png" }],    "pipeline": { "steps": [      { "op": "resize", "when": { "min_width": 2561 }, "params": { "width": 2560 } },      { "op": "compress", "params": { "format": "webp", "mode": "smart" } }    ] },    "webhook_url": "https://example.com/hooks/images"  }'

Webhooks

Give a job a webhook_url and we POST the finished job there, signed with your account's secret (Standard Webhooks). A failed delivery is retried after 5 seconds, 30 seconds and 2 minutes. Verify the signature before trusting the body.

import { verifyWebhook } from "@imagecompressor/sdk"; // body: the raw request body, exactly as receivedconst event = await verifyWebhook(process.env.IMAGECOMPRESSOR_WEBHOOK_SECRET, body, request.headers);if (event.type === "job.finished") {  for (const result of event.data.results) console.log(result.status, result.url);}

OpenAPI and API explorer

The whole API is described in an OpenAPI 3.1 document you can load into any client generator or API tool. The explorer below is built from it: pick an operation, add your key and a file, and send a real request.

Download openapi.jsonService status

Loading the API description…

MCP server

Connect your AI coding agent and ask it to optimize the images in your project or on your site. Tools: compress_image, convert_image, remove_background, optimize_website, get_website_report and get_usage.

Endpoint (Streamable HTTP)

https://imagecompressor.si/api/mcp

Example configuration

{  "mcpServers": {    "imagecompressor": {      "type": "http",      "url": "https://imagecompressor.si/api/mcp",      "headers": {        "Authorization": "Bearer ic_live_..."      }    }  }}

optimize_website returns a replacement map, so the agent can update every image reference for you.

Website Optimizer over MCP

Scans made in the Website Optimizer can be read by an agent, and their replacements applied to a project on your own computer. The tools follow contract version 1: every result carries contract_version, fields are only ever added within a version, and a breaking change gets new tool names.

Hosted server, reads only (key permission: sites)

list_website_scans()get_website_scan(scan_id)list_website_pages(scan_id, status?, search?, offset?, limit?)list_website_assets(scan_id, kind?, status?, finding?, page?, search?, offset?, limit?)get_replacement_mapping(scan_id, offset?, limit?)get_agent_prompt(scan_id, agent?)

Local server, in your project folder

imagecompressor mcp --root . load_replacement_package(path | scan_id)find_references(package_id?)preview_replacements(package_id?)            -> plan_id, diffapply_replacements(plan_id, approved: true)  -> backup_idvalidate_replacements(plan_id?)replacement_report(plan_id?)rollback(backup_id?, approved: true)

The local server reads and writes only inside the folder it is started for, shows every change as a diff first, changes nothing without approved: true and a plan it has shown in this session, backs up every file it touches, and never uploads your source code.