edit_image · POST /playground/edit · ~10 credits

Edit an image by describing the change.

No mask, no layers, no selection tool. Send the picture and a sentence about what should be different, and the edited version comes back as a hosted URL. It is the same operation whether your Node service calls it or your coding agent does.

Try it in the playground Endpoint reference

Six edits people actually need

Each of these is one request. The prompt column is the whole instruction — there is no second step where someone opens Photoshop.

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.

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.

curl -X POST "https://api.imagemcpserver.com/playground/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"
  }'

Four rules for edits that hold up

  1. 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.

  2. 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. 3

    Leave aspectRatio alone by default

    Setting it re-frames the picture. Omit it and the source dimensions survive the edit untouched.

  4. 4

    Feed the style back in

    Put your last approved asset in referenceImages so edit number nine still matches edit number one.

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.

  1. generate_image

    Draft the scene from a prompt.

  2. edit_image

    Fix the one thing that is wrong.

  3. remove_background

    Cut the subject out cleanly.

  4. 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 and they execute in parallel. See the batch endpoint.

Image editing API questions

Do I have to draw a mask to inpaint?

No. 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 that has no cursor.

Will editing change the dimensions of my image?

Only if you ask it to. Leave aspectRatio out and the source dimensions are preserved. Setting it 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 for general changes, inpaint for a localised fix, remove_bg for a cutout, upscale for resolution. remove_bg and upscale are also available as their own tools with their own flat prices, which is usually the clearer choice.

Can I keep a brand style across several edits?

Yes — pass referenceImages alongside the source. The extra images steer palette, lighting and treatment, so a batch of ten edits comes back looking like one set rather than ten unrelated pictures.

How many credits does an edit cost?

The cost of the model the call routes to, around 10 credits on the default. With your own OpenRouter key connected on a paid plan it is a flat 2 credits and OpenRouter bills you for the model.

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.

Create a free account Connect your client