Convert format
https://api.imagemcpserver.com/v1/convert-formatA straight format conversion with no model in the loop. Reach for it when a downstream tool only accepts one format, or when you want PNG screenshots delivered as WebP.
Overview
Convert an image between PNG, JPEG, WebP and other common formats.
Flat 1 credit per call.
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. |
targetFormat | string | Output format — png, jpeg/jpg, webp, gif, tiff, avif. Defaults to "png". SVG is not a valid target: use the text-to-SVG endpoint for vector output. Encoder settings are fixed — WebP and JPEG are written at quality 80, AVIF at 50, TIFF is JPEG-compressed, and only PNG is lossless. |
responseFormat | string | Either "url" (default) or "b64_json". The hosted result.imageUrl is returned either way; b64_json adds result.b64_json and result.imageBase64. |
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/convert-format" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/photo.png",
"targetFormat": "webp"
}'imagemcp.js convert --image ./photo.png --format webp --out ./photo.webpconst res = await fetch("https://api.imagemcpserver.com/v1/convert-format", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEMCP_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"image": "https://example.com/photo.png",
"targetFormat": "webp"
}),
});
const data = await res.json();
console.log(data.result.imageUrl);import os
import requests
res = requests.post(
"https://api.imagemcpserver.com/v1/convert-format",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"image": "https://example.com/photo.png",
"targetFormat": "webp"
},
timeout=120,
)
print(res.json()){
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "convert_format",
"arguments": {
"image": "https://example.com/photo.png",
"targetFormat": "webp"
}
}
}Response
Response fields
| Field | Type | Description |
|---|---|---|
result.imageUrl | string | Converted image (hosted URL). |
result.originalFormat | string | Format detected on the input. |
result.targetFormat | string | Format written. |
result.mimeType | string | MIME type of the output. |
result.width | number | Width of the converted image in pixels. |
result.height | number | Height of the converted image in pixels. |
result.originalSize | string | Size of the decoded input, in KB. |
result.convertedSize | string | Size of the written output, in KB. |
{
"success": true,
"message": "Image converted to WEBP successfully",
"deductedCredits": 1,
"userCredits": 2417,
"result": {
"imageUrl": "https://cdn.imagemcpserver.com/convert/convert_4471928.webp",
"originalFormat": "PNG",
"targetFormat": "WEBP",
"mimeType": "image/webp",
"width": 1536,
"height": 1024,
"originalSize": "2184.6 KB",
"convertedSize": "196.3 KB",
"latency": "0.31s",
"cost": "$0.0000",
"deductedCredits": 1,
"userCredits": 2417
}
}When it fails
success: false with a message. See errors & troubleshooting for the status codes and whether a retry is worth it.FAQ
How is this different from compress_image?
convert_format changes the container without a quality setting and returns a hosted URL; compress_image re-encodes at a quality you choose, reports how much size was saved, and returns base64 bytes with no hosted copy. Use compress when the goal is a smaller file.
Does converting preserve transparency, animation and EXIF?
Partly. PNG, WebP and AVIF keep the alpha channel; JPEG and TIFF flatten it to solid black and GIF keeps only 1-bit transparency. Animation is never preserved — every conversion reads the first frame only, including GIF to GIF. EXIF, the ICC profile and the orientation tag are always stripped, so rotate phone photos before converting.