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

[dawid-dol]

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:

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:

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:

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:

# 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:

from openai.types import ImageDetail

Before:

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

After:

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

[xXMrNidaXx]

+1 on this. The inconsistency between ReasoningEffort being exported as a named alias and ImageDetail requiring inline literals is a small paper cut that adds up when building typed abstractions.

Same pattern applies to other commonly-cast literals:

# Currently you need:
from typing import Literal, cast

cast(Literal["auto", "low", "high"], detail)           # ImageDetail
cast(Literal["png", "jpeg", "webp"], image_format)     # ImageFormat
cast(Literal["system", "user", "assistant"], role)    # MessageRole

# Would be cleaner as:
from openai.types import ImageDetail, ImageFormat, MessageRole

cast(ImageDetail, detail)
cast(ImageFormat, image_format)
cast(MessageRole, role)

Since this SDK is Stainless-generated, the fix would likely be in the codegen configuration to mark certain literal unions for named export. The pattern for ReasoningEffort shows it's already supported — just needs to be extended to more field types.

Would help with IDE autocomplete and docs generation too.