Edit or extend an existing image
edit_imageEdit images with text instructions: apply whole-image changes, inpaint masked areas, or combine multiple images into one scene.
Instructions
Edit existing image(s) with a text instruction. Covers three jobs:
Whole-image edit - pass one image and describe the change.
Inpainting - pass a
maskPNG whose transparent areas mark what to replace; everything else is preserved.Composition / style reference - pass several images and describe how to combine them (e.g. put the product from image 1 into the scene from image 2).
Input images must be png, jpg or webp. dall-e-3 cannot edit; use a gpt-image model.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| mask | No | Absolute path to a PNG mask with an alpha channel. Transparent pixels are the region the model may repaint; opaque pixels are kept. Must match the first input image's dimensions. | |
| size | No | Output dimensions as "WIDTHxHEIGHT", or "auto". | |
| model | No | Image model id. Omit or pass "auto" to use the best available model (tries gpt-image-2, then falls back if this API key lacks access). Pass an explicit id to control cost/quality: gpt-image-2, gpt-image-1.5, gpt-image-1, gpt-image-1-mini, dall-e-3. Any newer model id is also accepted and passed through unchanged. | |
| images | Yes | Absolute paths to the input image(s). With more than one, they are treated as references to combine. | |
| prompt | Yes | The edit instruction, or a description of the desired final image. | |
| quality | No | Render quality. | |
| filename | No | Base filename without extension. Defaults to a timestamp plus a slug of the prompt. With n > 1 an index is appended. | |
| background | No | ||
| output_dir | No | Directory to write the images into. Pass an absolute path (e.g. the current project's assets folder) when the images belong to a project. Defaults to /root/Pictures/claude-images. | |
| output_format | No | ||
| input_fidelity | No | Use "high" to preserve faces, logos and fine detail from the input. Not configurable on gpt-image-2, which is always high fidelity. | |
| return_preview | No | Return a downscaled copy of each image inline so you can actually look at the result and iterate. Set false to save tokens when the image is not going to be reviewed. | |
| output_compression | No |