# Image generation tool (`type: "image_generation"`, Responses API)

Status: DOCUMENTED · LIVE_VERIFIED for the validation-error path only (2026-09-18, gpt-5.4-nano, invalid size → HTTP 400); actual generation UNVERIFIED (skipped for cost; RUN_IMAGE_TESTS=true in the examples) Sources: https://developers.openai.com/api/docs/guides/tools-image-generation · https://developers.openai.com/api/docs/guides/image-generation · openapi-master.yaml ImageGenTool, ImageGenToolCall, ImageGenActionEnum, ResponseImageGenCall*Event Last verified: 2026-09-18

# Parameters

Parameter	Type / enum	Default	Notes
`type`	`image_generation`
`model`	`gpt-image-1` \| `gpt-image-1-mini` \| `gpt-image-1.5` \| `gpt-image-2` \| `gpt-image-2-2026-04-21` \| `gpt-image-2.5-sunburst[-2026-09-08]` \| `gpt-image-2.5-flare[-2026-09-08]` (free string allowed)	`gpt-image-1`	sunburst = precise editing, flare = fast generation
`size`	`1024x1024` \| `1024x1536` \| `1536x1024` \| `auto` (free string for gpt-image-2/2.5 arbitrary resolutions)	`auto`	live: width/height must be divisible by 16
`quality`	`low` \| `medium` \| `high` \| `xhigh` \| `max` \| `auto`	`auto`	`xhigh`/`max` only gpt-image-2.5-*
`background`	`transparent` \| `opaque` \| `auto`	`auto`
`output_format`	`png` \| `webp` \| `jpeg`	`png`
`output_compression`	0–100	100
`moderation`	`auto` \| `low`	`auto`
`input_fidelity`	`high` \| `low` \| null		gpt-image-1 / 1.5+ (face/style matching for edits)
`input_image_mask`	`{image_url (base64), file_id}`		inpainting
`partial_images`	0–3	0	streaming partial images
`action`	`generate` \| `edit` \| `auto`		edit an image already in the conversation

# Output

image_generation_call {id:"ig_…", type, status: in_progress|generating|completed|failed, result: <base64>|null, revised_prompt, size, quality, background, output_format, action}. The mainline model rewrites the prompt (revised_prompt). Streaming: response.image_generation_call.in_progress → generating → partial_image (partial_image_b64, partial_image_index) → completed.

# Compatible mainline models (guide list)

gpt-5.5, gpt-5.4-mini, gpt-5.4-nano, gpt-5.2, gpt-5, gpt-5-nano, o3, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini (model pages add gpt-5.1, 5.2-pro, 5.4, 5.4-pro, 5.5-pro, 5.6-*, gpt-6-astra, o3-mini, o3-pro, chat-latest…). Tool tool_choice: {"type":"image_generation"}.

# Billing

Image-model token pricing (see pricing fragment / guide calculator) + mainline model tokens. Not measured live.

# Live evidence

Probe	Status	Result
`tools:[{type:image_generation, size:"1x1"}]`	400	`{"type":"image_generation_user_error","code":"invalid_value","param":"tools","message":"Invalid size '1x1'. Width and height must both be divisible by 16."}` — a tool-specific error `type` distinct from `invalid_request_error`

Examples: examples/openai/tools/image-generation/ (error path; generation gated). Test: test_image_generation_invalid_size_error.