SpyBara
Go Premium

python/resources/images/methods/create_variation/index.md 2026-07-10 23:02 UTC to 2026-07-12 06:58 UTC

1 added, 1 removed.

2026
Wed 15 02:58 Tue 14 06:58 Mon 13 15:59 Sun 12 06:58 Fri 10 23:02 Thu 9 20:58 Tue 7 08:02

Create image variation

images.create_variation(ImageCreateVariationParams**kwargs) -> ImagesResponse

post /images/variations

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

Parameters

  • image: FileTypes

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

  • model: Optional[Union[str, ImageModel, null]]

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

    • str

    • Literal["gpt-image-1", "gpt-image-1-mini", "gpt-image-2", 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"

  • n: Optional[int]

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

  • response_format: Optional[Literal["url", "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.

    • "url"

    • "b64_json"

  • size: Optional[Literal["256x256", "512x512", "1024x1024"]]

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

    • "256x256"

    • "512x512"

    • "1024x1024"

  • user: Optional[str]

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

Returns

  • class ImagesResponse: …

    The response from the image generation endpoint.

    • created: int

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

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

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

      • "transparent"

      • "opaque"

    • data: Optional[List[Image]]

      The list of generated images.

      • b64_json: Optional[str]

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

      • revised_prompt: Optional[str]

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

      • url: Optional[str]

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

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

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

      • "png"

      • "webp"

      • "jpeg"

    • quality: Optional[Literal["low", "medium", "high"]]

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

      • "low"

      • "medium"

      • "high"

    • size: Optional[Literal["1024x1024", "1024x1536", "1536x1024"]]

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

      • "1024x1024"

      • "1024x1536"

      • "1536x1024"

    • usage: Optional[Usage]

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

      • input_tokens: int

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

      • input_tokens_details: UsageInputTokensDetails

        The input tokens detailed information for the image generation.

        • image_tokens: int

          The number of image tokens in the input prompt.

        • text_tokens: int

          The number of text tokens in the input prompt.

      • output_tokens: int

        The number of output tokens generated by the model.

      • total_tokens: int

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

      • output_tokens_details: Optional[UsageOutputTokensDetails]

        The output token details for the image generation.

        • image_tokens: int

          The number of image output tokens generated by the model.

        • text_tokens: int

          The number of text output tokens generated by the model.

Example

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
images_response = client.images.create_variation(
    image=b"Example data",
)
print(images_response.created)

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

from openai import OpenAI
client = OpenAI()

response = client.images.create_variation(
  image=open("image_edit_original.png", "rb"),
  n=2,
  size="1024x1024"
)

Response

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