Skip to content
Primary navigation

Suggested
API Dashboard
API Reference

Images

Given a prompt and/or an input image, the model will generate a new image.

Create image
images.generate(ImageGenerateParams**kwargs) -> ImagesResponse
POST/images/generations
Create image edit
images.edit(ImageEditParams**kwargs) -> ImagesResponse
POST/images/edits
Create image variation
images.create_variation(ImageCreateVariationParams**kwargs) -> ImagesResponse
POST/images/variations
ModelsExpand Collapse
class Image: …

Represents the content or the URL of an image generated by the OpenAI API.

b64_json: Optional[str]

The base64-encoded JSON of the generated image. Returned by default for the GPT image models, and only present if response_format is set to b64_json for dall-e-2 and dall-e-3.

revised_prompt: Optional[str]

For dall-e-3 only, the revised prompt that was used to generate the image.

url: Optional[str]

When using dall-e-2 or dall-e-3, the URL of the generated image if response_format is set to url (default value). Unsupported for the GPT image models.

class ImageEditCompletedEvent: …

Emitted when image editing has completed and the final image is available.

b64_json: str

Base64-encoded final edited image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the edited image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the edited image.

One of the following:
"png"
"webp"
"jpeg"
quality: Literal["low", "medium", "high", "auto"]

The quality setting for the edited image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the edited image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_edit.completed"]

The type of the event. Always image_edit.completed.

usage: Usage

For the GPT image models only, the token usage information for the image generation.

input_tokens: int

The number of tokens (images and text) in the input prompt.

input_tokens_details: UsageInputTokensDetails

The input tokens detailed information for the image generation.

image_tokens: int

The number of image tokens in the input prompt.

text_tokens: int

The number of text tokens in the input prompt.

output_tokens: int

The number of image tokens in the output image.

total_tokens: int

The total number of tokens (images and text) used for the image generation.

class ImageEditPartialImageEvent: …

Emitted when a partial image is available during image editing streaming.

b64_json: str

Base64-encoded partial image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the requested edited image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the requested edited image.

One of the following:
"png"
"webp"
"jpeg"
partial_image_index: int

0-based index for the partial image (streaming).

quality: Literal["low", "medium", "high", "auto"]

The quality setting for the requested edited image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the requested edited image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_edit.partial_image"]

The type of the event. Always image_edit.partial_image.

ImageEditStreamEvent

Emitted when a partial image is available during image editing streaming.

One of the following:
class ImageEditPartialImageEvent: …

Emitted when a partial image is available during image editing streaming.

b64_json: str

Base64-encoded partial image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the requested edited image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the requested edited image.

One of the following:
"png"
"webp"
"jpeg"
partial_image_index: int

0-based index for the partial image (streaming).

quality: Literal["low", "medium", "high", "auto"]

The quality setting for the requested edited image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the requested edited image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_edit.partial_image"]

The type of the event. Always image_edit.partial_image.

class ImageEditCompletedEvent: …

Emitted when image editing has completed and the final image is available.

b64_json: str

Base64-encoded final edited image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the edited image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the edited image.

One of the following:
"png"
"webp"
"jpeg"
quality: Literal["low", "medium", "high", "auto"]

The quality setting for the edited image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the edited image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_edit.completed"]

The type of the event. Always image_edit.completed.

usage: Usage

For the GPT image models only, the token usage information for the image generation.

input_tokens: int

The number of tokens (images and text) in the input prompt.

input_tokens_details: UsageInputTokensDetails

The input tokens detailed information for the image generation.

image_tokens: int

The number of image tokens in the input prompt.

text_tokens: int

The number of text tokens in the input prompt.

output_tokens: int

The number of image tokens in the output image.

total_tokens: int

The total number of tokens (images and text) used for the image generation.

class ImageGenCompletedEvent: …

Emitted when image generation has completed and the final image is available.

b64_json: str

Base64-encoded image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the generated image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the generated image.

One of the following:
"png"
"webp"
"jpeg"
quality: Literal["low", "medium", "high", "auto"]

The quality setting for the generated image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the generated image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_generation.completed"]

The type of the event. Always image_generation.completed.

usage: Usage

For the GPT image models only, the token usage information for the image generation.

input_tokens: int

The number of tokens (images and text) in the input prompt.

input_tokens_details: UsageInputTokensDetails

The input tokens detailed information for the image generation.

image_tokens: int

The number of image tokens in the input prompt.

text_tokens: int

The number of text tokens in the input prompt.

output_tokens: int

The number of image tokens in the output image.

total_tokens: int

The total number of tokens (images and text) used for the image generation.

class ImageGenPartialImageEvent: …

Emitted when a partial image is available during image generation streaming.

b64_json: str

Base64-encoded partial image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the requested image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the requested image.

One of the following:
"png"
"webp"
"jpeg"
partial_image_index: int

0-based index for the partial image (streaming).

quality: Literal["low", "medium", "high", "auto"]

The quality setting for the requested image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the requested image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_generation.partial_image"]

The type of the event. Always image_generation.partial_image.

ImageGenStreamEvent

Emitted when a partial image is available during image generation streaming.

One of the following:
class ImageGenPartialImageEvent: …

Emitted when a partial image is available during image generation streaming.

b64_json: str

Base64-encoded partial image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the requested image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the requested image.

One of the following:
"png"
"webp"
"jpeg"
partial_image_index: int

0-based index for the partial image (streaming).

quality: Literal["low", "medium", "high", "auto"]

The quality setting for the requested image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the requested image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_generation.partial_image"]

The type of the event. Always image_generation.partial_image.

class ImageGenCompletedEvent: …

Emitted when image generation has completed and the final image is available.

b64_json: str

Base64-encoded image data, suitable for rendering as an image.

background: Literal["transparent", "opaque", "auto"]

The background setting for the generated image.

One of the following:
"transparent"
"opaque"
"auto"
created_at: int

The Unix timestamp when the event was created.

output_format: Literal["png", "webp", "jpeg"]

The output format for the generated image.

One of the following:
"png"
"webp"
"jpeg"
quality: Literal["low", "medium", "high", "auto"]

The quality setting for the generated image.

One of the following:
"low"
"medium"
"high"
"auto"
size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"]

The size of the generated image.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
"auto"
type: Literal["image_generation.completed"]

The type of the event. Always image_generation.completed.

usage: Usage

For the GPT image models only, the token usage information for the image generation.

input_tokens: int

The number of tokens (images and text) in the input prompt.

input_tokens_details: UsageInputTokensDetails

The input tokens detailed information for the image generation.

image_tokens: int

The number of image tokens in the input prompt.

text_tokens: int

The number of text tokens in the input prompt.

output_tokens: int

The number of image tokens in the output image.

total_tokens: int

The total number of tokens (images and text) used for the image generation.

Literal["gpt-image-1.5", "dall-e-2", "dall-e-3", 2 more]
One of the following:
"gpt-image-1.5"
"dall-e-2"
"dall-e-3"
"gpt-image-1"
"gpt-image-1-mini"
class ImagesResponse: …

The response from the image generation endpoint.

created: int

The Unix timestamp (in seconds) of when the image was created.

background: Optional[Literal["transparent", "opaque"]]

The background parameter used for the image generation. Either transparent or opaque.

One of the following:
"transparent"
"opaque"
data: Optional[List[Image]]

The list of generated images.

b64_json: Optional[str]

The base64-encoded JSON of the generated image. Returned by default for the GPT image models, and only present if response_format is set to b64_json for dall-e-2 and dall-e-3.

revised_prompt: Optional[str]

For dall-e-3 only, the revised prompt that was used to generate the image.

url: Optional[str]

When using dall-e-2 or dall-e-3, the URL of the generated image if response_format is set to url (default value). Unsupported for the GPT image models.

output_format: Optional[Literal["png", "webp", "jpeg"]]

The output format of the image generation. Either png, webp, or jpeg.

One of the following:
"png"
"webp"
"jpeg"
quality: Optional[Literal["low", "medium", "high"]]

The quality of the image generated. Either low, medium, or high.

One of the following:
"low"
"medium"
"high"
size: Optional[Literal["1024x1024", "1024x1536", "1536x1024"]]

The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.

One of the following:
"1024x1024"
"1024x1536"
"1536x1024"
usage: Optional[Usage]

For gpt-image-1 only, the token usage information for the image generation.

input_tokens: int

The number of tokens (images and text) in the input prompt.

input_tokens_details: UsageInputTokensDetails

The input tokens detailed information for the image generation.

image_tokens: int

The number of image tokens in the input prompt.

text_tokens: int

The number of text tokens in the input prompt.

output_tokens: int

The number of output tokens generated by the model.

total_tokens: int

The total number of tokens (images and text) used for the image generation.

output_tokens_details: Optional[UsageOutputTokensDetails]

The output token details for the image generation.

image_tokens: int

The number of image output tokens generated by the model.

text_tokens: int

The number of text output tokens generated by the model.