cli/resources/images/methods/create_variation/index.md

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.

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

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

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
    }
  }
}

cli/resources/images/methods/create_variation/index.md +177 −0 created

1## Create image variation

3`$ openai images create-variation`

5**post** `/images/variations`

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

9### Parameters

11- `--image: string`

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

15- `--model: optional string or ImageModel`

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

19- `--n: optional number`

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

23- `--response-format: optional "url" or "b64_json"`

25 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.

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

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

31- `--user: optional string`

33 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).

35### Returns

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

39 The response from the image generation endpoint.

41 - `created: number`

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

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

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

49 - `"transparent"`

51 - `"opaque"`

53 - `data: optional array of Image`

55 The list of generated images.

57 - `b64_json: optional string`

59 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`.

61 - `revised_prompt: optional string`

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

65 - `url: optional string`

67 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.

69 - `output_format: optional "png" or "webp" or "jpeg"`

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

73 - `"png"`

75 - `"webp"`

77 - `"jpeg"`

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

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

83 - `"low"`

85 - `"medium"`

87 - `"high"`

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

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

93 - `"1024x1024"`

95 - `"1024x1536"`

97 - `"1536x1024"`

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

100

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

102

103 - `input_tokens: number`

104

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

106

107 - `input_tokens_details: object { image_tokens, text_tokens }`

108

109 The input tokens detailed information for the image generation.

110

111 - `image_tokens: number`

112

113 The number of image tokens in the input prompt.

114

115 - `text_tokens: number`

116

117 The number of text tokens in the input prompt.

118

119 - `output_tokens: number`

120

121 The number of output tokens generated by the model.

122

123 - `total_tokens: number`

124

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

126

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

128

129 The output token details for the image generation.

130

131 - `image_tokens: number`

132

133 The number of image output tokens generated by the model.

134

135 - `text_tokens: number`

136

137 The number of text output tokens generated by the model.

138

139### Example

140

141```cli

142openai images create-variation \

143 --api-key 'My API Key' \

144 --image 'Example data'

145```

146

147#### Response

148

149```json

150{

151 "created": 0,

152 "background": "transparent",

153 "data": [

154 {

155 "b64_json": "b64_json",

156 "revised_prompt": "revised_prompt",

157 "url": "https://example.com"

158 }

159 ],

160 "output_format": "png",

161 "quality": "low",

162 "size": "1024x1024",

163 "usage": {

164 "input_tokens": 0,

165 "input_tokens_details": {

166 "image_tokens": 0,

167 "text_tokens": 0

168 },

169 "output_tokens": 0,

170 "total_tokens": 0,

171 "output_tokens_details": {

172 "image_tokens": 0,

173 "text_tokens": 0

174 }

175 }

176}

177```