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

快速结论：该报错发生在 OpenAI Python SDK 静态类型层面：Azure OpenAI 已于 2026-04-21 正式 GA 的 gpt-image-2 模型未包含在 SDK 的 ImageModel Literal 类型中，导致 mypy/pyright 对合法模型名报类型错误。优先排查 openai 包版本，升级到 v2.35.0 或更高版本即可解决。

适用环境：OpenAI Python SDK（openai 包）；涉及 openai.types.ImageModel 类型、AzureOpenAI.images.generate / .edit 调用，以及 responses/tool.py 与 responses/tool_param.py 中的 ImageGeneration.model Literal。Issue 确认 Azure API 版本为 2024-10-21，类型检查工具为 mypy / pyright。

最快修复方案：升级 openai 包至 v2.35.0 或更高版本（维护者在 Issue 中确认 gpt-image-2 已加入 ImageModel，并同步更新了 Responses 工具类型和文档）。

注意事项：该修复来自官方维护者确认，但 Issue 未提供具体升级命令。若无法立即升级，可暂用类型忽略注解规避类型检查错误——这只是过渡方案，SDK 类型随后续版本已同步；如果升级后问题依旧，请确认实际安装版本号。

问题场景

用户使用 Azure OpenAI 的 gpt-image-2 图像生成模型（2026-04-21 在 Azure 上正式 GA）。运行时调用 client.images.generate(model="gpt-image-2", ...) 完全正常，因为 ImageModel 实际类型别名是 Union[str, ImageModel, None]，但在严格类型检查环境下出现问题：mypy / pyright 会拒绝 Literal['gpt-image-2']，报出虚假的类型错误；同时 IDE 自动补全和参数文档中也看不到 gpt-image-2 这个选项。

报错原文

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

# mypy: error: Argument "model" to "generate" ... has incompatible type
#   "Literal['gpt-image-2']"; expected "str | ImageModel | None"

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

原因分析

SDK 类型定义未能与 Azure 模型发布节奏保持同步。gpt-image-2 在 Azure 侧已正式 GA，但 openai-python SDK 的 ImageModel Literal 联合类型中仍只包含 gpt-image-1、gpt-image-1-mini、gpt-image-1.5 以及遗留的 dall-e-* 系列。相关类型文件（src/openai/types/image_model.py、responses/tool.py、responses/tool_param.py）以及 image_generate_params.py / image_edit_params.py 的文档字符串均未同步更新。

Issue 作者明确验证过：将 model="gpt-image-2" 作为普通字符串传入时，请求体序列化（quality="low"、output_format、background、moderation、n、倍数为 16 的自定义尺寸如 1088×1088）和响应解析均正常，usage 对象和 images.edit 的 multipart 发送也无问题。因此这纯粹是类型定义与文档同步滞后，而非协议层缺陷。相关类型文件由 Stainless 生成，修复应从 OpenAPI 规范的下一次同步中流入。

环境排查

openai Python SDK 版本：确认是否 ≤ v2.34.x（v2.35.0 起已加入 gpt-image-2）。
类型检查工具：mypy 或 pyright 是否开启严格模式。
Azure API 版本：Issue 验证所用为 2024-10-21（支持所用图像端点的最新 GA 版本）。
调用方式：确认 model 参数是否被窄化为 Literal 类型（仅在调用方将 model 收窄为 Literal 时才触发类型错误）。

解决步骤

检查当前已安装的 openai 包版本。若低于 v2.35.0，升级到 v2.35.0 或更高版本（Issue 中维护者确认该版本已包含 gpt-image-2，并同步了图片与 Responses 工具类型及文档）。
升级后重新运行类型检查，确认 get_args(ImageModel) 返回结果中已包含 gpt-image-2。
如果暂时无法升级或升级后仍被阻塞，可优先尝试类型注解绕过（Issue 评论中提出的临时方案）：
用 Literal["gpt-image-2"] | ImageModel 作为参数类型注解，配合类型忽略注释。可优先尝试，但注意这只是过渡手段，不应作为长期方案。

验证方法

升级后重新运行类型检查器（mypy 或 pyright），确认对 model="gpt-image-2" 的调用不再报错。也可以在 Python 中执行 from openai.types import ImageModel 后用 get_args(ImageModel) 查看返回的 Literal 成员是否已包含 gpt-image-2。同时确认 IDE 中 images.generate 的 model 参数自动补全已列出 gpt-image-2，且参数文档字符串中已包含该模型名。