gpt-image-2-mcp

Continue Edit Session

continue_edit_session

Apply another edit to an existing image session, using the previous output as the starting point. Use short, focused prompts to refine details while preserving the rest of the image.

Instructions

Apply another edit turn to an existing session. The previous turn's output image is used as the input. Use short, focused prompts like "make the sky more orange" or "add a small boat on the horizon"; include "keep everything else the same" to limit drift. Returns the new image and the updated session. Omitting size, quality, background, output_format, or model inherits what the session already uses (list_edit_sessions reports those settings). The turn hands off to a background job (poll get_image_job); while one is still running the session stays busy and further turns are refused until it lands.

Input Schema

TableJSON Schema

Name	Required	Description
`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. Omit to keep the size the session is already using.
`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.
`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. Omit to keep the quality the session is already using.
`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. Omit to keep the background the session is already using.
`session_id`	Yes	The session id returned by start_edit_session.
`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.

Changed22 schema fields changedv0.5.5Sep 23, 2026

removedInput schema / properties / background / default
```
Removed value: -"auto"
```

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. Omit to keep the background the session is already using."

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"
+]

removedInput schema / properties / quality / default
```
Removed value: -"auto"
```

changedInput schema / properties / quality / description

Previous value: -"Edit quality — same levels as generate."New value: +"Edit quality — same levels as generate. Omit to keep the quality the session is already using."

removedInput schema / properties / size / default
```
Removed value: -"auto"
```

changedInput schema / properties / size / description

Previous value: -"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."New value: +"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. Omit to keep the size the session is already using."

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.4/5.0

Behavior5/5

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

The description discloses asynchronous execution ('hands off to a background job (poll get_image_job)') and session-level locking ('while one is still running the session stays busy and further turns are refused until it lands'), neither of which is present in the annotations. It also explains parameter inheritance behavior, adding substantial value beyond the structured hints. No contradiction with annotations.

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

Conciseness4/5

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

Four sentences, each earning its place: purpose, chaining, prompt tips, inheritance, and async behavior. It is front-loaded with the core action and ends with the operational caveat. Slightly dense but not padded; a minor trim would push it to a 5.

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 output schema exists, the description correctly focuses on behavior and usage. It covers prerequisites (existing session), invocation conditions (not busy), the polling workflow, and inheritance semantics, and it references sibling tools (list_edit_sessions, get_image_job) for supporting context. Nothing an agent needs to invoke it correctly 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?

The input schema has 100% parameter coverage, including per-parameter 'omit to keep' rules, so the schema already carries the semantic load. The description reiterates the inheritance concept at a high level but does not add detail beyond what the schema states. This meets the baseline of 3 for fully documented schemas.

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 opens with a specific verb-resource pair ('Apply another edit turn' to 'an existing session') and immediately clarifies the chaining behavior ('previous turn's output image is used as the input'). This distinguishes it clearly from start_edit_session (new session) and generate_image (standalone generation), and the session context is reinforced by the reference to list_edit_sessions.

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?

It provides concrete usage guidance: short focused prompts, including 'keep everything else the same' to limit drift, omitting parameters to inherit session settings, and the busy condition that refuses further turns until the background job lands. It does not explicitly name edit_image as an alternative, but the session-flow context and references to start_edit_session and get_image_job make the intended use clear.

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

Deploy Server