Start Iterative Edit Session
start_edit_sessionBegin a multi-turn image editing session. Provide initial images and a prompt to start iterative refinements, returning a session ID for subsequent edits.
Instructions
Begin a stateful multi-turn edit session. Returns a session_id you then pass to continue_edit_session to iteratively refine the image (each turn uses the previous turn's output as the input). Use end_edit_session when done.
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 | 1–8 input images to seed the session (same source formats as edit_image). | |
| 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 |
| 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. | |
| session_id | Yes | ||
| turn | Yes |