resources/images/methods/create_variation/index.md 2026-09-16 22:58 UTC to 2026-09-18 22:59 UTC

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

Create image variation

post /images/variations

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

Returns

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

    • "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" or 2 more

    The quality of the image generated. One of low, medium, high, xhigh, or max.

    • "low"

    • "medium"

    • "high"

    • "xhigh"

    • "max"

  • size: optional string or "1024x1024" or "1024x1536" or "1536x1024"

    The image dimensions as a WIDTHxHEIGHT string, for example 1536x864.

    • string

    • "1024x1024" or "1024x1536" or "1536x1024"

      The image dimensions as a WIDTHxHEIGHT string, for example 1536x864.

      • "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

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

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
    }
  }
}

Example

curl https://api.openai.com/v1/images/variations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F image="@otter.png" \
  -F n=2 \
  -F size="1024x1024"

Response

{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}