gpt-image-2-mcp

Start Iterative Edit Session

start_edit_session

Start a multi-turn image editing session that returns a session ID, enabling iterative refinements where each edit uses the previous output as input.

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. The first turn hands off to a background job like every other image call: poll get_image_job for it, and the session_id arrives with its "completed" result.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`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
`user`	No	Optional end-user identifier forwarded to OpenAI for abuse monitoring. Pass a stable hashed user ID, not PII.
`model`	No	Model to use. One of "gpt-image-2.5-sunburst", "gpt-image-2.5-flare", "gpt-image-2"; defaults to "gpt-image-2.5-sunburst". The 2.5 variants accept the same parameters. Cost/token estimates assume gpt-image-2 pricing.
`images`	Yes	1–8 input images to seed the session (same source formats as edit_image).
`prompt`	Yes	Image description. gpt-image-2 handles very detailed prompts; use ALL CAPS or quote literal text you want rendered verbatim.
`quality`	No	Edit quality — same levels as generate.	auto
`background`	No	Background behavior. "opaque" forces a filled background; "transparent" asks for alpha (PNG) — verified working for the gpt-image-2 family, and the origin still decides, so check applied.background; "auto" lets the model pick.	auto
`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.
`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.
`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.
`output_compression`	No	Compression level 0–100 for jpeg/webp outputs. Ignored for png. Defaults to 100 (minimal compression).

Output Schema

TableJSON Schema

Name	Required	Description
`tool`	No
`turn`	No
`model`	No
`notes`	No
`route`	No
`state`	No
`usage`	No
`images`	No	Written image files — present once the job completed successfully.
`job_id`	No	Present on background hand-off — pass to get_image_job.
`prompt`	No
`applied`	No
`poll_hint`	No
`requested`	No
`session_id`	No	Identifies the session for later continue_edit_session calls; present once a turn has landed.
`started_at`	No
`async_after_ms`	No
`prompt_preview`	No
`cost_usd_estimated`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed17 schema fields changedv0.5.5Sep 23, 2026

changedInput schema / properties / background / description

Previous value: -"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."New value: +"Background behavior. \"opaque\" forces a filled background; \"transparent\" asks for alpha (PNG) — verified working for the gpt-image-2 family, and the origin still decides, so check applied.background; \"auto\" lets the model pick."

changedInput schema / properties / background / enum

Previous value: -[
-  "auto",
-  "opaque"
-]New value: +[
+  "auto",
+  "opaque",
+  "transparent"
+]

changedInput schema / properties / model / description

Previous value: -"Model to use. One of \"gpt-image-2\", \"gpt-image-2.5-flare\", \"gpt-image-2.5-sunburst\"; defaults to \"gpt-image-2\". The 2.5 variants accept the same parameters. Cost/token estimates assume gpt-image-2 pricing."New value: +"Model to use. One of \"gpt-image-2.5-sunburst\", \"gpt-image-2.5-flare\", \"gpt-image-2\"; defaults to \"gpt-image-2.5-sunburst\". The 2.5 variants accept the same parameters. Cost/token estimates assume gpt-image-2 pricing."

changedInput schema / properties / model / enum

Previous value: -[
-  "gpt-image-2",
-  "gpt-image-2.5-flare",
-  "gpt-image-2.5-sunburst"
-]New value: +[
+  "gpt-image-2.5-sunburst",
+  "gpt-image-2.5-flare",
+  "gpt-image-2"
+]

addedOutput schema / properties / async_after_ms

Added value: +{
+  "exclusiveMinimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / images / description

Added value: +"Written image files — present once the job completed successfully."

addedOutput schema / properties / job_id

Added value: +{
+  "description": "Present on background hand-off — pass to get_image_job.",
+  "type": "string"
+}

removedOutput schema / properties / notes / description

Removed value: -"Caveats about how the request was served."

addedOutput schema / properties / poll_hint
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / prompt_preview
```
Added value: +{
+  "type": "string"
+}
```

removedOutput schema / properties / route / description

Removed value: -"Which API route served the request (edit tools only): \"direct\" = /v1/images/edits, \"responses\" = Responses-API fallback (one image per call, undercounted cost)."

addedOutput schema / properties / session_id / description

Added value: +"Identifies the session for later continue_edit_session calls; present once a turn has landed."

addedOutput schema / properties / started_at
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / state

Added value: +{
+  "enum": [
+    "running",
+    "completed",
+    "failed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / tool
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / usage / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "input_tokens": {
-        "type": "number"
-      },
-      "input_tokens_details": {
-        "additionalProperties": false,
-        "properties": {
-          "image_tokens": {
-            "type": "number"
-          },
-          "text_tokens": {
-            "type": "number"
-          }
-        },
-        "type": "object"
-      },
-      "output_tokens": {
-        "type": "number"
-      },
-      "output_tokens_details": {
-        "additionalProperties": false,
-        "properties": {
-          "image_tokens": {
-            "type": "number"
-          },
-          "text_tokens": {
-            "type": "number"
-          }
-        },
-        "type": "object"
-      },
-      "total_tokens": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "input_tokens",
-      "output_tokens",
-      "total_tokens"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "input_tokens": {
+        "type": "number"
+      },
+      "input_tokens_details": {
+        "additionalProperties": false,
+        "properties": {
+          "image_tokens": {
+            "type": "number"
+          },
+          "text_tokens": {
+            "type": "number"
+          }
+        },
+        "type": "object"
+      },
+      "output_tokens": {
+        "type": "number"
+      },
+      "output_tokens_details": {
+        "additionalProperties": false,
+        "properties": {
+          "image_tokens": {
+            "type": "number"
+          },
+          "text_tokens": {
+            "type": "number"
+          }
+        },
+        "type": "object"
+      },
+      "total_tokens": {
+        "type": "number"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / required

Removed value: -[
-  "model",
-  "prompt",
-  "requested",
-  "applied",
-  "images",
-  "usage",
-  "cost_usd_estimated",
-  "session_id",
-  "turn"
-]

First observedv0.3.0Sep 21, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, and destructive hints. The description adds meaningful behavioral context beyond those: the session is stateful, each turn consumes the previous output, the first turn is asynchronous, and the session_id arrives with the completed job result. This is useful and not contradicted by any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler. The description front-loads the core stateful behavior, then explains the session lifecycle and async job mechanics. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema and the existence of an output schema, the description sufficiently covers what an agent needs to invoke this tool correctly: session lifecycle, sibling tool routing, and the background-job polling behavior. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and every parameter already has a detailed schema description. The tool description itself adds no parameter-level detail, but none is needed since the schema carries the full burden. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool begins a stateful multi-turn edit session and names the sibling tools it connects to (continue_edit_session, end_edit_session). This makes it immediately distinguishable from one-off image tools like edit_image and generate_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lays out the intended workflow: pass the returned session_id to continue_edit_session, and call end_edit_session when done. It does not explicitly contrast start_edit_session with one-off edit_image/generate_image, but the lifecycle guidance is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server