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

Create image variation

images.create_variation(**kwargs) -> ImagesResponse

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: String | ImageModel

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

  • String = String

  • ImageModel = :"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: Integer

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

• response_format: :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: :"256x256" | :"512x512" | :"1024x1024"

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

  • :"256x256"

  • :"512x512"

  • :"1024x1024"

• user: String

  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: Integer

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

  • background: :transparent | :opaque

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

    • :transparent

    • :opaque

  • data: Array[Image]

    The list of generated images.

    • b64_json: 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: String

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

    • url: 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: :png | :webp | :jpeg

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

    • :png

    • :webp

    • :jpeg

  • quality: :low | :medium | :high

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

    • :low

    • :medium

    • :high

  • size: :"1024x1024" | :"1024x1536" | :"1536x1024"

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

    • :"1024x1024"

    • :"1024x1536"

    • :"1536x1024"

  • usage: Usage{ input_tokens, input_tokens_details, output_tokens, 2 more}

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

    • input_tokens: Integer

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

    • input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}

      The input tokens detailed information for the image generation.

      • image_tokens: Integer

        The number of image tokens in the input prompt.

      • text_tokens: Integer

        The number of text tokens in the input prompt.

    • output_tokens: Integer

      The number of output tokens generated by the model.

    • total_tokens: Integer

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

    • output_tokens_details: OutputTokensDetails{ image_tokens, text_tokens}

      The output token details for the image generation.

      • image_tokens: Integer

        The number of image output tokens generated by the model.

      • text_tokens: Integer

        The number of text output tokens generated by the model.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

images_response = openai.images.create_variation(image: StringIO.new("Example data"))

puts(images_response)

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