Edit image — POST /v1/edit
Updated
https://api.imagemcpserver.com/v1/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.
Pricing, examples and when to use it: AI image editing 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. |
referenceImages | string[] | Extra reference images (https URLs or data URIs) sent alongside the input image — e.g. a product to place into the scene. |
promptrequired | string | The edit to make. Optional only when action is "remove_bg" or "upscale", where a default instruction is filled in. |
action | "edit" | "inpaint" | "remove_bg" | "upscale" | Send "edit" for a normal edit (the MCP tool and CLI always do); "inpaint" is an alias of edit. "remove_bg" and "upscale" run the dedicated pipelines at 8 and 15 credits. |
model | string | Model id. Defaults to google/gemini-2.5-flash-image. |
aspectRatio | string | Omit to keep the source image's dimensions (the response reports "source"). Pass a ratio such as 16:9 to reframe the edit. Over REST this needs action to be sent — with no action the call is framed 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 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/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/v1/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/v1/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": "source",
"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?
They run the same pipeline. edit_image with action "remove_bg" is dispatched to the dedicated cutout model behind remove_background (8 credits), and action "upscale" to the upscaler (15 credits). Call remove_background or upscale_image directly so your logs say what ran.