gpt-image-2-mcp

Start Iterative Edit Session

start_edit_session

Begin a stateful image editing session that returns a session ID for iterative refinement, using each turn's output as the next turn's 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.

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", "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.
`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; "auto" lets the model pick. gpt-image-2 does NOT support transparent backgrounds — use a different model for that.	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
`turn`	Yes
`model`	Yes
`notes`	No	Caveats about how the request was served.
`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).
`usage`	Yes
`images`	Yes
`prompt`	Yes
`applied`	Yes
`requested`	Yes
`session_id`	Yes
`cost_usd_estimated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

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 only say the tool is non-read-only, non-idempotent, and non-destructive. The description adds meaningful behavior beyond that: the session is stateful, it returns a session_id, each turn uses the previous turn's output as input, and the session must be explicitly ended. This gives the agent a usable mental model of an accumulating session without contradicting 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 tight sentences: the action, the continuation protocol, and the termination protocol. The most important fact (stateful multi-turn session) is front-loaded, and every sentence contributes distinct information with no filler or repetition of schema details.

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, the presence of an output schema, and the sibling set, the description covers everything an agent needs to correctly initiate a session: what the tool does, how to continue it, and how to end it. The output schema presumably documents the returned session_id, so the description need not repeat return details.

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 description coverage is 100%, so the structured schema already documents all 12 parameters with detailed meanings, defaults, and constraints. The description itself adds no parameter-level semantics beyond mentioning session_id and continuation flow. Per the baseline rule for high coverage, a 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 uses a specific verb-resource pair ('Begin a stateful multi-turn edit session') and immediately differentiates itself from siblings by explaining the returned session_id is passed to continue_edit_session for iterative refinement. It also plants the session lifecycle in the reader's mind by naming end_edit_session, so an agent can distinguish this from one-shot edit_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 clearly conveys when this tool is appropriate: when the agent needs a stateful, multi-turn refinement loop where each turn consumes the previous output. It also explains the follow-up flow (continue_edit_session) and termination flow (end_edit_session). It stops short of explicitly saying 'use edit_image for single-shot edits' or listing exclusions, so it earns a 4 rather than a 5.

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

Deploy Server