Add `ImageDetail` as a named public type alias (like `ReasoningEffort`)

Author: dawid-dolCreated Feb 24, 2026Updated Sep 15, 2026

Confirm this is a feature request for the Python library and not the underlying OpenAI API.

  • This is a feature request for the Python library

Describe the feature or improvement you're requesting

The SDK exposes ReasoningEffort as a named TypeAlias in openai.types, making it easy to reference in user code:

python
from openai.types import ReasoningEffort

cast(ReasoningEffort, reasoning_effort.value if reasoning_effort else 'minimal')`

There's no equivalent for the image detail level. The detail field on image input types uses an inline literal across several generated files:

bash
types/responses/response_input_image_content.py — detail: Optional[Literal["low", "high", "auto"]]
types/responses/response_input_image_content_param.py — detail: Optional[Literal["low", "high", "auto"]]
types/chat/chat_completion_content_part_image.py — detail: Optional[Literal["auto", "low", "high"]]

Users who need to type or cast this value are forced to repeat the inline literal or define their own alias:

python
cast(Literal["low", "high", "auto"], image_quality.value if image_quality else 'high')

Proposed change

Add ImageDetail as a named type alias following the same pattern as ReasoningEffort:

python
# openai/types/shared/image_detail.py
from typing import Optional
from typing_extensions import Literal, TypeAlias

__all__ = ["ImageDetail"]

ImageDetail: TypeAlias = Optional[Literal["low", "high", "auto"]]

Export it from openai.types so users can import it directly:

python
from openai.types import ImageDetail

Before:

python
cast(Literal["low", "high", "auto"], image_quality.value if image_quality else 'high')

After:

python
cast(ImageDetail, image_quality.value if image_quality else 'high')

And use it as the field type across the relevant generated models instead of the inline literal.

Why this matters?

It would add consistency with the existing ReasoningEffort pattern and cleaner user code when casting or annotating image detail values.

Additional context

No response