Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Openai Images API
license:
name: MIT
url: https://github.com/openai/openai-openapi/blob/master/LICENSE
termsOfService: https://openai.com/policies/terms-of-use
version: '1.0'
description: 'Operations tagged Images across 3 of this provider''s published API definitions: images-openapi-original.yml, openai-images-openapi.yml, openai-openapi-master.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.openai.com/v1
tags:
- name: Images
description: Given a prompt and/or an input image, the model will generate a new image.
paths:
/images/generations:
post:
operationId: createImage
tags:
- Images
summary: OpenAI Creates an image given a prompt.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateImageRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesResponse'
x-oaiMeta:
name: Create image
group: images
returns: Returns a list of [image](/docs/api-reference/images/object) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/images/generations \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"dall-e-3\",\n \"prompt\": \"A cute baby sea otter\",\n \"n\": 1,\n \"size\": \"1024x1024\"\n }'\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nclient.images.generate(\n model=\"dall-e-3\",\n prompt=\"A cute baby sea otter\",\n n=1,\n size=\"1024x1024\"\n)\n"
node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.generate({ model: \"dall-e-3\", prompt: \"A cute baby sea otter\" });\n\n console.log(image.data);\n}\nmain();"
response: "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n"
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
/images/edits:
post:
operationId: createImageEdit
tags:
- Images
summary: OpenAI Creates an edited or extended image given an original image and a prompt.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateImageEditRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesResponse'
x-oaiMeta:
name: Create image edit
group: images
returns: Returns a list of [image](/docs/api-reference/images/object) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/images/edits \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F image=\"@otter.png\" \\\n -F mask=\"@mask.png\" \\\n -F prompt=\"A cute baby sea otter wearing a beret\" \\\n -F n=2 \\\n -F size=\"1024x1024\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nclient.images.edit(\n image=open(\"otter.png\", \"rb\"),\n mask=open(\"mask.png\", \"rb\"),\n prompt=\"A cute baby sea otter wearing a beret\",\n n=2,\n size=\"1024x1024\"\n)\n"
node.js: "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.edit({\n image: fs.createReadStream(\"otter.png\"),\n mask: fs.createReadStream(\"mask.png\"),\n prompt: \"A cute baby sea otter wearing a beret\",\n });\n\n console.log(image.data);\n}\nmain();"
response: "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n"
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
/images/variations:
post:
operationId: createImageVariation
tags:
- Images
summary: OpenAI Creates a variation of a given image.
requestBody:
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateImageVariationRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ImagesResponse'
x-oaiMeta:
name: Create image variation
group: images
returns: Returns a list of [image](/docs/api-reference/images/object) objects.
examples:
request:
curl: "curl https://api.openai.com/v1/images/variations \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F image=\"@otter.png\" \\\n -F n=2 \\\n -F size=\"1024x1024\"\n"
python: "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.images.create_variation(\n image=open(\"image_edit_original.png\", \"rb\"),\n n=2,\n size=\"1024x1024\"\n)\n"
node.js: "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.createVariation({\n image: fs.createReadStream(\"otter.png\"),\n });\n\n console.log(image.data);\n}\nmain();"
response: "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n"
security:
- ApiKeyAuth: []
servers:
- url: https://api.openai.com/v1
components:
schemas:
ImagesResponse:
properties:
created:
type: integer
data:
type: array
items:
$ref: '#/components/schemas/Image'
required:
- created
- data
CreateImageVariationRequest:
type: object
required:
- image
properties:
image:
type: string
format: binary
description: The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
example: example_value
model:
type: string
default: dall-e-2
description: The model to use for image variation. Only DALL-E 2 is supported.
example: example_value
n:
type: integer
minimum: 1
maximum: 10
default: 1
description: The number of images to generate.
example: 10
response_format:
type: string
enum:
- url
- b64_json
default: url
description: The format in which the generated images are returned.
example: url
size:
type: string
enum:
- 256x256
- 512x512
- 1024x1024
default: 1024x1024
description: The size of the generated images.
example: 256x256
user:
type: string
description: A unique identifier representing your end-user.
example: example_value
ImagesResponse_2:
type: object
required:
- created
- data
properties:
created:
type: integer
description: The Unix timestamp (in seconds) when the images were created.
example: 10
data:
type: array
description: The list of generated images.
items:
$ref: '#/components/schemas/Image'
example: []
CreateImageEditRequest:
type: object
required:
- image
- prompt
properties:
image:
type: string
format: binary
description: The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, the image must have transparency which will be used as the mask.
example: example_value
prompt:
type: string
maxLength: 32000
description: A text description of the desired image(s). The maximum length is 1000 characters for DALL-E 2 and 32000 characters for gpt-image-1.
example: example_value
mask:
type: string
format: binary
description: An additional image whose fully transparent areas indicate where the image should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as image.
example: example_value
model:
type: string
default: dall-e-2
description: The model to use for image editing.
examples:
- dall-e-2
- gpt-image-1
n:
type: integer
minimum: 1
maximum: 10
default: 1
description: The number of images to generate.
example: 10
size:
type: string
enum:
- 256x256
- 512x512
- 1024x1024
- auto
default: 1024x1024
description: The size of the generated images.
example: 256x256
response_format:
type: string
enum:
- url
- b64_json
default: url
description: The format in which the generated images are returned.
example: url
user:
type: string
description: A unique identifier representing your end-user.
example: example_value
Image:
type: object
properties:
url:
type: string
format: uri
description: The URL of the generated image, if response_format is url. The URL is valid for 60 minutes.
example: https://www.example.com
b64_json:
type: string
description: The base64-encoded JSON of the generated image, if response_format is b64_json.
example: example_value
revised_prompt:
type: string
description: The prompt that was used to generate the image, if there was any revision to the prompt. Only present for DALL-E 3 and gpt-image-1.
example: example_value
CreateImageRequest:
type: object
required:
- prompt
properties:
prompt:
type: string
maxLength: 32000
description: A text description of the desired image(s). The maximum length is 1000 characters for DALL-E 2 and 32000 characters for gpt-image-1.
example: example_value
model:
type: string
default: dall-e-2
description: The model to use for image generation. Defaults to dall-e-2.
examples:
- dall-e-2
- dall-e-3
- gpt-image-1
n:
type: integer
minimum: 1
maximum: 10
default: 1
description: The number of images to generate. Must be between 1 and 10. For DALL-E 3, only n=1 is supported.
example: 10
quality:
type: string
enum:
- standard
- hd
- low
- medium
- high
- auto
default: auto
description: The quality of the image. hd creates images with finer details and greater consistency. For gpt-image-1 use low, medium, high, or auto.
example: standard
response_format:
type: string
enum:
- url
- b64_json
default: url
description: The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes.
example: url
size:
type: string
enum:
- 256x256
- 512x512
- 1024x1024
- 1792x1024
- 1024x1792
- auto
default: 1024x1024
description: The size of the generated images. Must be one of the supported sizes for the model being used.
example: 256x256
style:
type: string
enum:
- vivid
- natural
default: vivid
description: The style of the generated images. Vivid generates hyper-real and dramatic images. Natural produces more natural, less hyper-real images. Only supported for DALL-E 3.
example: vivid
user:
type: string
description: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
example: example_value
CreateImageVariationRequest_2:
type: object
properties:
image:
description: The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
type: string
format: binary
model:
anyOf:
- type: string
- type: string
enum:
- dall-e-2
x-stainless-const: true
x-oaiTypeLabel: string
default: dall-e-2
example: dall-e-2
nullable: true
description: The model to use for image generation. Only `dall-e-2` is supported at this time.
n:
type: integer
minimum: 1
maximum: 10
default: 1
example: 1
nullable: true
description: The number of images to generate. Must be between 1 and 10.
response_format:
type: string
enum:
- url
- b64_json
default: url
example: url
nullable: true
description: 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:
type: string
enum:
- 256x256
- 512x512
- 1024x1024
default: 1024x1024
example: 1024x1024
nullable: true
description: The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.
user:
type: string
example: user-1234
description: 'A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).
'
required:
- image
ImagesResponse_3:
type: object
title: Image generation response
description: The response from the image generation endpoint.
properties:
created:
type: integer
format: unixtime
description: The Unix timestamp (in seconds) of when the image was created.
data:
type: array
description: The list of generated images.
items:
$ref: '#/components/schemas/Image_2'
background:
type: string
description: The background parameter used for the image generation. Either `transparent` or `opaque`.
enum:
- transparent
- opaque
output_format:
type: string
description: The output format of the image generation. Either `png`, `webp`, or `jpeg`.
enum:
- png
- webp
- jpeg
size:
type: string
description: The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
enum:
- 1024x1024
- 1024x1536
- 1536x1024
quality:
type: string
description: The quality of the image generated. Either `low`, `medium`, or `high`.
enum:
- low
- medium
- high
usage:
$ref: '#/components/schemas/ImageGenUsage'
required:
- created
x-oaiMeta:
name: The image generation response
group: images
example: "{\n \"created\": 1713833628,\n \"data\": [\n {\n \"b64_json\": \"...\"\n }\n ],\n \"background\": \"transparent\",\n \"output_format\": \"png\",\n \"size\": \"1024x1024\",\n \"quality\": \"high\",\n \"usage\": {\n \"total_tokens\": 100,\n \"input_tokens\": 50,\n \"output_tokens\": 50,\n \"input_tokens_details\": {\n \"text_tokens\": 10,\n \"image_tokens\": 40\n }\n }\n}\n"
ImageGenInputUsageDetails:
properties:
text_tokens:
type: integer
description: The number of text tokens in the input prompt.
image_tokens:
type: integer
description: The number of image tokens in the input prompt.
type: object
required:
- text_tokens
- image_tokens
title: Input usage details
description: The input tokens detailed information for the image generation.
ImageGenStreamEvent:
anyOf:
- $ref: '#/components/schemas/ImageGenPartialImageEvent'
- $ref: '#/components/schemas/ImageGenCompletedEvent'
discriminator:
propertyName: type
ImageEditStreamEvent:
anyOf:
- $ref: '#/components/schemas/ImageEditPartialImageEvent'
- $ref: '#/components/schemas/ImageEditCompletedEvent'
discriminator:
propertyName: type
ImageGenPartialImageEvent:
type: object
description: 'Emitted when a partial image is available during image generation streaming.
'
properties:
type:
type: string
description: 'The type of the event. Always `image_generation.partial_image`.
'
enum:
- image_generation.partial_image
x-stainless-const: true
b64_json:
type: string
description: 'Base64-encoded partial image data, suitable for rendering as an image.
'
created_at:
type: integer
format: unixtime
description: 'The Unix timestamp when the event was created.
'
size:
type: string
description: 'The size of the requested image.
'
enum:
- 1024x1024
- 1024x1536
- 1536x1024
- auto
quality:
type: string
description: 'The quality setting for the requested image.
'
enum:
- low
- medium
- high
- auto
background:
type: string
description: 'The background setting for the requested image.
'
enum:
- transparent
- opaque
- auto
output_format:
type: string
description: 'The output format for the requested image.
'
enum:
- png
- webp
- jpeg
partial_image_index:
type: integer
description: '0-based index for the partial image (streaming).
'
required:
- type
- b64_json
- created_at
- size
- quality
- background
- output_format
- partial_image_index
x-oaiMeta:
name: image_generation.partial_image
group: images
example: "{\n \"type\": \"image_generation.partial_image\",\n \"b64_json\": \"...\",\n \"created_at\": 1620000000,\n \"size\": \"1024x1024\",\n \"quality\": \"high\",\n \"background\": \"transparent\",\n \"output_format\": \"png\",\n \"partial_image_index\": 0\n}\n"
ImageEditCompletedEvent:
type: object
description: 'Emitted when image editing has completed and the final image is available.
'
properties:
type:
type: string
description: 'The type of the event. Always `image_edit.completed`.
'
enum:
- image_edit.completed
x-stainless-const: true
b64_json:
type: string
description: 'Base64-encoded final edited image data, suitable for rendering as an image.
'
created_at:
type: integer
format: unixtime
description: 'The Unix timestamp when the event was created.
'
size:
type: string
description: 'The size of the edited image.
'
enum:
- 1024x1024
- 1024x1536
- 1536x1024
- auto
quality:
type: string
description: 'The quality setting for the edited image.
'
enum:
- low
- medium
- high
- auto
background:
type: string
description: 'The background setting for the edited image.
'
enum:
- transparent
- opaque
- auto
output_format:
type: string
description: 'The output format for the edited image.
'
enum:
- png
- webp
- jpeg
usage:
$ref: '#/components/schemas/ImagesUsage'
required:
- type
- b64_json
- created_at
- size
- quality
- background
- output_format
- usage
x-oaiMeta:
name: image_edit.completed
group: images
example: "{\n \"type\": \"image_edit.completed\",\n \"b64_json\": \"...\",\n \"created_at\": 1620000000,\n \"size\": \"1024x1024\",\n \"quality\": \"high\",\n \"background\": \"transparent\",\n \"output_format\": \"png\",\n \"usage\": {\n \"total_tokens\": 100,\n \"input_tokens\": 50,\n \"output_tokens\": 50,\n \"input_tokens_details\": {\n \"text_tokens\": 10,\n \"image_tokens\": 40\n }\n }\n}\n"
ImagesUsage:
type: object
description: 'For the GPT image models only, the token usage information for the image generation.
'
required:
- total_tokens
- input_tokens
- output_tokens
- input_tokens_details
properties:
total_tokens:
type: integer
description: 'The total number of tokens (images and text) used for the image generation.
'
input_tokens:
type: integer
description: The number of tokens (images and text) in the input prompt.
output_tokens:
type: integer
description: The number of image tokens in the output image.
input_tokens_details:
type: object
description: The input tokens detailed information for the image generation.
required:
- text_tokens
- image_tokens
properties:
text_tokens:
type: integer
description: The number of text tokens in the input prompt.
image_tokens:
type: integer
description: The number of image tokens in the input prompt.
CreateImageRequest_2:
type: object
properties:
prompt:
description: 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`.
type: string
example: A cute baby sea otter
model:
anyOf:
- type: string
- type: string
enum:
- gpt-image-1.5
- dall-e-2
- dall-e-3
- gpt-image-1
- gpt-image-1-mini
x-oaiTypeLabel: string
default: dall-e-2
example: gpt-image-1.5
nullable: true
description: 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`). Defaults to `dall-e-2` unless a parameter specific to the GPT image models is used.
n:
type: integer
minimum: 1
maximum: 10
default: 1
example: 1
nullable: true
description: The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported.
quality:
type: string
enum:
- standard
- hd
- low
- medium
- high
- auto
default: auto
example: medium
nullable: true
description: '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:
type: string
enum:
- url
- b64_json
default: url
example: url
nullable: true
description: 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.
output_format:
type: string
enum:
- png
- jpeg
- webp
default: png
example: png
nullable: true
description: 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`.
output_compression:
type: integer
default: 100
example: 100
nullable: true
description: 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.
stream:
type: boolean
default: false
example: false
nullable: true
description: 'Generate the image in streaming mode. Defaults to `false`. See the
[Image generation guide](/docs/guides/image-generation) for more information.
This parameter is only supported for the GPT image models.
'
partial_images:
$ref: '#/components/schemas/PartialImages'
size:
anyOf:
- type: string
- type: string
enum:
- auto
- 1024x1024
- 1536x1024
- 1024x1536
- 256x256
- 512x512
- 1792x1024
- 1024x1792
default: auto
example: 1024x1024
nullable: true
description: 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`.
moderation:
type: string
enum:
- low
- auto
default: auto
example: low
nullable: true
description: 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).
background:
type: string
enum:
- transparent
- opaque
- auto
default: auto
example: transparent
nullable: true
description: 'Allows to set transparency for the background of the generated image(s).
This parameter is only supported for the GPT image models. 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.
If `transparent`, the output format needs to support transparency, so it
should be set to either `png` (default value) or `webp`.
'
style:
type: string
enum:
- vivid
- natural
default: vivid
example: vivid
nullable: true
description: 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:
type: string
example: user-1234
description: 'A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).
'
required:
- prompt
InputFidelity:
type: string
enum:
- high
- low
description: 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`.
ImageRefParam:
type: object
description: 'Reference an input image by either URL or uploaded file ID.
Provide exactly one of `image_url` or `file_id`.
'
properties:
image_url:
type: string
format: uri
maxLength: 20971520
description: A fully qualified URL or base64-encoded data URL.
example: https://example.com/source-image.png
file_id:
type: string
description: The File API ID of an uploaded image to use as input.
example: file-abc123
anyOf:
- required:
- image_url
- required:
- file_id
not:
required:
- image_url
- file_id
additionalProperties: false
ImageGenCompletedEvent:
type: object
description: 'Emitted when image generation has completed and the final image is available.
'
properties:
type:
type: string
description: 'The type of the event. Always `image_generation.completed`.
'
enum:
- image_generation.completed
x-stainless-const: true
b64_json:
type: string
description: 'Base64-encoded image data, suitable for rendering as an image.
'
created_at:
type: integer
format: unixtime
description: 'The Unix timestamp when the event was created.
'
size:
type: string
description: 'The size of the generated image.
'
enum:
- 1024x1024
- 1024x1536
- 1536x1024
- auto
quality:
type: string
description: 'The quality setting for the generated image.
'
enum:
- low
- medium
- high
- auto
background:
type: string
description: 'The background setting for the generated image.
'
enum:
- transparent
- opaque
- auto
output_format:
type: string
description: 'The output format for the generated image.
'
enum:
- png
- webp
- jpeg
usage:
$ref: '#/components/schemas/ImagesUsage'
required:
- type
- b64_json
- created_at
- size
- quality
- background
- output_format
- usage
x-oaiMeta:
name: image_generation.completed
group: images
example: "{\n \"type\": \"image_generation.completed\",\n \"b64_json\": \"...\",\n \"created_at\": 1620000000,\n \"size\": \"1024x1024\",\n \"quality\": \"high\",\n \"background\": \"transparent\",\n \"output_form
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-images-api-openapi.yml