01
Replace a background
"Put this sofa in a sunlit Scandinavian living room with oak floors"
Turns one studio shot into a whole catalogue of settings without a photographer.
edit_image · POST /v1/edit · model rate, 15 credits by default
AI image editing API: change any image with a prompt
An AI image editing API takes an existing image and a written instruction, then returns the modified version — a swapped background, a removed object, a corrected exposure — leaving the rest of the picture intact.
This one is maskless. You describe the region in words instead of painting a selection, which is what makes it callable by an agent that has no cursor. It is the same operation whether your Node service posts to /v1/edit or your coding assistant calls the edit_image MCP tool.
By the imagemcpserver.com teamUpdated
- 0
- masks to draw
- 4
- edit actions
- 2
- ways to call it
What an image editing API does, and why the mask matters
Most inpainting APIs want two inputs beyond the prompt: the image, and a mask marking exactly which pixels to regenerate. That mask has to come from somewhere — a brush in a UI, or code that segments the picture first. It is a reasonable design for a photo editor with a human in front of it, and a poor one for anything automated.
A maskless endpoint moves the selection into the sentence. “Remove the person on the left” is a region description the model can resolve on its own, so the caller never needs to know where that person is in pixel coordinates. That is the difference between an API a designer drives and one a script or an agent can drive unattended.
Mask-based editing
Image + mask + prompt
Precise, and predictable about which pixels move. But something has to produce the mask, so an automated caller needs a segmentation step before it can edit at all.
This endpoint
Image + prompt
One call, no pre-processing. The trade is that the model decides the boundary, so naming what should stay unchanged does real work in the prompt.
Editing versus generation: what actually changes
The two endpoints look almost identical on the wire. What separates them is one required field and one default, and those two differences are where most confused output comes from.
| POST /v1/generate | POST /v1/edit | |
|---|---|---|
| Input image | Optional — supplying one turns the call into image-to-image | Required |
| What the prompt means | A description of the picture to create | An instruction about what to change |
| aspectRatio when omitted | Defaults to 1:1 | Keeps the source dimensions |
| Typical failure | Output ignores part of a long prompt | Model rebuilds more of the frame than you wanted |
If you are starting from nothing rather than from a picture, you want the generation endpoint instead.
Six edits people actually need
Each of these is one request. The prompt is the whole instruction — there is no second step where someone opens Photoshop.
02
Remove an object
"Remove the traffic cone in the bottom right and fill the pavement naturally"
Cleans up stock and user-submitted photos before they reach a page.
03
Restyle
"Redraw this photograph as a flat vector illustration in two colours"
Brings mismatched imagery into one house style across a site.
04
Retouch
"Brighten the exposure, warm the white balance, sharpen the label text"
The boring corrections that otherwise queue up behind a designer.
05
Add an element
"Add steam rising from the cup, keep everything else identical"
Small additions that would otherwise mean regenerating the whole image.
06
Re-frame
aspectRatio: "21:9" with "extend the scene left and right"
One asset becomes a hero banner, a card and a social preview.
What a request looks like
Two required fields — the image and the prompt. The image can be a public https URL or a base64 data URI, so an agent can edit something it just generated without ever writing it to disk.
Note aspectRatio in the response below. The request did not set it, so the edit kept the source dimensions and the field comes back as "source" rather than a ratio.
Request
curl -X POST "https://api.imagemcpserver.com/v1/edit" \
-H "Authorization: Bearer $IMAGEMCP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://cdn.example.com/product/chair-raw.jpg",
"prompt": "Remove the price tag and place the chair on a
seamless cream backdrop with a soft shadow",
"action": "edit"
}'And what comes back
Every response carries deductedCredits and userCredits, so a script always knows what the call cost and what is left before it queues the next one.
Response
{
"success": true,
"deductedCredits": 15,
"userCredits": 2447,
"result": {
"imageUrl": "https://cdn.imagemcpserver.com/gen/gen_7362514.png",
"action": "edit",
"model": "google/gemini-2.5-flash-image",
"hasInputImage": true,
"referenceImagesCount": 1,
"aspectRatio": "source",
"seed": 220914,
"latency": "5.03s"
}
}Python and JavaScript
It is one POST with a bearer token, so there is no SDK to install and nothing to keep up to date. The header x-api-key works as an alternative to Authorization if that suits your client better.
Python
import os, requests
r = requests.post(
"https://api.imagemcpserver.com/v1/edit",
headers={"Authorization": f"Bearer {os.environ['IMAGEMCP_API_KEY']}"},
json={
"image": "https://cdn.example.com/product/chair-raw.jpg",
"prompt": "Remove the price tag, keep the lighting identical",
},
timeout=120,
)
data = r.json()
print(data["result"]["imageUrl"], data["deductedCredits"])JavaScript
const 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: sourceUrl,
prompt: "Remove the price tag, keep the lighting identical",
}),
});
const { result, deductedCredits } = await res.json();
console.log(result.imageUrl, deductedCredits);Every field, and what it changes
The same body works for the REST endpoint and the edit_image MCP tool, because the tool is a thin wrapper over the endpoint.
| Field | Accepts | What it does |
|---|---|---|
image | string · required | The picture to edit, as an https URL or a base64 data URI. imageBase64 is accepted as an alias for the same value. |
prompt | string · required | The change to make. Optional only for the remove_bg and upscale actions, which fill in a default instruction. |
action | edit · inpaint · remove_bg · upscale | Defaults to edit. inpaint follows the same path as edit; the other two switch to fixed instructions and fixed prices. |
model | string | A model ID such as google/gemini-2.5-flash-image. Omit it to use the account default. |
aspectRatio | 1:1 · 16:9 · 9:16 · 4:3 · 3:4 · 21:9 | Omit it on an edit and the source dimensions survive untouched. Setting it re-frames the picture. |
referenceImages | string[] | Extra images that steer palette, lighting and treatment without being copied outright. |
style | string | Recorded on the request and echoed back as result.style — it is not sent to the model. Put style direction in the prompt itself. |
responseFormat | url · b64_json | Defaults to url. b64_json adds the raw base64 alongside the hosted URL. |
The four actions
Only the first two are edits in the usual sense. Setting remove_bg or upscale does not re-prompt an image model at all — the request is handed to the same purpose-built pipeline the dedicated tool uses, so the result and the price are identical either way.
| action | What it does | Cost |
|---|---|---|
edit | Applies your instruction to the image. The default when the field is omitted. | Model's rate |
inpaint | Accepted as an alias — it routes exactly as edit does, so use whichever reads better in your code. | Model's rate |
remove_bg | Hands the call straight to the dedicated cut-out pipeline — the same code path remove_background uses. | 8 credits |
upscale | Hands the call to the dedicated super-resolution pipeline, the same one upscale_image uses. | 15 credits |
So choose on readability, not on quality. Calling remove_background or upscale_image directly says what you mean and needs no prompt; the actions exist so a caller already holding an edit request does not have to switch endpoints.
Four rules for edits that hold up
Maskless editing puts the boundary decision in the model’s hands, so the prompt has to do the work a selection would otherwise have done.
- 1
Name what stays, not just what changes
Adding "keep the composition and lighting identical" stops the model rebuilding the whole frame around one small fix. This is the single highest-value habit on a maskless endpoint.
- 2
One change per call
Two unrelated instructions in one prompt is where results get muddy. Chain two calls instead — the second edits the output URL of the first.
- 3
Leave aspectRatio alone by default
Omit it and the source dimensions survive the edit untouched, which the response confirms by returning "source". Set it only when you actually want to re-frame.
- 4
Feed the last approved asset back in
Put it in referenceImages so edit number nine still matches edit number one. The style field will not do this — it never reaches the model.
Editing is usually the middle of a chain
The output URL of one tool is valid input to the next, which is what lets an agent run a whole asset pipeline without a human in the loop.
generate_image
Draft the scene from a prompt.
edit_image
Fix the one thing that is wrong.
remove_background
Cut the subject out cleanly.
compress_image
Ship it at a sensible file size.
Running four sequential calls costs four round trips. If the steps are independent — ten product photos, all needing the same treatment — send them together through multicall, which fans them out concurrently and bills the batch as one deduction. See the batch endpoint.
What an edit costs
An edit is billed at the rate of the model it routes to, not by image size or prompt length. Iterating on wording is therefore cheap.
Fast model
8 credits
Quick corrections and iterating on an instruction.
Default model
15 credits
google/gemini-2.5-flash-image, where calls land unless you name a model.
Premium model
30 credits
When the edited asset ships to a customer.
Your OpenRouter key
2 credits
BYOK on any paid plan. OpenRouter bills the model directly.
If the model provider fails, the call answers 502 upstream_error and the credits are refunded automatically, so a retry loop cannot quietly drain a balance. Checking the balance is free — get_user_info never deducts credits. See plans and credit packs, or work through the BYOK break-even.
Where teams use it
Editing earns its place wherever the picture already exists and only one thing about it is wrong — which is most of the time, once a library has been built.
Product catalogues
One studio shot becomes a dozen listings: price tags removed, backgrounds swapped per marketplace, every frame cropped to the same ratio.
Read the walkthrough →
Ad and landing page variants
Take the approved hero and re-frame it for each placement rather than commissioning a new shoot per channel.
Read the walkthrough →
Editorial imagery
Bring stock and contributor photos into one house treatment so an archive of hundreds of posts still looks deliberate.
Read the walkthrough →
User-generated content
Clean up what people upload — straighten exposure, remove the stray object — before it reaches a public page.
Read the walkthrough →
Image editing API questions
How do I edit a photo with a prompt?
Send the picture and a sentence describing the change to POST /v1/edit. The image goes in the image field as an https URL or a base64 data URI, the instruction goes in prompt, and the edited result comes back as a hosted URL in result.imageUrl. There is no mask to draw and no editor to open — the instruction is the whole interface.
Is there an API for photo editing?
Yes, and there are two shapes of them. Fixed-function APIs expose one operation each — resize, background removal, colour correction. Generative editing APIs like this one take an arbitrary instruction and apply it, so a request that has never been anticipated still works. This server gives you both: /v1/edit for open-ended changes, and dedicated endpoints for background removal, upscaling, compression and format conversion.
Which AI can edit images with prompts?
Any image model that accepts an input reference. Calls route to google/gemini-2.5-flash-image by default, and passing a model ID sends the edit elsewhere. GET /v1/models lists what is live on your account with the credit cost of each, and it is free to call.
Do I have to draw a mask to inpaint?
No. Most inpainting APIs require a mask channel marking the pixels to regenerate. Here you describe the region in words — "replace the sky with an overcast morning", "remove the person on the left" — and the model resolves what to change. That is what makes the endpoint usable by an agent, which has no cursor to paint a selection with.
What is the difference between inpainting and outpainting?
Inpainting changes something inside the existing frame — patching out an object, replacing a surface. Outpainting extends the picture beyond its original edges. There is no separate outpaint action here: you approximate it by setting aspectRatio to a wider ratio than the source and asking in the prompt for the scene to continue outwards. How convincingly the new edge material blends depends on the model you route to, so it is worth testing before you rely on it.
Will editing change the dimensions of my image?
Only if you ask it to. Leave aspectRatio out of an edit and the source dimensions are preserved — the response confirms it by returning result.aspectRatio as "source". Setting the field deliberately re-frames the picture, which is how you turn a square product shot into a 16:9 banner.
What does the action field do?
It picks the mode. edit is the default and applies your instruction. inpaint is accepted and follows the same path as edit. remove_bg and upscale are different in kind: rather than re-prompting an image model, the request is handed to the same dedicated pipeline behind the remove_background and upscale_image tools, at the same fixed prices of 8 and 15 credits. Calling those tools directly is clearer, but either entry point produces the same result.
Can I keep a brand style across several edits?
Pass referenceImages alongside the source image. The extra pictures steer palette, lighting and treatment, so a batch of ten edits comes back looking like one set. Note that the separate style field does not do this — it is recorded on the request and echoed back, but never reaches the model. Style direction belongs in the prompt text.
Can it handle batch processing?
Yes, through the multicall endpoint. Send an array of edits and they are executed concurrently rather than one after another, and the whole batch is billed as a single credit deduction. That is the right shape for a catalogue job where a hundred photos all need the same treatment.
How many credits does an edit cost?
The cost of the model the call routes to — 15 credits on the default, 8 on a fast model, 30 on a premium one. With your own OpenRouter key connected on a paid plan it is a flat 2 credits and OpenRouter bills you for the model directly. If the provider fails, the credits are refunded automatically.
Reference
Give your agent an editor
Thirty credits a month, free, no card. Enough to work out whether prompt-driven editing belongs in your pipeline before you pay for it.