Compress image — POST /v1/compress
Updated
https://api.imagemcpserver.com/v1/compressRe-encodes an image at the quality and format you choose and returns the result as base64 along with before/after sizes. Two uses dominate: trimming assets before they ship to a browser, and shrinking images before they are pushed back into an agent's context window.
Overview
Shrink an image's file size with quality control, and report exactly how much was saved.
Flat 1 credit per call. No model is involved, so it is fast and cheap.
Pricing, examples and when to use it: Image compression API.
Request
Headers
| Field | Type | Description |
|---|---|---|
Authorizationrequired | string | Bearer <IMAGEMCP_API_KEY>. The header x-api-key: <key> is accepted as an alternative. |
Content-Typerequired | string | application/json |
Body parameters
| Field | Type | Description |
|---|---|---|
imagerequired | string | Input image as an https URL or a base64 data URI. imageBase64 is accepted as an alias for the same value. |
quality | number | Encoder quality 1–100 (default 70, clamped). For PNG it switches on lossy palette quantisation — and a quality is always applied — so PNG output here is never lossless. |
targetFormat | "webp" | "jpeg" | "png" | Output format. Defaults to "webp"; jpg is accepted as jpeg. Any other value is encoded as WebP. |
Examples
The same call in every form we support. The MCP tab is what an MCP client sends under the hood; the CLI tab is what an agent with the agent skill runs.
curl -X POST "https://api.imagemcpserver.com/v1/compress" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/large-photo.png",
"quality": 70,
"targetFormat": "webp"
}'imagemcp.js compress --image ./large-photo.png --quality 70 --format webp --out ./small.webpconst res = await fetch("https://api.imagemcpserver.com/v1/compress", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEMCP_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"image": "https://example.com/large-photo.png",
"quality": 70,
"targetFormat": "webp"
}),
});
const data = await res.json();
console.log(data.result.savedPercentage);import os
import requests
res = requests.post(
"https://api.imagemcpserver.com/v1/compress",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"image": "https://example.com/large-photo.png",
"quality": 70,
"targetFormat": "webp"
},
timeout=120,
)
print(res.json()){
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "compress_image",
"arguments": {
"image": "https://example.com/large-photo.png",
"quality": 70,
"targetFormat": "webp"
}
}
}Response
Response fields
| Field | Type | Description |
|---|---|---|
result.image | string | Compressed image as a base64 data URI. |
result.originalSize | string | Input size, e.g. "4302.4 KB". |
result.compressedSize | string | Output size in the same units. |
result.savedPercentage | string | How much was saved, e.g. "91.2%". |
result.format | string | The requested format, upper-cased. Over REST any value other than jpeg, jpg, png or webp is encoded as WebP but still labelled as requested — read the MIME prefix of result.image for the real type. |
{
"success": true,
"message": "Image compressed successfully",
"deductedCredits": 1,
"userCredits": 2418,
"result": {
"image": "data:image/webp;base64,UklGRl4…",
"originalSize": "4302.4 KB",
"compressedSize": "380.2 KB",
"savedPercentage": "91.2%",
"quality": "70%",
"format": "WEBP",
"latency": "0.42s",
"cost": "$0.0000",
"deductedCredits": 1,
"userCredits": 2418
}
}When it fails
success: false with a message. See errors & troubleshooting for the status codes and whether a retry is worth it.FAQ
Is the compressed image returned as a URL?
No — it comes back as a base64 data URI in result.image, together with the original and compressed sizes.
What quality should I use?
70 is the default and holds up well for web delivery. Drop toward 40–50 when you are shrinking images to fit an agent's context window and fine detail does not matter.