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

Create image variation

client.Images.NewVariation(ctx, body) (*ImagesResponse, error)

post /images/variations

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

Parameters

• body ImageNewVariationParams

  • Image param.Field[Reader]

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

  • Model param.Field[ImageModel]

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

    • string

    • type ImageModel string

      • const ImageModelGPTImage1 ImageModel = "gpt-image-1"

      • const ImageModelGPTImage1Mini ImageModel = "gpt-image-1-mini"

      • const ImageModelGPTImage2 ImageModel = "gpt-image-2"

      • const ImageModelGPTImage2_2026_04_21 ImageModel = "gpt-image-2-2026-04-21"

      • const ImageModelGPTImage1_5 ImageModel = "gpt-image-1.5"

      • const ImageModelChatgptImageLatest ImageModel = "chatgpt-image-latest"

      • const ImageModelDallE2 ImageModel = "dall-e-2"

      • const ImageModelDallE3 ImageModel = "dall-e-3"

  • N param.Field[int64]

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

  • ResponseFormat param.Field[ImageNewVariationParamsResponseFormat]

    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.

    • const ImageNewVariationParamsResponseFormatURL ImageNewVariationParamsResponseFormat = "url"

    • const ImageNewVariationParamsResponseFormatB64JSON ImageNewVariationParamsResponseFormat = "b64_json"

  • Size param.Field[ImageNewVariationParamsSize]

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

    • const ImageNewVariationParamsSize256x256 ImageNewVariationParamsSize = "256x256"

    • const ImageNewVariationParamsSize512x512 ImageNewVariationParamsSize = "512x512"

    • const ImageNewVariationParamsSize1024x1024 ImageNewVariationParamsSize = "1024x1024"

  • User param.Field[string]

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

Returns

• type ImagesResponse struct{…}

  The response from the image generation endpoint.

  • Created int64

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

  • Background ImagesResponseBackground

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

    • const ImagesResponseBackgroundTransparent ImagesResponseBackground = "transparent"

    • const ImagesResponseBackgroundOpaque ImagesResponseBackground = "opaque"

  • Data []Image

    The list of generated images.

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

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

  • OutputFormat ImagesResponseOutputFormat

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

    • const ImagesResponseOutputFormatPNG ImagesResponseOutputFormat = "png"

    • const ImagesResponseOutputFormatWebP ImagesResponseOutputFormat = "webp"

    • const ImagesResponseOutputFormatJPEG ImagesResponseOutputFormat = "jpeg"

  • Quality ImagesResponseQuality

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

    • const ImagesResponseQualityLow ImagesResponseQuality = "low"

    • const ImagesResponseQualityMedium ImagesResponseQuality = "medium"

    • const ImagesResponseQualityHigh ImagesResponseQuality = "high"

  • Size ImagesResponseSize

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

    • const ImagesResponseSize1024x1024 ImagesResponseSize = "1024x1024"

    • const ImagesResponseSize1024x1536 ImagesResponseSize = "1024x1536"

    • const ImagesResponseSize1536x1024 ImagesResponseSize = "1536x1024"

  • Usage ImagesResponseUsage

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

    • InputTokens int64

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

    • InputTokensDetails ImagesResponseUsageInputTokensDetails

      The input tokens detailed information for the image generation.

      • ImageTokens int64

        The number of image tokens in the input prompt.

      • TextTokens int64

        The number of text tokens in the input prompt.

    • OutputTokens int64

      The number of output tokens generated by the model.

    • TotalTokens int64

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

    • OutputTokensDetails ImagesResponseUsageOutputTokensDetails

      The output token details for the image generation.

      • ImageTokens int64

        The number of image output tokens generated by the model.

      • TextTokens int64

        The number of text output tokens generated by the model.

Example

package main

import (
  "bytes"
  "context"
  "fmt"
  "io"

  "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

func main() {
  client := openai.NewClient(
    option.WithAPIKey("My API Key"),
  )
  imagesResponse, err := client.Images.NewVariation(context.TODO(), openai.ImageNewVariationParams{
    Image: io.Reader(bytes.NewBuffer([]byte("Example data"))),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", imagesResponse.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
    }
  }
}