Skip to content
API Reference
Images

Create image variation

images.create_variation(**kwargs) -> ImagesResponse { created, background, data, 4 more }
POST/images/variations

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

ParametersExpand Collapse
image: FileInput

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.

Accepts one of the following:
String
ImageModel = :"gpt-image-1.5" | :"dall-e-2" | :"dall-e-3" | 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: Integer

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

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

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

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

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

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

ReturnsExpand Collapse
class ImagesResponse { created, background, data, 4 more }

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.

Accepts one of the following:
:transparent
:opaque
data: Array[Image { b64_json, revised_prompt, url } ]

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.

Accepts one of the following:
:png
:webp
:jpeg
quality: :low | :medium | :high

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

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

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

Accepts one of the following:
:"1024x1024"
:"1024x1536"
:"1536x1024"
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: { 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: { 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.

Create image variation

require "openai"

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

images_response = openai.images.create_variation(image: Pathname(__FILE__))

puts(images_response)
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}
Returns Examples
{
  "created": 1589478378,
  "data": [
    {
      "url": "https://..."
    },
    {
      "url": "https://..."
    }
  ]
}