Skip to content
API Reference
Images

Create image variation

POST/images/variations

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

Body ParametersForm DataExpand Collapse
image: file

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.

Accepts one of the following:
UnionMember0 = string
ImageModel = "gpt-image-1.5" or "dall-e-2" or "dall-e-3" or 2 more
Accepts one of the following:
"gpt-image-1.5"
"dall-e-2"
"dall-e-3"
"gpt-image-1"
"gpt-image-1-mini"
n: optional number

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

minimum1
maximum10
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.

Accepts one of the following:
"url"
"b64_json"
size: optional "256x256" or "512x512" or "1024x1024"

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

Accepts one of the following:
"256x256"
"512x512"
"1024x1024"
user: optional string

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

ReturnsExpand Collapse
ImagesResponse = 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.

Accepts one of the following:
"transparent"
"opaque"
data: optional array of Image { b64_json, revised_prompt, url }

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.

Accepts one of the following:
"png"
"webp"
"jpeg"
quality: optional "low" or "medium" or "high"

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

Accepts one of the following:
"low"
"medium"
"high"
size: optional "1024x1024" or "1024x1536" or "1536x1024"

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

Accepts one of the following:
"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.

Create image variation

curl https://api.openai.com/v1/images/variations \
    -H 'Content-Type: multipart/form-data' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -F 'image=@/path/to/image' \
    -F n=1 \
    -F response_format=url \
    -F size=1024x1024 \
    -F user=user-1234
{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "url"
    }
  ],
  "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
    }
  }
}
Returns Examples
{
  "created": 0,
  "background": "transparent",
  "data": [
    {
      "b64_json": "b64_json",
      "revised_prompt": "revised_prompt",
      "url": "url"
    }
  ],
  "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
    }
  }
}