Edit image
https://api.imagemcpserver.com/playground/editSend an image plus an instruction and get the edited result back. This is the endpoint for retouching, background swaps, object removal, restyling and any change that is easier to describe than to mask. The image is passed to the model as a reference, so the more specific the instruction, the more faithful the edit.
Overview
Change an existing image with natural-language instructions.
Billed at the model's rate. With action: "remove_bg" the call costs 8 credits and with action: "upscale" it costs 15.
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. |
promptrequired | string | The edit to make. Optional only when action is "remove_bg" or "upscale", where a default instruction is filled in. |
action | "edit" | "remove_bg" | "upscale" | Defaults to "edit". The other two switch to fixed instructions and fixed credit costs. |
model | string | Model id. Defaults to google/gemini-2.5-flash-image. |
aspectRatio | string | Output aspect ratio. Defaults to "1:1". |
responseFormat | "url" | "b64_json" | Defaults to "url". Pass "b64_json" to also receive result.b64_json and result.imageBase64 alongside the hosted URL. |
Examples
The same call in five forms. 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/playground/edit" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/photo.jpg",
"prompt": "Replace the background with a snowy mountain resort at dusk, keep the subject lighting intact",
"action": "edit"
}'imagemcp.js edit \
--image ./photo.jpg \
--prompt "Replace the background with a snowy mountain resort at dusk" \
--out ./edited.pngconst res = await fetch("https://api.imagemcpserver.com/playground/edit", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.IMAGEMCP_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"image": "https://example.com/photo.jpg",
"prompt": "Replace the background with a snowy mountain resort at dusk, keep the subject lighting intact",
"action": "edit"
}),
});
const data = await res.json();
console.log(data.result.imageUrl);import os
import requests
res = requests.post(
"https://api.imagemcpserver.com/playground/edit",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"image": "https://example.com/photo.jpg",
"prompt": "Replace the background with a snowy mountain resort at dusk, keep the subject lighting intact",
"action": "edit"
},
timeout=120,
)
print(res.json()){
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "edit_image",
"arguments": {
"image": "https://example.com/photo.jpg",
"prompt": "Replace the background with a snowy mountain resort at dusk, keep the subject lighting intact",
"action": "edit"
}
}
}Response
Response fields
| Field | Type | Description |
|---|---|---|
result.imageUrl | string | Public URL of the edited image. |
result.action | string | Action that was applied. |
result.hasInputImage | boolean | Always true for a successful edit. |
deductedCredits | number | Credits taken for this call. |
userCredits | number | Balance remaining after the call. |
{
"success": true,
"message": "Image processed successfully via OpenRouter Images API",
"deductedCredits": 15,
"userCredits": 2447,
"result": {
"imageUrl": "https://cdn.imagemcpserver.com/gen/gen_7362514.png",
"prompt": "Replace the background with a snowy mountain resort at dusk",
"action": "edit",
"hasInputImage": true,
"referenceImagesCount": 1,
"model": "google/gemini-2.5-flash-image",
"aspectRatio": "1:1",
"seed": 220914,
"latency": "5.03s",
"cost": "$0.0380",
"deductedCredits": 15,
"userCredits": 2447
}
}When it fails
success: false with a message. See errors & troubleshooting for the status codes and whether a retry is worth it.FAQ
Do I need to supply a mask?
No. The edit is driven by your instruction rather than a mask channel — describe the region you want changed in the prompt.
What is the difference between edit_image and remove_background?
edit_image with action "remove_bg" routes through the general image model, while remove_background runs a dedicated cutout model. For clean alpha cut-outs, use remove_background.