openai / openai/openai-python

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

Open
#2,889 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
31.6k
Forks
5.7k
Avg merge
1d 6h
Merged PRs (30d)
96

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the existing ReasoningEffort alias pattern with the proposed openai/types/shared/image_detail.py location and its export from openai.types. Then update the detail fields in types/responses/response_input_image_content.py, types/responses/response_input_image_content_param.py, and types/chat/chat_completion_content_part_image.py. Done means ImageDetail can be imported from openai.types and replaces the repeated inline literals in those models.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.