Images

Create image

$ openai images generate

post /images/generations

Creates an image given a prompt. Learn more.

Parameters

--prompt: string

A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models, 1000 characters for dall-e-2 and 4000 characters for dall-e-3.
--background: optional "transparent" or "opaque" or "auto"

Allows to set transparency for the background of the generated image(s). This parameter is only supported for GPT image models that support transparent backgrounds. Must be one of transparent, opaque, or auto (default value). When auto is used, the model will automatically determine the best background for the image.

gpt-image-2 and gpt-image-2-2026-04-21 do not support transparent backgrounds. Requests with background set to transparent will return an error for these models; use opaque or auto instead.

If transparent, the output format needs to support transparency, so it should be set to either png (default value) or webp.
--model: optional string or ImageModel

The model to use for image generation. One of dall-e-2, dall-e-3, or a GPT image model (gpt-image-1, gpt-image-1-mini, gpt-image-1.5, gpt-image-2, or gpt-image-2-2026-04-21). Defaults to dall-e-2 unless a parameter specific to the GPT image models is used.
--moderation: optional "low" or "auto"

Control the content-moderation level for images generated by the GPT image models. Must be either low for less restrictive filtering or auto (default value).
--n: optional number

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

The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the webp or jpeg output formats, and defaults to 100.
--output-format: optional "png" or "jpeg" or "webp"

The format in which the generated images are returned. This parameter is only supported for the GPT image models. Must be one of png, jpeg, or webp.
--partial-images: optional number

The number of partial images to generate. This parameter is used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event.

Note that the final image may be sent before the full number of partial images are generated if the full image is generated more quickly.
--quality: optional "standard" or "hd" or "low" or 3 more

The quality of the image that will be generated.
- auto (default value) will automatically select the best quality for the given model.
- high, medium and low are supported for the GPT image models.
- hd and standard are supported for dall-e-3.
- standard is the only option for dall-e-2.
--response-format: optional "url" or "b64_json"

The format in which generated images with dall-e-2 and dall-e-3 are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for the GPT image models, which always return base64-encoded images.
--size: optional string or "auto" or "1024x1024" or "1536x1024" or 5 more

The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
--style: optional "vivid" or "natural"

The style of the generated images. This parameter is only supported for dall-e-3. 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.
--user: optional string

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

Returns

images_response: object { created, background, data, 4 more }

The response from the image generation endpoint.
- created: number
  
  The Unix timestamp (in seconds) of when the image was created.
- background: optional "transparent" or "opaque"
  
  The background parameter used for the image generation. Either transparent or opaque.
  - "transparent"
  - "opaque"
- data: optional array of Image
  
  The list of generated images.
  - b64_json: optional string
    
    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 string
    
    For dall-e-3 only, the revised prompt that was used to generate the image.
  - url: optional string
    
    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 "png" or "webp" or "jpeg"
  
  The output format of the image generation. Either png, webp, or jpeg.
  - "png"
  - "webp"
  - "jpeg"
- quality: optional "low" or "medium" or "high"
  
  The quality of the image generated. Either low, medium, or high.
  - "low"
  - "medium"
  - "high"
- size: optional "1024x1024" or "1024x1536" or "1536x1024"
  
  The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  For gpt-image-1 only, the token usage information for the image generation.
  - input_tokens: number
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: object { image_tokens, text_tokens }
    
    The input tokens detailed information for the image generation.
    - image_tokens: number
      
      The number of image tokens in the input prompt.
    - text_tokens: number
      
      The number of text tokens in the input prompt.
  - output_tokens: number
    
    The number of output tokens generated by the model.
  - total_tokens: number
    
    The total number of tokens (images and text) used for the image generation.
  - output_tokens_details: optional object { image_tokens, text_tokens }
    
    The output token details for the image generation.
    - image_tokens: number
      
      The number of image output tokens generated by the model.
    - text_tokens: number
      
      The number of text output tokens generated by the model.

Example

openai images generate \
  --api-key 'My API Key' \
  --prompt 'A cute baby sea otter'

Response

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    }
  }
}

Create image edit

$ openai images edit

post /images/edits

Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (gpt-image-1.5, gpt-image-1, gpt-image-1-mini, and chatgpt-image-latest) and dall-e-2.

Parameters

--image: string or array of string

The image(s) to edit. Must be a supported image file or an array of images.

For the GPT image models (gpt-image-1, gpt-image-1-mini, gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21, and chatgpt-image-latest), each image should be a png, webp, or jpg file less than 50MB. You can provide up to 16 images.

For dall-e-2, you can only provide one image, and it should be a square png file less than 4MB.
--prompt: string

A text description of the desired image(s). The maximum length is 1000 characters for dall-e-2, and 32000 characters for the GPT image models.
--background: optional "transparent" or "opaque" or "auto"

Allows to set transparency for the background of the generated image(s). This parameter is only supported for GPT image models that support transparent backgrounds. Must be one of transparent, opaque, or auto (default value). When auto is used, the model will automatically determine the best background for the image.

gpt-image-2 and gpt-image-2-2026-04-21 do not support transparent backgrounds. Requests with background set to transparent will return an error for these models; use opaque or auto instead.

If transparent, the output format needs to support transparency, so it should be set to either png (default value) or webp.
--input-fidelity: optional "high" or "low"

Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini. Supports high and low. Defaults to low.
--mask: optional string

An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where image should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as image.
--model: optional string or ImageModel

The model to use for image generation. One of dall-e-2 or a GPT image model (gpt-image-1, gpt-image-1-mini, gpt-image-1.5, gpt-image-2, gpt-image-2-2026-04-21, or chatgpt-image-latest). Defaults to gpt-image-1.5.
--n: optional number

The number of images to generate. Must be between 1 and 10.
--output-compression: optional number

The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the webp or jpeg output formats, and defaults to 100.
--output-format: optional "png" or "jpeg" or "webp"

The format in which the generated images are returned. This parameter is only supported for the GPT image models. Must be one of png, jpeg, or webp. The default value is png.
--partial-images: optional number

The number of partial images to generate. This parameter is used for streaming responses that return partial images. Value must be between 0 and 3. When set to 0, the response will be a single image sent in one streaming event.

Note that the final image may be sent before the full number of partial images are generated if the full image is generated more quickly.
--quality: optional "standard" or "low" or "medium" or 2 more

The quality of the image that will be generated for GPT image models. Defaults to auto.
--response-format: optional "url" or "b64_json"

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. This parameter is only supported for dall-e-2 (default is url for dall-e-2), as GPT image models always return base64-encoded images.
--size: optional string or "256x256" or "512x512" or "1024x1024" or 3 more

The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
--user: optional string

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

Returns

images_response: object { created, background, data, 4 more }

The response from the image generation endpoint.
- created: number
  
  The Unix timestamp (in seconds) of when the image was created.
- background: optional "transparent" or "opaque"
  
  The background parameter used for the image generation. Either transparent or opaque.
  - "transparent"
  - "opaque"
- data: optional array of Image
  
  The list of generated images.
  - b64_json: optional string
    
    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 string
    
    For dall-e-3 only, the revised prompt that was used to generate the image.
  - url: optional string
    
    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 "png" or "webp" or "jpeg"
  
  The output format of the image generation. Either png, webp, or jpeg.
  - "png"
  - "webp"
  - "jpeg"
- quality: optional "low" or "medium" or "high"
  
  The quality of the image generated. Either low, medium, or high.
  - "low"
  - "medium"
  - "high"
- size: optional "1024x1024" or "1024x1536" or "1536x1024"
  
  The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  For gpt-image-1 only, the token usage information for the image generation.
  - input_tokens: number
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: object { image_tokens, text_tokens }
    
    The input tokens detailed information for the image generation.
    - image_tokens: number
      
      The number of image tokens in the input prompt.
    - text_tokens: number
      
      The number of text tokens in the input prompt.
  - output_tokens: number
    
    The number of output tokens generated by the model.
  - total_tokens: number
    
    The total number of tokens (images and text) used for the image generation.
  - output_tokens_details: optional object { image_tokens, text_tokens }
    
    The output token details for the image generation.
    - image_tokens: number
      
      The number of image output tokens generated by the model.
    - text_tokens: number
      
      The number of text output tokens generated by the model.

Example

openai images edit \
  --api-key 'My API Key' \
  --image 'Example data' \
  --prompt 'A cute baby sea otter wearing a beret'

Response

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    }
  }
}

Create image variation

$ openai images create-variation

post /images/variations

Creates a variation of a given image. This endpoint only supports dall-e-2.

Parameters

--image: string

The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
--model: optional string or ImageModel

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

The number of images to generate. Must be between 1 and 10.
--response-format: optional "url" or "b64_json"

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.
--size: optional "256x256" or "512x512" or "1024x1024"

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
--user: optional string

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

Returns

images_response: object { created, background, data, 4 more }

The response from the image generation endpoint.
- created: number
  
  The Unix timestamp (in seconds) of when the image was created.
- background: optional "transparent" or "opaque"
  
  The background parameter used for the image generation. Either transparent or opaque.
  - "transparent"
  - "opaque"
- data: optional array of Image
  
  The list of generated images.
  - b64_json: optional string
    
    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 string
    
    For dall-e-3 only, the revised prompt that was used to generate the image.
  - url: optional string
    
    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 "png" or "webp" or "jpeg"
  
  The output format of the image generation. Either png, webp, or jpeg.
  - "png"
  - "webp"
  - "jpeg"
- quality: optional "low" or "medium" or "high"
  
  The quality of the image generated. Either low, medium, or high.
  - "low"
  - "medium"
  - "high"
- size: optional "1024x1024" or "1024x1536" or "1536x1024"
  
  The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  For gpt-image-1 only, the token usage information for the image generation.
  - input_tokens: number
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: object { image_tokens, text_tokens }
    
    The input tokens detailed information for the image generation.
    - image_tokens: number
      
      The number of image tokens in the input prompt.
    - text_tokens: number
      
      The number of text tokens in the input prompt.
  - output_tokens: number
    
    The number of output tokens generated by the model.
  - total_tokens: number
    
    The total number of tokens (images and text) used for the image generation.
  - output_tokens_details: optional object { image_tokens, text_tokens }
    
    The output token details for the image generation.
    - image_tokens: number
      
      The number of image output tokens generated by the model.
    - text_tokens: number
      
      The number of text output tokens generated by the model.

Example

openai images create-variation \
  --api-key 'My API Key' \
  --image 'Example data'

Response

{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "https://example.com"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    },
    "output_tokens": 0,
    "total_tokens": 0,
    "output_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 0
    }
  }
}

Domain Types

Image

image: object { b64_json, revised_prompt, url }

Represents the content or the URL of an image generated by the OpenAI API.
- b64_json: optional string
  
  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 string
  
  For dall-e-3 only, the revised prompt that was used to generate the image.
- url: optional string
  
  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.

Image Edit Completed Event

image_edit_completed_event: object { b64_json, background, created_at, 5 more }

Emitted when image editing has completed and the final image is available.
- b64_json: string
  
  Base64-encoded final edited image data, suitable for rendering as an image.
- background: "transparent" or "opaque" or "auto"
  
  The background setting for the edited image.
  - "transparent"
  - "opaque"
  - "auto"
- created_at: number
  
  The Unix timestamp when the event was created.
- output_format: "png" or "webp" or "jpeg"
  
  The output format for the edited image.
  - "png"
  - "webp"
  - "jpeg"
- quality: "low" or "medium" or "high" or "auto"
  
  The quality setting for the edited image.
  - "low"
  - "medium"
  - "high"
  - "auto"
- size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
  
  The size of the edited image.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
  - "auto"
- type: "image_edit.completed"
  
  The type of the event. Always image_edit.completed.
- usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }
  
  For the GPT image models only, the token usage information for the image generation.
  - input_tokens: number
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: object { image_tokens, text_tokens }
    
    The input tokens detailed information for the image generation.
    - image_tokens: number
      
      The number of image tokens in the input prompt.
    - text_tokens: number
      
      The number of text tokens in the input prompt.
  - output_tokens: number
    
    The number of image tokens in the output image.
  - total_tokens: number
    
    The total number of tokens (images and text) used for the image generation.

Image Edit Partial Image Event

image_edit_partial_image_event: object { b64_json, background, created_at, 5 more }

Emitted when a partial image is available during image editing streaming.
- b64_json: string
  
  Base64-encoded partial image data, suitable for rendering as an image.
- background: "transparent" or "opaque" or "auto"
  
  The background setting for the requested edited image.
  - "transparent"
  - "opaque"
  - "auto"
- created_at: number
  
  The Unix timestamp when the event was created.
- output_format: "png" or "webp" or "jpeg"
  
  The output format for the requested edited image.
  - "png"
  - "webp"
  - "jpeg"
- partial_image_index: number
  
  0-based index for the partial image (streaming).
- quality: "low" or "medium" or "high" or "auto"
  
  The quality setting for the requested edited image.
  - "low"
  - "medium"
  - "high"
  - "auto"
- size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
  
  The size of the requested edited image.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
  - "auto"
- type: "image_edit.partial_image"
  
  The type of the event. Always image_edit.partial_image.

Image Edit Stream Event

image_edit_stream_event: ImageEditPartialImageEvent or ImageEditCompletedEvent

Emitted when a partial image is available during image editing streaming.
- image_edit_partial_image_event: object { b64_json, background, created_at, 5 more }
  
  Emitted when a partial image is available during image editing streaming.
  - b64_json: string
    
    Base64-encoded partial image data, suitable for rendering as an image.
  - background: "transparent" or "opaque" or "auto"
    
    The background setting for the requested edited image.
    - "transparent"
    - "opaque"
    - "auto"
  - created_at: number
    
    The Unix timestamp when the event was created.
  - output_format: "png" or "webp" or "jpeg"
    
    The output format for the requested edited image.
    - "png"
    - "webp"
    - "jpeg"
  - partial_image_index: number
    
    0-based index for the partial image (streaming).
  - quality: "low" or "medium" or "high" or "auto"
    
    The quality setting for the requested edited image.
    - "low"
    - "medium"
    - "high"
    - "auto"
  - size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
    
    The size of the requested edited image.
    - "1024x1024"
    - "1024x1536"
    - "1536x1024"
    - "auto"
  - type: "image_edit.partial_image"
    
    The type of the event. Always image_edit.partial_image.
- image_edit_completed_event: object { b64_json, background, created_at, 5 more }
  
  Emitted when image editing has completed and the final image is available.
  - b64_json: string
    
    Base64-encoded final edited image data, suitable for rendering as an image.
  - background: "transparent" or "opaque" or "auto"
    
    The background setting for the edited image.
    - "transparent"
    - "opaque"
    - "auto"
  - created_at: number
    
    The Unix timestamp when the event was created.
  - output_format: "png" or "webp" or "jpeg"
    
    The output format for the edited image.
    - "png"
    - "webp"
    - "jpeg"
  - quality: "low" or "medium" or "high" or "auto"
    
    The quality setting for the edited image.
    - "low"
    - "medium"
    - "high"
    - "auto"
  - size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
    
    The size of the edited image.
    - "1024x1024"
    - "1024x1536"
    - "1536x1024"
    - "auto"
  - type: "image_edit.completed"
    
    The type of the event. Always image_edit.completed.
  - usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }
    
    For the GPT image models only, the token usage information for the image generation.
    - input_tokens: number
      
      The number of tokens (images and text) in the input prompt.
    - input_tokens_details: object { image_tokens, text_tokens }
      
      The input tokens detailed information for the image generation.
      - image_tokens: number
        
        The number of image tokens in the input prompt.
      - text_tokens: number
        
        The number of text tokens in the input prompt.
    - output_tokens: number
      
      The number of image tokens in the output image.
    - total_tokens: number
      
      The total number of tokens (images and text) used for the image generation.

Image Gen Completed Event

image_gen_completed_event: object { b64_json, background, created_at, 5 more }

Emitted when image generation has completed and the final image is available.
- b64_json: string
  
  Base64-encoded image data, suitable for rendering as an image.
- background: "transparent" or "opaque" or "auto"
  
  The background setting for the generated image.
  - "transparent"
  - "opaque"
  - "auto"
- created_at: number
  
  The Unix timestamp when the event was created.
- output_format: "png" or "webp" or "jpeg"
  
  The output format for the generated image.
  - "png"
  - "webp"
  - "jpeg"
- quality: "low" or "medium" or "high" or "auto"
  
  The quality setting for the generated image.
  - "low"
  - "medium"
  - "high"
  - "auto"
- size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
  
  The size of the generated image.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
  - "auto"
- type: "image_generation.completed"
  
  The type of the event. Always image_generation.completed.
- usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }
  
  For the GPT image models only, the token usage information for the image generation.
  - input_tokens: number
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: object { image_tokens, text_tokens }
    
    The input tokens detailed information for the image generation.
    - image_tokens: number
      
      The number of image tokens in the input prompt.
    - text_tokens: number
      
      The number of text tokens in the input prompt.
  - output_tokens: number
    
    The number of image tokens in the output image.
  - total_tokens: number
    
    The total number of tokens (images and text) used for the image generation.

Image Gen Partial Image Event

image_gen_partial_image_event: object { b64_json, background, created_at, 5 more }

Emitted when a partial image is available during image generation streaming.
- b64_json: string
  
  Base64-encoded partial image data, suitable for rendering as an image.
- background: "transparent" or "opaque" or "auto"
  
  The background setting for the requested image.
  - "transparent"
  - "opaque"
  - "auto"
- created_at: number
  
  The Unix timestamp when the event was created.
- output_format: "png" or "webp" or "jpeg"
  
  The output format for the requested image.
  - "png"
  - "webp"
  - "jpeg"
- partial_image_index: number
  
  0-based index for the partial image (streaming).
- quality: "low" or "medium" or "high" or "auto"
  
  The quality setting for the requested image.
  - "low"
  - "medium"
  - "high"
  - "auto"
- size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
  
  The size of the requested image.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
  - "auto"
- type: "image_generation.partial_image"
  
  The type of the event. Always image_generation.partial_image.

Image Gen Stream Event

image_gen_stream_event: ImageGenPartialImageEvent or ImageGenCompletedEvent

Emitted when a partial image is available during image generation streaming.
- image_gen_partial_image_event: object { b64_json, background, created_at, 5 more }
  
  Emitted when a partial image is available during image generation streaming.
  - b64_json: string
    
    Base64-encoded partial image data, suitable for rendering as an image.
  - background: "transparent" or "opaque" or "auto"
    
    The background setting for the requested image.
    - "transparent"
    - "opaque"
    - "auto"
  - created_at: number
    
    The Unix timestamp when the event was created.
  - output_format: "png" or "webp" or "jpeg"
    
    The output format for the requested image.
    - "png"
    - "webp"
    - "jpeg"
  - partial_image_index: number
    
    0-based index for the partial image (streaming).
  - quality: "low" or "medium" or "high" or "auto"
    
    The quality setting for the requested image.
    - "low"
    - "medium"
    - "high"
    - "auto"
  - size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
    
    The size of the requested image.
    - "1024x1024"
    - "1024x1536"
    - "1536x1024"
    - "auto"
  - type: "image_generation.partial_image"
    
    The type of the event. Always image_generation.partial_image.
- image_gen_completed_event: object { b64_json, background, created_at, 5 more }
  
  Emitted when image generation has completed and the final image is available.
  - b64_json: string
    
    Base64-encoded image data, suitable for rendering as an image.
  - background: "transparent" or "opaque" or "auto"
    
    The background setting for the generated image.
    - "transparent"
    - "opaque"
    - "auto"
  - created_at: number
    
    The Unix timestamp when the event was created.
  - output_format: "png" or "webp" or "jpeg"
    
    The output format for the generated image.
    - "png"
    - "webp"
    - "jpeg"
  - quality: "low" or "medium" or "high" or "auto"
    
    The quality setting for the generated image.
    - "low"
    - "medium"
    - "high"
    - "auto"
  - size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"
    
    The size of the generated image.
    - "1024x1024"
    - "1024x1536"
    - "1536x1024"
    - "auto"
  - type: "image_generation.completed"
    
    The type of the event. Always image_generation.completed.
  - usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }
    
    For the GPT image models only, the token usage information for the image generation.
    - input_tokens: number
      
      The number of tokens (images and text) in the input prompt.
    - input_tokens_details: object { image_tokens, text_tokens }
      
      The input tokens detailed information for the image generation.
      - image_tokens: number
        
        The number of image tokens in the input prompt.
      - text_tokens: number
        
        The number of text tokens in the input prompt.
    - output_tokens: number
      
      The number of image tokens in the output image.
    - total_tokens: number
      
      The total number of tokens (images and text) used for the image generation.

Image Model

image_model: "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 5 more
- "gpt-image-1"
- "gpt-image-1-mini"
- "gpt-image-2"
- "gpt-image-2-2026-04-21"
- "gpt-image-1.5"
- "chatgpt-image-latest"
- "dall-e-2"
- "dall-e-3"

Images Response

images_response: object { created, background, data, 4 more }

The response from the image generation endpoint.
- created: number
  
  The Unix timestamp (in seconds) of when the image was created.
- background: optional "transparent" or "opaque"
  
  The background parameter used for the image generation. Either transparent or opaque.
  - "transparent"
  - "opaque"
- data: optional array of Image
  
  The list of generated images.
  - b64_json: optional string
    
    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 string
    
    For dall-e-3 only, the revised prompt that was used to generate the image.
  - url: optional string
    
    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 "png" or "webp" or "jpeg"
  
  The output format of the image generation. Either png, webp, or jpeg.
  - "png"
  - "webp"
  - "jpeg"
- quality: optional "low" or "medium" or "high"
  
  The quality of the image generated. Either low, medium, or high.
  - "low"
  - "medium"
  - "high"
- size: optional "1024x1024" or "1024x1536" or "1536x1024"
  
  The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.
  - "1024x1024"
  - "1024x1536"
  - "1536x1024"
- usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }
  
  For gpt-image-1 only, the token usage information for the image generation.
  - input_tokens: number
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: object { image_tokens, text_tokens }
    
    The input tokens detailed information for the image generation.
    - image_tokens: number
      
      The number of image tokens in the input prompt.
    - text_tokens: number
      
      The number of text tokens in the input prompt.
  - output_tokens: number
    
    The number of output tokens generated by the model.
  - total_tokens: number
    
    The total number of tokens (images and text) used for the image generation.
  - output_tokens_details: optional object { image_tokens, text_tokens }
    
    The output token details for the image generation.
    - image_tokens: number
      
      The number of image output tokens generated by the model.
    - text_tokens: number
      
      The number of text output tokens generated by the model.

cli/resources/images/index.md +1419 −0 created

1# Images

3## Create image

5`$ openai images generate`

7**post** `/images/generations`

9Creates an image given a prompt. [Learn more](https://platform.openai.com/docs/guides/images).

11### Parameters

13- `--prompt: string`

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

17- `--background: optional "transparent" or "opaque" or "auto"`

19 Allows to set transparency for the background of the generated image(s).

20 This parameter is only supported for GPT image models that support

21 transparent backgrounds. Must be one of `transparent`, `opaque`, or

22 `auto` (default value). When `auto` is used, the model will

23 automatically determine the best background for the image.

25 `gpt-image-2` and `gpt-image-2-2026-04-21` do not support

26 transparent backgrounds. Requests with `background` set to

27 `transparent` will return an error for these models; use `opaque` or

28 `auto` instead.

30 If `transparent`, the output format needs to support transparency,

31 so it should be set to either `png` (default value) or `webp`.

33- `--model: optional string or ImageModel`

35 The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, or `gpt-image-2-2026-04-21`). Defaults to `dall-e-2` unless a parameter specific to the GPT image models is used.

37- `--moderation: optional "low" or "auto"`

39 Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value).

41- `--n: optional number`

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

45- `--output-compression: optional number`

47 The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and defaults to 100.

49- `--output-format: optional "png" or "jpeg" or "webp"`

51 The format in which the generated images are returned. This parameter is only supported for the GPT image models. Must be one of `png`, `jpeg`, or `webp`.

53- `--partial-images: optional number`

55 The number of partial images to generate. This parameter is used for

56 streaming responses that return partial images. Value must be between 0 and 3.

57 When set to 0, the response will be a single image sent in one streaming event.

59 Note that the final image may be sent before the full number of partial images

60 are generated if the full image is generated more quickly.

62- `--quality: optional "standard" or "hd" or "low" or 3 more`

64 The quality of the image that will be generated.

66 - `auto` (default value) will automatically select the best quality for the given model.

67 - `high`, `medium` and `low` are supported for the GPT image models.

68 - `hd` and `standard` are supported for `dall-e-3`.

69 - `standard` is the only option for `dall-e-2`.

71- `--response-format: optional "url" or "b64_json"`

73 The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for the GPT image models, which always return base64-encoded images.

75- `--size: optional string or "auto" or "1024x1024" or "1536x1024" or 5 more`

77 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

79- `--style: optional "vivid" or "natural"`

81 The style of the generated images. This parameter is only supported for `dall-e-3`. 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.

83- `--user: optional string`

85 A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).

87### Returns

89- `images_response: object { created, background, data, 4 more }`

91 The response from the image generation endpoint.

93 - `created: number`

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

97 - `background: optional "transparent" or "opaque"`

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

100

101 - `"transparent"`

102

103 - `"opaque"`

104

105 - `data: optional array of Image`

106

107 The list of generated images.

108

109 - `b64_json: optional string`

110

111 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`.

112

113 - `revised_prompt: optional string`

114

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

116

117 - `url: optional string`

118

119 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.

120

121 - `output_format: optional "png" or "webp" or "jpeg"`

122

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

124

125 - `"png"`

126

127 - `"webp"`

128

129 - `"jpeg"`

130

131 - `quality: optional "low" or "medium" or "high"`

132

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

134

135 - `"low"`

136

137 - `"medium"`

138

139 - `"high"`

140

141 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`

142

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

144

145 - `"1024x1024"`

146

147 - `"1024x1536"`

148

149 - `"1536x1024"`

150

151 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

152

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

154

155 - `input_tokens: number`

156

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

158

159 - `input_tokens_details: object { image_tokens, text_tokens }`

160

161 The input tokens detailed information for the image generation.

162

163 - `image_tokens: number`

164

165 The number of image tokens in the input prompt.

166

167 - `text_tokens: number`

168

169 The number of text tokens in the input prompt.

170

171 - `output_tokens: number`

172

173 The number of output tokens generated by the model.

174

175 - `total_tokens: number`

176

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

178

179 - `output_tokens_details: optional object { image_tokens, text_tokens }`

180

181 The output token details for the image generation.

182

183 - `image_tokens: number`

184

185 The number of image output tokens generated by the model.

186

187 - `text_tokens: number`

188

189 The number of text output tokens generated by the model.

190

191### Example

192

193```cli

194openai images generate \

195 --api-key 'My API Key' \

196 --prompt 'A cute baby sea otter'

197```

198

199#### Response

200

201```json

202{

203 "created": 0,

204 "background": "transparent",

205 "data": [

206 {

207 "b64_json": "b64_json",

208 "revised_prompt": "revised_prompt",

209 "url": "https://example.com"

210 }

211 ],

212 "output_format": "png",

213 "quality": "low",

214 "size": "1024x1024",

215 "usage": {

216 "input_tokens": 0,

217 "input_tokens_details": {

218 "image_tokens": 0,

219 "text_tokens": 0

220 },

221 "output_tokens": 0,

222 "total_tokens": 0,

223 "output_tokens_details": {

224 "image_tokens": 0,

225 "text_tokens": 0

226 }

227 }

228}

229```

230

231## Create image edit

232

233`$ openai images edit`

234

235**post** `/images/edits`

236

237Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`, and `chatgpt-image-latest`) and `dall-e-2`.

238

239### Parameters

240

241- `--image: string or array of string`

242

243 The image(s) to edit. Must be a supported image file or an array of images.

244

245 For the GPT image models (`gpt-image-1`, `gpt-image-1-mini`,

246 `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, and

247 `chatgpt-image-latest`), each image should be a `png`, `webp`, or

248 `jpg` file less than 50MB. You can provide up to 16 images.

249

250 For `dall-e-2`, you can only provide one image, and it should be a

251 square `png` file less than 4MB.

252

253- `--prompt: string`

254

255 A text description of the desired image(s). The maximum length is 1000 characters for `dall-e-2`, and 32000 characters for the GPT image models.

256

257- `--background: optional "transparent" or "opaque" or "auto"`

258

259 Allows to set transparency for the background of the generated image(s).

260 This parameter is only supported for GPT image models that support

261 transparent backgrounds. Must be one of `transparent`, `opaque`, or

262 `auto` (default value). When `auto` is used, the model will

263 automatically determine the best background for the image.

264

265 `gpt-image-2` and `gpt-image-2-2026-04-21` do not support

266 transparent backgrounds. Requests with `background` set to

267 `transparent` will return an error for these models; use `opaque` or

268 `auto` instead.

269

270 If `transparent`, the output format needs to support transparency,

271 so it should be set to either `png` (default value) or `webp`.

272

273- `--input-fidelity: optional "high" or "low"`

274

275 Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.

276

277- `--mask: optional string`

278

279 An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`.

280

281- `--model: optional string or ImageModel`

282

283 The model to use for image generation. One of `dall-e-2` or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, or `chatgpt-image-latest`). Defaults to `gpt-image-1.5`.

284

285- `--n: optional number`

286

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

288

289- `--output-compression: optional number`

290

291 The compression level (0-100%) for the generated images. This parameter

292 is only supported for the GPT image models with the `webp` or `jpeg` output

293 formats, and defaults to 100.

294

295- `--output-format: optional "png" or "jpeg" or "webp"`

296

297 The format in which the generated images are returned. This parameter is

298 only supported for the GPT image models. Must be one of `png`, `jpeg`, or `webp`.

299 The default value is `png`.

300

301- `--partial-images: optional number`

302

303 The number of partial images to generate. This parameter is used for

304 streaming responses that return partial images. Value must be between 0 and 3.

305 When set to 0, the response will be a single image sent in one streaming event.

306

307 Note that the final image may be sent before the full number of partial images

308 are generated if the full image is generated more quickly.

309

310- `--quality: optional "standard" or "low" or "medium" or 2 more`

311

312 The quality of the image that will be generated for GPT image models. Defaults to `auto`.

313

314- `--response-format: optional "url" or "b64_json"`

315

316 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. This parameter is only supported for `dall-e-2` (default is `url` for `dall-e-2`), as GPT image models always return base64-encoded images.

317

318- `--size: optional string or "256x256" or "512x512" or "1024x1024" or 3 more`

319

320 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

321

322- `--user: optional string`

323

324 A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).

325

326### Returns

327

328- `images_response: object { created, background, data, 4 more }`

329

330 The response from the image generation endpoint.

331

332 - `created: number`

333

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

335

336 - `background: optional "transparent" or "opaque"`

337

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

339

340 - `"transparent"`

341

342 - `"opaque"`

343

344 - `data: optional array of Image`

345

346 The list of generated images.

347

348 - `b64_json: optional string`

349

350 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`.

351

352 - `revised_prompt: optional string`

353

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

355

356 - `url: optional string`

357

358 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.

359

360 - `output_format: optional "png" or "webp" or "jpeg"`

361

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

363

364 - `"png"`

365

366 - `"webp"`

367

368 - `"jpeg"`

369

370 - `quality: optional "low" or "medium" or "high"`

371

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

373

374 - `"low"`

375

376 - `"medium"`

377

378 - `"high"`

379

380 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`

381

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

383

384 - `"1024x1024"`

385

386 - `"1024x1536"`

387

388 - `"1536x1024"`

389

390 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

391

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

393

394 - `input_tokens: number`

395

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

397

398 - `input_tokens_details: object { image_tokens, text_tokens }`

399

400 The input tokens detailed information for the image generation.

401

402 - `image_tokens: number`

403

404 The number of image tokens in the input prompt.

405

406 - `text_tokens: number`

407

408 The number of text tokens in the input prompt.

409

410 - `output_tokens: number`

411

412 The number of output tokens generated by the model.

413

414 - `total_tokens: number`

415

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

417

418 - `output_tokens_details: optional object { image_tokens, text_tokens }`

419

420 The output token details for the image generation.

421

422 - `image_tokens: number`

423

424 The number of image output tokens generated by the model.

425

426 - `text_tokens: number`

427

428 The number of text output tokens generated by the model.

429

430### Example

431

432```cli

433openai images edit \

434 --api-key 'My API Key' \

435 --image 'Example data' \

436 --prompt 'A cute baby sea otter wearing a beret'

437```

438

439#### Response

440

441```json

442{

443 "created": 0,

444 "background": "transparent",

445 "data": [

446 {

447 "b64_json": "b64_json",

448 "revised_prompt": "revised_prompt",

449 "url": "https://example.com"

450 }

451 ],

452 "output_format": "png",

453 "quality": "low",

454 "size": "1024x1024",

455 "usage": {

456 "input_tokens": 0,

457 "input_tokens_details": {

458 "image_tokens": 0,

459 "text_tokens": 0

460 },

461 "output_tokens": 0,

462 "total_tokens": 0,

463 "output_tokens_details": {

464 "image_tokens": 0,

465 "text_tokens": 0

466 }

467 }

468}

469```

470

471## Create image variation

472

473`$ openai images create-variation`

474

475**post** `/images/variations`

476

477Creates a variation of a given image. This endpoint only supports `dall-e-2`.

478

479### Parameters

480

481- `--image: string`

482

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

484

485- `--model: optional string or ImageModel`

486

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

488

489- `--n: optional number`

490

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

492

493- `--response-format: optional "url" or "b64_json"`

494

495 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.

496

497- `--size: optional "256x256" or "512x512" or "1024x1024"`

498

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

500

501- `--user: optional string`

502

503 A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).

504

505### Returns

506

507- `images_response: object { created, background, data, 4 more }`

508

509 The response from the image generation endpoint.

510

511 - `created: number`

512

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

514

515 - `background: optional "transparent" or "opaque"`

516

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

518

519 - `"transparent"`

520

521 - `"opaque"`

522

523 - `data: optional array of Image`

524

525 The list of generated images.

526

527 - `b64_json: optional string`

528

529 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`.

530

531 - `revised_prompt: optional string`

532

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

534

535 - `url: optional string`

536

537 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.

538

539 - `output_format: optional "png" or "webp" or "jpeg"`

540

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

542

543 - `"png"`

544

545 - `"webp"`

546

547 - `"jpeg"`

548

549 - `quality: optional "low" or "medium" or "high"`

550

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

552

553 - `"low"`

554

555 - `"medium"`

556

557 - `"high"`

558

559 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`

560

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

562

563 - `"1024x1024"`

564

565 - `"1024x1536"`

566

567 - `"1536x1024"`

568

569 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

570

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

572

573 - `input_tokens: number`

574

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

576

577 - `input_tokens_details: object { image_tokens, text_tokens }`

578

579 The input tokens detailed information for the image generation.

580

581 - `image_tokens: number`

582

583 The number of image tokens in the input prompt.

584

585 - `text_tokens: number`

586

587 The number of text tokens in the input prompt.

588

589 - `output_tokens: number`

590

591 The number of output tokens generated by the model.

592

593 - `total_tokens: number`

594

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

596

597 - `output_tokens_details: optional object { image_tokens, text_tokens }`

598

599 The output token details for the image generation.

600

601 - `image_tokens: number`

602

603 The number of image output tokens generated by the model.

604

605 - `text_tokens: number`

606

607 The number of text output tokens generated by the model.

608

609### Example

610

611```cli

612openai images create-variation \

613 --api-key 'My API Key' \

614 --image 'Example data'

615```

616

617#### Response

618

619```json

620{

621 "created": 0,

622 "background": "transparent",

623 "data": [

624 {

625 "b64_json": "b64_json",

626 "revised_prompt": "revised_prompt",

627 "url": "https://example.com"

628 }

629 ],

630 "output_format": "png",

631 "quality": "low",

632 "size": "1024x1024",

633 "usage": {

634 "input_tokens": 0,

635 "input_tokens_details": {

636 "image_tokens": 0,

637 "text_tokens": 0

638 },

639 "output_tokens": 0,

640 "total_tokens": 0,

641 "output_tokens_details": {

642 "image_tokens": 0,

643 "text_tokens": 0

644 }

645 }

646}

647```

648

649## Domain Types

650

651### Image

652

653- `image: object { b64_json, revised_prompt, url }`

654

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

656

657 - `b64_json: optional string`

658

659 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`.

660

661 - `revised_prompt: optional string`

662

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

664

665 - `url: optional string`

666

667 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.

668

669### Image Edit Completed Event

670

671- `image_edit_completed_event: object { b64_json, background, created_at, 5 more }`

672

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

674

675 - `b64_json: string`

676

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

678

679 - `background: "transparent" or "opaque" or "auto"`

680

681 The background setting for the edited image.

682

683 - `"transparent"`

684

685 - `"opaque"`

686

687 - `"auto"`

688

689 - `created_at: number`

690

691 The Unix timestamp when the event was created.

692

693 - `output_format: "png" or "webp" or "jpeg"`

694

695 The output format for the edited image.

696

697 - `"png"`

698

699 - `"webp"`

700

701 - `"jpeg"`

702

703 - `quality: "low" or "medium" or "high" or "auto"`

704

705 The quality setting for the edited image.

706

707 - `"low"`

708

709 - `"medium"`

710

711 - `"high"`

712

713 - `"auto"`

714

715 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

716

717 The size of the edited image.

718

719 - `"1024x1024"`

720

721 - `"1024x1536"`

722

723 - `"1536x1024"`

724

725 - `"auto"`

726

727 - `type: "image_edit.completed"`

728

729 The type of the event. Always `image_edit.completed`.

730

731 - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }`

732

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

734

735 - `input_tokens: number`

736

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

738

739 - `input_tokens_details: object { image_tokens, text_tokens }`

740

741 The input tokens detailed information for the image generation.

742

743 - `image_tokens: number`

744

745 The number of image tokens in the input prompt.

746

747 - `text_tokens: number`

748

749 The number of text tokens in the input prompt.

750

751 - `output_tokens: number`

752

753 The number of image tokens in the output image.

754

755 - `total_tokens: number`

756

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

758

759### Image Edit Partial Image Event

760

761- `image_edit_partial_image_event: object { b64_json, background, created_at, 5 more }`

762

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

764

765 - `b64_json: string`

766

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

768

769 - `background: "transparent" or "opaque" or "auto"`

770

771 The background setting for the requested edited image.

772

773 - `"transparent"`

774

775 - `"opaque"`

776

777 - `"auto"`

778

779 - `created_at: number`

780

781 The Unix timestamp when the event was created.

782

783 - `output_format: "png" or "webp" or "jpeg"`

784

785 The output format for the requested edited image.

786

787 - `"png"`

788

789 - `"webp"`

790

791 - `"jpeg"`

792

793 - `partial_image_index: number`

794

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

796

797 - `quality: "low" or "medium" or "high" or "auto"`

798

799 The quality setting for the requested edited image.

800

801 - `"low"`

802

803 - `"medium"`

804

805 - `"high"`

806

807 - `"auto"`

808

809 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

810

811 The size of the requested edited image.

812

813 - `"1024x1024"`

814

815 - `"1024x1536"`

816

817 - `"1536x1024"`

818

819 - `"auto"`

820

821 - `type: "image_edit.partial_image"`

822

823 The type of the event. Always `image_edit.partial_image`.

824

825### Image Edit Stream Event

826

827- `image_edit_stream_event: ImageEditPartialImageEvent or ImageEditCompletedEvent`

828

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

830

831 - `image_edit_partial_image_event: object { b64_json, background, created_at, 5 more }`

832

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

834

835 - `b64_json: string`

836

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

838

839 - `background: "transparent" or "opaque" or "auto"`

840

841 The background setting for the requested edited image.

842

843 - `"transparent"`

844

845 - `"opaque"`

846

847 - `"auto"`

848

849 - `created_at: number`

850

851 The Unix timestamp when the event was created.

852

853 - `output_format: "png" or "webp" or "jpeg"`

854

855 The output format for the requested edited image.

856

857 - `"png"`

858

859 - `"webp"`

860

861 - `"jpeg"`

862

863 - `partial_image_index: number`

864

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

866

867 - `quality: "low" or "medium" or "high" or "auto"`

868

869 The quality setting for the requested edited image.

870

871 - `"low"`

872

873 - `"medium"`

874

875 - `"high"`

876

877 - `"auto"`

878

879 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

880

881 The size of the requested edited image.

882

883 - `"1024x1024"`

884

885 - `"1024x1536"`

886

887 - `"1536x1024"`

888

889 - `"auto"`

890

891 - `type: "image_edit.partial_image"`

892

893 The type of the event. Always `image_edit.partial_image`.

894

895 - `image_edit_completed_event: object { b64_json, background, created_at, 5 more }`

896

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

898

899 - `b64_json: string`

900

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

902

903 - `background: "transparent" or "opaque" or "auto"`

904

905 The background setting for the edited image.

906

907 - `"transparent"`

908

909 - `"opaque"`

910

911 - `"auto"`

912

913 - `created_at: number`

914

915 The Unix timestamp when the event was created.

916

917 - `output_format: "png" or "webp" or "jpeg"`

918

919 The output format for the edited image.

920

921 - `"png"`

922

923 - `"webp"`

924

925 - `"jpeg"`

926

927 - `quality: "low" or "medium" or "high" or "auto"`

928

929 The quality setting for the edited image.

930

931 - `"low"`

932

933 - `"medium"`

934

935 - `"high"`

936

937 - `"auto"`

938

939 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

940

941 The size of the edited image.

942

943 - `"1024x1024"`

944

945 - `"1024x1536"`

946

947 - `"1536x1024"`

948

949 - `"auto"`

950

951 - `type: "image_edit.completed"`

952

953 The type of the event. Always `image_edit.completed`.

954

955 - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }`

956

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

958

959 - `input_tokens: number`

960

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

962

963 - `input_tokens_details: object { image_tokens, text_tokens }`

964

965 The input tokens detailed information for the image generation.

966

967 - `image_tokens: number`

968

969 The number of image tokens in the input prompt.

970

971 - `text_tokens: number`

972

973 The number of text tokens in the input prompt.

974

975 - `output_tokens: number`

976

977 The number of image tokens in the output image.

978

979 - `total_tokens: number`

980

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

982

983### Image Gen Completed Event

984

985- `image_gen_completed_event: object { b64_json, background, created_at, 5 more }`

986

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

988

989 - `b64_json: string`

990

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

992

993 - `background: "transparent" or "opaque" or "auto"`

994

995 The background setting for the generated image.

996

997 - `"transparent"`

998

999 - `"opaque"`

1000

1001 - `"auto"`

1002

1003 - `created_at: number`

1004

1005 The Unix timestamp when the event was created.

1006

1007 - `output_format: "png" or "webp" or "jpeg"`

1008

1009 The output format for the generated image.

1010

1011 - `"png"`

1012

1013 - `"webp"`

1014

1015 - `"jpeg"`

1016

1017 - `quality: "low" or "medium" or "high" or "auto"`

1018

1019 The quality setting for the generated image.

1020

1021 - `"low"`

1022

1023 - `"medium"`

1024

1025 - `"high"`

1026

1027 - `"auto"`

1028

1029 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1030

1031 The size of the generated image.

1032

1033 - `"1024x1024"`

1034

1035 - `"1024x1536"`

1036

1037 - `"1536x1024"`

1038

1039 - `"auto"`

1040

1041 - `type: "image_generation.completed"`

1042

1043 The type of the event. Always `image_generation.completed`.

1044

1045 - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }`

1046

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

1048

1049 - `input_tokens: number`

1050

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

1052

1053 - `input_tokens_details: object { image_tokens, text_tokens }`

1054

1055 The input tokens detailed information for the image generation.

1056

1057 - `image_tokens: number`

1058

1059 The number of image tokens in the input prompt.

1060

1061 - `text_tokens: number`

1062

1063 The number of text tokens in the input prompt.

1064

1065 - `output_tokens: number`

1066

1067 The number of image tokens in the output image.

1068

1069 - `total_tokens: number`

1070

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

1072

1073### Image Gen Partial Image Event

1074

1075- `image_gen_partial_image_event: object { b64_json, background, created_at, 5 more }`

1076

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

1078

1079 - `b64_json: string`

1080

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

1082

1083 - `background: "transparent" or "opaque" or "auto"`

1084

1085 The background setting for the requested image.

1086

1087 - `"transparent"`

1088

1089 - `"opaque"`

1090

1091 - `"auto"`

1092

1093 - `created_at: number`

1094

1095 The Unix timestamp when the event was created.

1096

1097 - `output_format: "png" or "webp" or "jpeg"`

1098

1099 The output format for the requested image.

1100

1101 - `"png"`

1102

1103 - `"webp"`

1104

1105 - `"jpeg"`

1106

1107 - `partial_image_index: number`

1108

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

1110

1111 - `quality: "low" or "medium" or "high" or "auto"`

1112

1113 The quality setting for the requested image.

1114

1115 - `"low"`

1116

1117 - `"medium"`

1118

1119 - `"high"`

1120

1121 - `"auto"`

1122

1123 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1124

1125 The size of the requested image.

1126

1127 - `"1024x1024"`

1128

1129 - `"1024x1536"`

1130

1131 - `"1536x1024"`

1132

1133 - `"auto"`

1134

1135 - `type: "image_generation.partial_image"`

1136

1137 The type of the event. Always `image_generation.partial_image`.

1138

1139### Image Gen Stream Event

1140

1141- `image_gen_stream_event: ImageGenPartialImageEvent or ImageGenCompletedEvent`

1142

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

1144

1145 - `image_gen_partial_image_event: object { b64_json, background, created_at, 5 more }`

1146

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

1148

1149 - `b64_json: string`

1150

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

1152

1153 - `background: "transparent" or "opaque" or "auto"`

1154

1155 The background setting for the requested image.

1156

1157 - `"transparent"`

1158

1159 - `"opaque"`

1160

1161 - `"auto"`

1162

1163 - `created_at: number`

1164

1165 The Unix timestamp when the event was created.

1166

1167 - `output_format: "png" or "webp" or "jpeg"`

1168

1169 The output format for the requested image.

1170

1171 - `"png"`

1172

1173 - `"webp"`

1174

1175 - `"jpeg"`

1176

1177 - `partial_image_index: number`

1178

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

1180

1181 - `quality: "low" or "medium" or "high" or "auto"`

1182

1183 The quality setting for the requested image.

1184

1185 - `"low"`

1186

1187 - `"medium"`

1188

1189 - `"high"`

1190

1191 - `"auto"`

1192

1193 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1194

1195 The size of the requested image.

1196

1197 - `"1024x1024"`

1198

1199 - `"1024x1536"`

1200

1201 - `"1536x1024"`

1202

1203 - `"auto"`

1204

1205 - `type: "image_generation.partial_image"`

1206

1207 The type of the event. Always `image_generation.partial_image`.

1208

1209 - `image_gen_completed_event: object { b64_json, background, created_at, 5 more }`

1210

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

1212

1213 - `b64_json: string`

1214

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

1216

1217 - `background: "transparent" or "opaque" or "auto"`

1218

1219 The background setting for the generated image.

1220

1221 - `"transparent"`

1222

1223 - `"opaque"`

1224

1225 - `"auto"`

1226

1227 - `created_at: number`

1228

1229 The Unix timestamp when the event was created.

1230

1231 - `output_format: "png" or "webp" or "jpeg"`

1232

1233 The output format for the generated image.

1234

1235 - `"png"`

1236

1237 - `"webp"`

1238

1239 - `"jpeg"`

1240

1241 - `quality: "low" or "medium" or "high" or "auto"`

1242

1243 The quality setting for the generated image.

1244

1245 - `"low"`

1246

1247 - `"medium"`

1248

1249 - `"high"`

1250

1251 - `"auto"`

1252

1253 - `size: "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1254

1255 The size of the generated image.

1256

1257 - `"1024x1024"`

1258

1259 - `"1024x1536"`

1260

1261 - `"1536x1024"`

1262

1263 - `"auto"`

1264

1265 - `type: "image_generation.completed"`

1266

1267 The type of the event. Always `image_generation.completed`.

1268

1269 - `usage: object { input_tokens, input_tokens_details, output_tokens, total_tokens }`

1270

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

1272

1273 - `input_tokens: number`

1274

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

1276

1277 - `input_tokens_details: object { image_tokens, text_tokens }`

1278

1279 The input tokens detailed information for the image generation.

1280

1281 - `image_tokens: number`

1282

1283 The number of image tokens in the input prompt.

1284

1285 - `text_tokens: number`

1286

1287 The number of text tokens in the input prompt.

1288

1289 - `output_tokens: number`

1290

1291 The number of image tokens in the output image.

1292

1293 - `total_tokens: number`

1294

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

1296

1297### Image Model

1298

1299- `image_model: "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-2" or 5 more`

1300

1301 - `"gpt-image-1"`

1302

1303 - `"gpt-image-1-mini"`

1304

1305 - `"gpt-image-2"`

1306

1307 - `"gpt-image-2-2026-04-21"`

1308

1309 - `"gpt-image-1.5"`

1310

1311 - `"chatgpt-image-latest"`

1312

1313 - `"dall-e-2"`

1314

1315 - `"dall-e-3"`

1316

1317### Images Response

1318

1319- `images_response: object { created, background, data, 4 more }`

1320

1321 The response from the image generation endpoint.

1322

1323 - `created: number`

1324

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

1326

1327 - `background: optional "transparent" or "opaque"`

1328

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

1330

1331 - `"transparent"`

1332

1333 - `"opaque"`

1334

1335 - `data: optional array of Image`

1336

1337 The list of generated images.

1338

1339 - `b64_json: optional string`

1340

1341 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`.

1342

1343 - `revised_prompt: optional string`

1344

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

1346

1347 - `url: optional string`

1348

1349 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.

1350

1351 - `output_format: optional "png" or "webp" or "jpeg"`

1352

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

1354

1355 - `"png"`

1356

1357 - `"webp"`

1358

1359 - `"jpeg"`

1360

1361 - `quality: optional "low" or "medium" or "high"`

1362

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

1364

1365 - `"low"`

1366

1367 - `"medium"`

1368

1369 - `"high"`

1370

1371 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`

1372

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

1374

1375 - `"1024x1024"`

1376

1377 - `"1024x1536"`

1378

1379 - `"1536x1024"`

1380

1381 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

1382

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

1384

1385 - `input_tokens: number`

1386

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

1388

1389 - `input_tokens_details: object { image_tokens, text_tokens }`

1390

1391 The input tokens detailed information for the image generation.

1392

1393 - `image_tokens: number`

1394

1395 The number of image tokens in the input prompt.

1396

1397 - `text_tokens: number`

1398

1399 The number of text tokens in the input prompt.

1400

1401 - `output_tokens: number`

1402

1403 The number of output tokens generated by the model.

1404

1405 - `total_tokens: number`

1406

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

1408

1409 - `output_tokens_details: optional object { image_tokens, text_tokens }`

1410

1411 The output token details for the image generation.

1412

1413 - `image_tokens: number`

1414

1415 The number of image output tokens generated by the model.

1416

1417 - `text_tokens: number`

1418

1419 The number of text output tokens generated by the model.

cli/resources/images/index.md 2026-05-05 23:00 UTC to 2026-05-07 21:57 UTC

Images

Create image

Parameters

Returns

Example

Response

Create image edit

Parameters

Returns

Example

Response

Create image variation

Parameters

Returns

Example

Response

Domain Types

Image

Image Edit Completed Event

Image Edit Partial Image Event

Image Edit Stream Event

Image Gen Completed Event

Image Gen Partial Image Event

Image Gen Stream Event

Image Model

Images Response