Skip to content
API Reference
Images

Create image variation

ImagesResponse images().createVariation(ImageCreateVariationParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/images/variations

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

ParametersExpand Collapse
ImageCreateVariationParams params
InputStream image

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

Optional<ImageModel> model

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

GPT_IMAGE_1_5("gpt-image-1.5")
DALL_E_2("dall-e-2")
DALL_E_3("dall-e-3")
GPT_IMAGE_1("gpt-image-1")
GPT_IMAGE_1_MINI("gpt-image-1-mini")
Optional<Long> n

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

minimum1
maximum10
Optional<ResponseFormat> responseFormat

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("url")
B64_JSON("b64_json")
Optional<Size> size

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

_256X256("256x256")
_512X512("512x512")
_1024X1024("1024x1024")
Optional<String> user

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

ReturnsExpand Collapse
class ImagesResponse:

The response from the image generation endpoint.

long created

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

Optional<Background> background

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

Accepts one of the following:
TRANSPARENT("transparent")
OPAQUE("opaque")
Optional<List<Image>> data

The list of generated images.

Optional<String> b64Json

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.

Optional<String> revisedPrompt

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

Optional<String> url

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.

Optional<OutputFormat> outputFormat

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

Accepts one of the following:
PNG("png")
WEBP("webp")
JPEG("jpeg")
Optional<Quality> quality

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

Accepts one of the following:
LOW("low")
MEDIUM("medium")
HIGH("high")
Optional<Size> size

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

Accepts one of the following:
_1024X1024("1024x1024")
_1024X1536("1024x1536")
_1536X1024("1536x1024")
Optional<Usage> usage

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

long inputTokens

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

InputTokensDetails inputTokensDetails

The input tokens detailed information for the image generation.

long imageTokens

The number of image tokens in the input prompt.

long textTokens

The number of text tokens in the input prompt.

long outputTokens

The number of output tokens generated by the model.

long totalTokens

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

Optional<OutputTokensDetails> outputTokensDetails

The output token details for the image generation.

long imageTokens

The number of image output tokens generated by the model.

long textTokens

The number of text output tokens generated by the model.

Create image variation

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.images.ImageCreateVariationParams;
import com.openai.models.images.ImagesResponse;
import java.io.ByteArrayInputStream;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        ImageCreateVariationParams params = ImageCreateVariationParams.builder()
            .image(ByteArrayInputStream("some content".getBytes()))
            .build();
        ImagesResponse imagesResponse = client.images().createVariation(params);
    }
}
{
  "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
    }
  }
}