Edit Image
edit_imageEdit or compose images by providing 1–8 input images, a text prompt, and an optional mask. Swap backgrounds, retouch products, or combine references into a single composition.
Instructions
Edit or compose images with gpt-image-2. Give 1–8 input images plus a text prompt; optionally include a PNG mask whose transparent regions mark what to change (mask applies to the first image). Great for: swap backgrounds, retouch products, combine multiple reference images into one composition, maintain a character across scenes. gpt-image-2 always processes inputs at high fidelity (no input_fidelity knob needed). The edited image is saved to disk and returned inline.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Image description. gpt-image-2 handles very detailed prompts; use ALL CAPS or quote literal text you want rendered verbatim. | |
| images | Yes | Input images. Each entry can be: an absolute file path, a relative path (resolved from CWD), a file:// URL, an http(s):// URL, or a data:image/...;base64,... URL. PNG/WEBP/JPG, up to 50MB each. | |
| mask | No | Optional PNG mask — fully transparent pixels mark the editable region. Must match the first input image's dimensions and be <4MB. Accepts the same source types as `images`. | |
| size | No | Output dimensions. "auto" (default), one of the presets "1024x1024", "1536x1024", "1024x1536", or a custom "WxH" where both edges are multiples of 16, max edge ≤ 3840px, aspect ratio within 1:3–3:1, and total pixels 655,360–8,294,400. Outputs above 2K are beta. | auto |
| quality | No | Edit quality — same levels as generate. | auto |
| n | No | How many images to generate (1–10). Each counts toward rate limits and cost. | |
| background | No | Background behavior. "opaque" forces a filled background; "auto" lets the model pick. gpt-image-2 does NOT support transparent backgrounds — use a different model for that. | auto |
| output_format | No | File format. "png" (default, lossless), "jpeg" (smaller, lossy), "webp" (best compression). When omitted on continue_edit_session, the session's current format is kept. | |
| output_compression | No | Compression level 0–100 for jpeg/webp outputs. Ignored for png. Defaults to 100 (minimal compression). | |
| output_dir | No | Absolute or relative directory where generated images should be written. Defaults to $GPT_IMAGE_2_OUTPUT_DIR or a per-project subfolder under the OS config dir. The directory is created if missing. | |
| filename_prefix | No | Short label appended to the generated filename so you can find it later (e.g. "hero-banner"). Letters/digits/hyphens only; auto-sanitized. | |
| user | No | Optional end-user identifier forwarded to OpenAI for abuse monitoring. Pass a stable hashed user ID, not PII. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | ||
| prompt | Yes | ||
| requested | Yes | ||
| applied | Yes | ||
| images | Yes | ||
| usage | Yes | ||
| cost_usd_estimated | Yes | ||
| route | No | Which API route served the request (edit tools only): "direct" = /v1/images/edits, "responses" = Responses-API fallback (one image per call, undercounted cost). | |
| notes | No | Caveats about how the request was served. |