edit_image
Edit or generate images from 1-8 reference images and a text prompt. Use it to keep a consistent style across assets, modify elements, combine images, or target changes with an optional mask.
Instructions
Create a new image that is guided by one or more existing images (1-8 reference files) plus a text prompt, save it to the project's generated-assets directory, and return a preview. The model sees every reference image and the prompt together, so use this tool whenever the result must stay consistent with images you already have: to keep one visual style across a whole set of assets, pass the same brand-board or style-reference image in reference_paths for every asset and describe the new subject in the prompt (for example 'In the style of the reference: a hero illustration of a lighthouse at dawn'). Also use it to modify an image (change colours, add or remove elements, restyle it) or to combine several images into one. For a brand-new image with no reference, use generate_image. MASKING: mask_path is an optional PNG the same size as the first reference whose transparent pixels mark the region to change. Masking is prompt-guided rather than pixel-exact: the model treats the mask as strong guidance and may adjust areas near the edge, so always describe the desired change in the prompt too. Paths may be absolute or relative to the server's working directory. SIZE: pass a preset name or explicit WIDTHxHEIGHT. Presets: 'square' (1024x1024), 'landscape' (1536x1024), 'portrait' (1024x1536), 'hero' (1920x1088), 'banner' (1536x512), 'auto' (model picks). Explicit sizes are rounded to the nearest multiple of 16 (minimum 256); the aspect ratio must be between 1:3 and 3:1 and neither side may exceed 3840. The result text reports the size actually produced, so check it if the exact pixel size matters. BACKGROUND: 'transparent' produces an alpha channel and requires output_format 'png' or 'webp' (never 'jpeg'); use it for logos, icons and cut-out illustrations. QUALITY: 'low' is fast and cheap (good for drafts and iteration), 'high' is slow (can take over a minute) and detailed; 'auto' lets the model choose. RETURNS: for each image, a text block with the absolute file path, final width x height, model, quality and the path of a .json sidecar holding the prompt and settings, followed by a small JPEG preview (longest side 512px) so you can inspect the result. The full-resolution file is already on disk; reference it by the returned path (for example as a site asset).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Preset name (square, landscape, portrait, hero, banner, auto) or WIDTHxHEIGHT. | square |
| prompt | Yes | What the new image should show; describe how the references should influence it. | |
| quality | No | auto, low (fast draft), medium, or high (slow, detailed). | auto |
| filename | No | Optional file name without extension. Defaults to a slug of the prompt plus a timestamp. Never overwrites. | |
| mask_path | No | Optional PNG mask for the first reference; transparent pixels mark the area to change. | |
| background | No | auto, opaque, or transparent (transparent requires png or webp). | auto |
| output_format | No | File format: png, jpeg, or webp. | png |
| reference_paths | Yes | 1-8 image files (png, jpeg, or webp) that guide the result. |