## Create image variation

`$ openai images create-variation`

**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: optional string or ImageModel`

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

- `--n: optional number`

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

- `--response-format: optional "url" or "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.

- `--size: optional "256x256" or "512x512" or "1024x1024"`

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

- `--user: optional string`

  A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids).

### Returns

- `images_response: object { created, background, data, 4 more }`

  The response from the image generation endpoint.

  - `created: number`

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

  - `background: optional "transparent" or "opaque"`

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

    - `"transparent"`

    - `"opaque"`

  - `data: optional array of Image`

    The list of generated images.

    - `b64_json: optional 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: optional string`

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

    - `url: optional 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: optional "png" or "webp" or "jpeg"`

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

    - `"png"`

    - `"webp"`

    - `"jpeg"`

  - `quality: optional "low" or "medium" or "high"`

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

    - `"low"`

    - `"medium"`

    - `"high"`

  - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`

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

    - `"1024x1024"`

    - `"1024x1536"`

    - `"1536x1024"`

  - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`

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

    - `input_tokens: number`

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

    - `input_tokens_details: object { image_tokens, text_tokens }`

      The input tokens detailed information for the image generation.

      - `image_tokens: number`

        The number of image tokens in the input prompt.

      - `text_tokens: number`

        The number of text tokens in the input prompt.

    - `output_tokens: number`

      The number of output tokens generated by the model.

    - `total_tokens: number`

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

    - `output_tokens_details: optional object { image_tokens, text_tokens }`

      The output token details for the image generation.

      - `image_tokens: number`

        The number of image output tokens generated by the model.

      - `text_tokens: number`

        The number of text output tokens generated by the model.

### Example

```cli
openai images create-variation \
  --api-key 'My API Key' \
  --image 'Example data'
```

#### Response

```json
{
  "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
    }
  }
}
```