OpenAI API (unofficial showcase)
POST/images/variationsDeprecated

Create image variations from an uploaded image

Creates image variations based on an uploaded image using the legacy image variations contract. This operation is retired and no longer available; use the image edits endpoint with a GPT Image model and a prompt to create a variation. The legacy request schema requires a square PNG image smaller than 4 MB.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

6 body fields

Legacy multipart form data for the retired image variations operation. The image field is required.

imagestringrequired
The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
modelstringoptional
The legacy model used by the retired image variations endpoint. This endpoint no longer accepts requests.
Default:dall-e-2
nintegeroptional
The number of images to generate. Must be between 1 and 10.
Default:1
response_formatstringoptional
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.
Allowed:urlb64_jsonnullDefault:url
sizestringoptional
The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.
Allowed:256x256512x5121024x1024nullDefault:1024x1024
userstringoptional
A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).

6 status codes
200Returns the generated image data and the creation timestamp.
safety_identifierstringoptional
The effective safety identifier used for safety monitoring and abuse detection. This is the non-empty `safety_identifier` from the request, or the deprecated `user` value when `safety_identifier` is omitted, null, or empty.
createdintegerrequired
The Unix timestamp (in seconds) of when the image was created.
dataarray<object>optional
The list of generated images.
backgroundstringoptional
The background parameter used for the image generation. Either `transparent` or `opaque`.
Allowed:transparentopaque
output_formatstringoptional
The output format of the image generation. Either `png`, `webp`, or `jpeg`.
Allowed:pngwebpjpeg
sizestringoptional
The image dimensions as a `WIDTHxHEIGHT` string, for example `1536x864`.
qualitystringoptional
The quality of the image generated. One of `low`, `medium`, `high`, `xhigh`, or `max`.
Allowed:lowmediumhighxhighmax
usageobjectoptional
For `gpt-image-1` only, the token usage information for the image generation.
400Returned when the image or request is invalid, or the request cannot be processed for the account.
errorobjectrequired
403Returned when the project does not have access to the requested model.
errorobjectrequired
410Returned when the image variations endpoint is no longer available.
errorobjectrequired
429Returned when the image rate limit is exceeded.
errorobjectrequired
500Returned when the image variation could not be generated or processed.
errorobjectrequired

Error handling

A 400 is returned when the image or request is invalid, a 403 when the project lacks access to the requested model, and a 410 because the image variations endpoint is no longer available. A 429 indicates that the image rate limit was exceeded, and a 500 indicates that the variation could not be generated or processed. The image field is required and must contain a square PNG smaller than 4 MB; n must be between 1 and 10 if provided.