Skip to content

images

The image module provides functionality for creating variations of images, editing images based on textual prompts, and generating new images from prompts using specified models.

The module supports both synchronous and asynchronous operations, with capabilities for handling raw responses and streaming. Suitable for applications requiring dynamic image generation or modification through the OpenAI API, this module leverages models like DALL-E to interpret text prompts into visual content.

Classes:

Name Description
AsyncImages
AsyncImagesWithRawResponse
AsyncImagesWithStreamingResponse
Images
ImagesWithRawResponse
ImagesWithStreamingResponse

AsyncImages 

AsyncImages(client: AsyncOpenAI)

Methods:

Name Description
create_variation

Creates a variation of a given image.
edit

Creates an edited or extended image given an original image and a prompt.
generate

Creates an image given a prompt.
with_raw_response
with_streaming_response

create_variation async 

create_variation(
    *,
    image: FileTypes,
    model: (
        Union[str, Literal["dall-e-2"], None] | NotGiven
    ) = NOT_GIVEN,
    n: Optional[int] | NotGiven = NOT_GIVEN,
    response_format: (
        Optional[Literal["url", "b64_json"]] | NotGiven
    ) = NOT_GIVEN,
    size: (
        Optional[Literal["256x256", "512x512", "1024x1024"]]
        | NotGiven
    ) = NOT_GIVEN,
    user: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> ImagesResponse

Creates a variation of a given image.

Parameters:

Name Type Description Default
image FileTypes

The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.

 required
model Union[str, Literal['dall-e-2'], None] | NotGiven

The model to use for image generation. Only dall-e-2 is supported at this time.

 NOT_GIVEN
n Optional[int] | NotGiven

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

 NOT_GIVEN
response_format Optional[Literal['url', 'b64_json']] | NotGiven

The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated.

 NOT_GIVEN
size Optional[Literal['256x256', '512x512', '1024x1024']] | NotGiven

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.

 NOT_GIVEN
user str | NotGiven

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

edit async 

edit(
    *,
    image: FileTypes,
    prompt: str,
    mask: FileTypes | NotGiven = NOT_GIVEN,
    model: (
        Union[str, Literal["dall-e-2"], None] | NotGiven
    ) = NOT_GIVEN,
    n: Optional[int] | NotGiven = NOT_GIVEN,
    response_format: (
        Optional[Literal["url", "b64_json"]] | NotGiven
    ) = NOT_GIVEN,
    size: (
        Optional[Literal["256x256", "512x512", "1024x1024"]]
        | NotGiven
    ) = NOT_GIVEN,
    user: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> ImagesResponse

Creates an edited or extended image given an original image and a prompt.

Parameters:

Name Type Description Default
image FileTypes

The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.

 required
prompt str

A text description of the desired image(s). The maximum length is 1000 characters.

 required
mask FileTypes | NotGiven

An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where image should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as image.

 NOT_GIVEN
model Union[str, Literal['dall-e-2'], None] | NotGiven

The model to use for image generation. Only dall-e-2 is supported at this time.

 NOT_GIVEN
n Optional[int] | NotGiven

The number of images to generate. Must be between 1 and 10.

 NOT_GIVEN
response_format Optional[Literal['url', 'b64_json']] | NotGiven

The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated.

 NOT_GIVEN
size Optional[Literal['256x256', '512x512', '1024x1024']] | NotGiven

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.

 NOT_GIVEN
user str | NotGiven

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

generate async 

generate(
    *,
    prompt: str,
    model: (
        Union[str, Literal["dall-e-2", "dall-e-3"], None]
        | NotGiven
    ) = NOT_GIVEN,
    n: Optional[int] | NotGiven = NOT_GIVEN,
    quality: (
        Literal["standard", "hd"] | NotGiven
    ) = NOT_GIVEN,
    response_format: (
        Optional[Literal["url", "b64_json"]] | NotGiven
    ) = NOT_GIVEN,
    size: (
        Optional[
            Literal[
                "256x256",
                "512x512",
                "1024x1024",
                "1792x1024",
                "1024x1792",
            ]
        ]
        | NotGiven
    ) = NOT_GIVEN,
    style: (
        Optional[Literal["vivid", "natural"]] | NotGiven
    ) = NOT_GIVEN,
    user: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> ImagesResponse

Creates an image given a prompt.

Parameters:

Name Type Description Default
prompt str

A text description of the desired image(s). The maximum length is 1000 characters for dall-e-2 and 4000 characters for dall-e-3.

 required
model Union[str, Literal['dall-e-2', 'dall-e-3'], None] | NotGiven

The model to use for image generation.

 NOT_GIVEN
n Optional[int] | NotGiven

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

 NOT_GIVEN
quality Literal['standard', 'hd'] | NotGiven

The quality of the image that will be generated. hd creates images with finer details and greater consistency across the image. This param is only supported for dall-e-3.

 NOT_GIVEN
response_format Optional[Literal['url', 'b64_json']] | NotGiven

The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated.

 NOT_GIVEN
size Optional[Literal['256x256', '512x512', '1024x1024', '1792x1024', '1024x1792']] | NotGiven

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.

 NOT_GIVEN
style Optional[Literal['vivid', 'natural']] | NotGiven

The style of the generated images. Must be one of vivid or natural. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. This param is only supported for dall-e-3.

 NOT_GIVEN
user str | NotGiven

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

with_raw_response 

with_raw_response() -> AsyncImagesWithRawResponse

with_streaming_response 

with_streaming_response() -> (
    AsyncImagesWithStreamingResponse
)

AsyncImagesWithRawResponse 

AsyncImagesWithRawResponse(images: AsyncImages)

Attributes:

Name Type Description
create_variation
edit
generate

create_variation instance-attribute 

create_variation = async_to_raw_response_wrapper(
    create_variation
)

edit instance-attribute 

edit = async_to_raw_response_wrapper(edit)

generate instance-attribute 

generate = async_to_raw_response_wrapper(generate)

AsyncImagesWithStreamingResponse 

AsyncImagesWithStreamingResponse(images: AsyncImages)

Attributes:

Name Type Description
create_variation
edit
generate

create_variation instance-attribute 

create_variation = async_to_streamed_response_wrapper(
    create_variation
)

edit instance-attribute 

edit = async_to_streamed_response_wrapper(edit)

generate instance-attribute 

generate = async_to_streamed_response_wrapper(generate)

Images 

Images(client: OpenAI)

Methods:

Name Description
create_variation

Creates a variation of a given image.
edit

Creates an edited or extended image given an original image and a prompt.
generate

Creates an image given a prompt.
with_raw_response
with_streaming_response

create_variation 

create_variation(
    *,
    image: FileTypes,
    model: (
        Union[str, Literal["dall-e-2"], None] | NotGiven
    ) = NOT_GIVEN,
    n: Optional[int] | NotGiven = NOT_GIVEN,
    response_format: (
        Optional[Literal["url", "b64_json"]] | NotGiven
    ) = NOT_GIVEN,
    size: (
        Optional[Literal["256x256", "512x512", "1024x1024"]]
        | NotGiven
    ) = NOT_GIVEN,
    user: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> ImagesResponse

Creates a variation of a given image.

Parameters:

Name Type Description Default
image FileTypes

The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.

 required
model Union[str, Literal['dall-e-2'], None] | NotGiven

The model to use for image generation. Only dall-e-2 is supported at this time.

 NOT_GIVEN
n Optional[int] | NotGiven

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

 NOT_GIVEN
response_format Optional[Literal['url', 'b64_json']] | NotGiven

The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated.

 NOT_GIVEN
size Optional[Literal['256x256', '512x512', '1024x1024']] | NotGiven

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.

 NOT_GIVEN
user str | NotGiven

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

edit 

edit(
    *,
    image: FileTypes,
    prompt: str,
    mask: FileTypes | NotGiven = NOT_GIVEN,
    model: (
        Union[str, Literal["dall-e-2"], None] | NotGiven
    ) = NOT_GIVEN,
    n: Optional[int] | NotGiven = NOT_GIVEN,
    response_format: (
        Optional[Literal["url", "b64_json"]] | NotGiven
    ) = NOT_GIVEN,
    size: (
        Optional[Literal["256x256", "512x512", "1024x1024"]]
        | NotGiven
    ) = NOT_GIVEN,
    user: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> ImagesResponse

Creates an edited or extended image given an original image and a prompt.

Parameters:

Name Type Description Default
image FileTypes

The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.

 required
prompt str

A text description of the desired image(s). The maximum length is 1000 characters.

 required
mask FileTypes | NotGiven

An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where image should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as image.

 NOT_GIVEN
model Union[str, Literal['dall-e-2'], None] | NotGiven

The model to use for image generation. Only dall-e-2 is supported at this time.

 NOT_GIVEN
n Optional[int] | NotGiven

The number of images to generate. Must be between 1 and 10.

 NOT_GIVEN
response_format Optional[Literal['url', 'b64_json']] | NotGiven

The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated.

 NOT_GIVEN
size Optional[Literal['256x256', '512x512', '1024x1024']] | NotGiven

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.

 NOT_GIVEN
user str | NotGiven

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

generate 

generate(
    *,
    prompt: str,
    model: (
        Union[str, Literal["dall-e-2", "dall-e-3"], None]
        | NotGiven
    ) = NOT_GIVEN,
    n: Optional[int] | NotGiven = NOT_GIVEN,
    quality: (
        Literal["standard", "hd"] | NotGiven
    ) = NOT_GIVEN,
    response_format: (
        Optional[Literal["url", "b64_json"]] | NotGiven
    ) = NOT_GIVEN,
    size: (
        Optional[
            Literal[
                "256x256",
                "512x512",
                "1024x1024",
                "1792x1024",
                "1024x1792",
            ]
        ]
        | NotGiven
    ) = NOT_GIVEN,
    style: (
        Optional[Literal["vivid", "natural"]] | NotGiven
    ) = NOT_GIVEN,
    user: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | Timeout | None | NotGiven = NOT_GIVEN
) -> ImagesResponse

Creates an image given a prompt.

Parameters:

Name Type Description Default
prompt str

A text description of the desired image(s). The maximum length is 1000 characters for dall-e-2 and 4000 characters for dall-e-3.

 required
model Union[str, Literal['dall-e-2', 'dall-e-3'], None] | NotGiven

The model to use for image generation.

 NOT_GIVEN
n Optional[int] | NotGiven

The number of images to generate. Must be between 1 and 10. For dall-e-3, only n=1 is supported.

 NOT_GIVEN
quality Literal['standard', 'hd'] | NotGiven

The quality of the image that will be generated. hd creates images with finer details and greater consistency across the image. This param is only supported for dall-e-3.

 NOT_GIVEN
response_format Optional[Literal['url', 'b64_json']] | NotGiven

The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated.

 NOT_GIVEN
size Optional[Literal['256x256', '512x512', '1024x1024', '1792x1024', '1024x1792']] | NotGiven

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models.

 NOT_GIVEN
style Optional[Literal['vivid', 'natural']] | NotGiven

The style of the generated images. Must be one of vivid or natural. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. This param is only supported for dall-e-3.

 NOT_GIVEN
user str | NotGiven

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

 NOT_GIVEN
extra_headers Headers | None

Send extra headers

 None
extra_query Query | None

Add additional query parameters to the request

 None
extra_body Body | None

Add additional JSON properties to the request

 None
timeout float | Timeout | None | NotGiven

Override the client-level default timeout for this request, in seconds

 NOT_GIVEN

with_raw_response 

with_raw_response() -> ImagesWithRawResponse

with_streaming_response 

with_streaming_response() -> ImagesWithStreamingResponse

ImagesWithRawResponse 

ImagesWithRawResponse(images: Images)

Attributes:

Name Type Description
create_variation
edit
generate

create_variation instance-attribute 

create_variation = to_raw_response_wrapper(create_variation)

edit instance-attribute 

edit = to_raw_response_wrapper(edit)

generate instance-attribute 

generate = to_raw_response_wrapper(generate)

ImagesWithStreamingResponse 

ImagesWithStreamingResponse(images: Images)

Attributes:

Name Type Description
create_variation
edit
generate

create_variation instance-attribute 

create_variation = to_streamed_response_wrapper(
    create_variation
)

edit instance-attribute 

edit = to_streamed_response_wrapper(edit)

generate instance-attribute 

generate = to_streamed_response_wrapper(generate)