types: ImageModel Literal missing 'gpt-image-2' (GA'd 2026-04-21 on Azure)

[ottodeng]

Describe the bug

gpt-image-2 — Azure OpenAI's newest image generation model, publicly previewed on 2026-04-21 (docs) — is missing from the SDK's ImageModel literal and from several parameter/docstring references. Passing model="gpt-image-2" works at runtime (because the type alias is Union[str, ImageModel, None]), but:

1. mypy / pyright users get a spurious type-error on a valid, GA'd model name.
2. The parameter docs in image_generate_params.py, image_edit_params.py, responses/tool.py, and responses/tool_param.py still list only gpt-image-1 / gpt-image-1-mini / gpt-image-1.5, which gives the impression that gpt-image-2 isn't supported.

Everything at the request-body and response-parsing layer (quality=low, output_format, background, moderation, custom sizes, usage.{input,output,total}_tokens) already works — I've verified end-to-end via respx-mocked calls against AzureOpenAI.images.generate / .edit, so the fix really is just the Literal + docstring bump that usually follows every new model release.

To Reproduce

from typing import get_args
from openai.types import ImageModel

print(get_args(ImageModel))
# ('gpt-image-1.5', 'dall-e-2', 'dall-e-3', 'gpt-image-1', 'gpt-image-1-mini')
# -> 'gpt-image-2' is missing

And under a strict type-checker:

from openai import AzureOpenAI

client = AzureOpenAI(
    azure_endpoint="<YOUR_ENDPOINT>",
    api_key="<YOUR_KEY>",
    api_version="2024-10-21",
)

# mypy: error: Argument "model" to "generate" ... has incompatible type
#   "Literal['gpt-image-2']"; expected "str | ImageModel | None"
# (only surfaces if the caller narrows model to a Literal, but it also
#  means IDE autocomplete / docs don't suggest gpt-image-2.)
client.images.generate(
    model="gpt-image-2",
    prompt="a cute corgi puppy sitting on grass",
    size="1024x1024",
    quality="low",
    n=1,
)

Expected behavior

gpt-image-2 is a first-class value in openai.types.ImageModel and in the three responses tool-param Literals:

• src/openai/types/image_model.py
• src/openai/types/responses/tool.py (ImageGeneration.model)
• src/openai/types/responses/tool_param.py (ImageGeneration.model)

And the docstrings in image_generate_params.py / image_edit_params.py mention gpt-image-2 alongside the existing GPT-Image variants.

Actual behavior

ImageModel / ImageGeneration.model Literals contain only gpt-image-1, gpt-image-1-mini, gpt-image-1.5, plus the legacy dall-e-*. Docstrings say e.g.:

One of `dall-e-2`, `dall-e-3`, or a GPT image model (`gpt-image-1`,
`gpt-image-1-mini`, `gpt-image-1.5`).

Verification that the rest of the surface works

I confirmed with respx that — once you pass model="gpt-image-2" as a plain str — the SDK:

• serializes quality="low", output_format, background, moderation, n, and arbitrary multiples-of-16 sizes (e.g. 1088x1088) correctly into the request body;
• round-trips the response, including the usage object (input_tokens, output_tokens, output_tokens_details, etc.);
• sends multipart/form-data correctly for images.edit.

So this really is just a Literal/docstring sync, not a wire-level issue. A minimal example using AzureOpenAI + gpt-image-2 is attached in a companion PR to examples/azure_image.py.

References

• Azure docs: https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/dall-e
• Azure API versioning: https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#api-versions (2024-10-21 is the latest GA version that supports the image endpoints used here)

Happy to do a PR for types/image_model.py and the responses/tool*.py Literals if it would be useful, but I realize those files are generated by Stainless so the change should probably flow in from the OpenAPI spec on the next sync. Filing this so it's on the radar.

Additional context

I've also put together a small examples/azure_image.py showing end-to-end generate + edit against an Azure GPT-Image deployment (with quality="low" to keep costs in check), since examples/azure.py only covers chat completions today. Opening that as a separate PR.

[jingchang0623-crypto]

The phantom model in the type system — gpt-image-2 exists in production but not in the SDK's ImageModel Literal.

This is the SDK equivalent of Schrödinger's cat: the model is both alive (you can call it) and dead (the type checker says it doesn't exist).

Azure's GA announcement for gpt-image-2 on 2026-04-21 means this is now a first-class model, but the SDK types haven't caught up. This causes:

1. Type checker errors: mypy/pyright reject valid model names
2. IDE autocomplete gaps: Developers can't discover the model through hints
3. Runtime vs type mismatch: Code that works fails validation in strict mode

The fix is trivial — add "gpt-image-2" to the Literal union. But the deeper question: how do we keep SDK types in sync with rapidly evolving model catalogs?

One pattern we've found useful: maintain a models.latest module that's updated more frequently than the main SDK release, allowing opt-in for bleeding edge model names without breaking the core type system.

We wrote about similar "ghost entities" in AI systems — things that exist in one context but not another, causing cascading confusion: https://miaoquai.com/stories/ai-hallucination-ghost-library.html

For anyone blocked on this now, the workaround is:

model: Literal["gpt-image-2"] | ImageModel = "gpt-image-2"  # type: ignore
response = client.images.generate(model=model, ...)

Not elegant, but it keeps the type checker happy while the SDK catches up.

[nightcityblade]

Hi, I'd like to work on this. I'll submit a PR shortly.