edit_image
Edit images or create new ones from reference images via OpenRouter models, with optional masks and saved results.
Instructions
Edit an image (or create one from reference images) with an OpenRouter image model.
Call list_image_models first to choose a model, picking one whose inputs column
says "text+image". Options are checked against the model before anything is sent.
The input images are uploaded to a third-party model provider through OpenRouter: get the user's OK before sending client or project images to third-party providers. Each call costs money on the user's OpenRouter account; the result reports the cost.
All paths must be absolute (or start with "~"); relative paths are rejected. Results are saved next to the first input image (never overwriting it) with a JSON sidecar, unless output_dir is given. The result lists the saved paths, notes, failures, model, provider, time and cost, plus JPEG previews.
Args:
prompt: The change to make, e.g. "make it dusk with warm window light".
model: Model id from list_image_models.
images: Absolute paths of the input images. The first is the image being
edited; any others are references.
mask_path: Optional absolute path of a mask for the first image: white = change,
black = keep. The edit is composited locally, so only the white area
changes, but there may be a visible lighting seam at the mask edge where
new and old pixels meet; a soft mask edge or mask_feather_px helps.
Requires fit="preserve".
mask_feather_px: Blur radius in pixels for the mask edge; by default it is
chosen from the image size.
fit: "preserve" (default) returns each result at exactly the first input's
pixel size: the server picks the model's closest aspect ratio, then scales
and crops back (padding the input first if no ratio is close). With
fit="preserve" don't pass aspect_ratio or size. "model" keeps the size the
model returns and lets you choose aspect_ratio.
n: Number of images, 1 to 10. Above the model's max n, the server splits them
into several calls (each billed) and says so in the notes.
aspect_ratio: One of the model's aspect ratios (only with fit="model").
resolution: One of the model's resolution tiers.
size: Exact pixel size such as "1024x1024" (only with fit="model").
quality: One of the model's quality values.
seed: Integer for repeatable results, for models that support it.
background: One of the model's background values, e.g. "transparent".
output_format: One of the model's output formats, e.g. "png".
output_dir: Folder to save into instead of next to the first input. Must be
an absolute path or start with "~".
filename_prefix: File name stem; defaults to the first input's name.
provider_options: Provider passthrough options as a flat dict, e.g.
{"moderation": "low"}. Keys must be in the model's passthrough parameters
(see get_image_model); the server sends each key to every provider that
allows it. Any other key is rejected before anything is spent.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| fit | No | preserve | |
| seed | No | ||
| size | No | ||
| model | Yes | ||
| images | Yes | ||
| prompt | Yes | ||
| quality | No | ||
| mask_path | No | ||
| background | No | ||
| output_dir | No | ||
| resolution | No | ||
| aspect_ratio | No | ||
| output_format | No | ||
| filename_prefix | No | ||
| mask_feather_px | No | ||
| provider_options | No |