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

Create image variation

images.create_variation(**kwargs) -> ImagesResponse

post /images/variations

Create image variation

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: String | ImageModel

The model to use for image generation. Only dall-e-2 is supported at this time.
- String = String
- ImageModel = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 5 more
  - :"gpt-image-1"
  - :"gpt-image-1-mini"
  - :"gpt-image-2"
  - :"gpt-image-2-2026-04-21"
  - :"gpt-image-1.5"
  - :"chatgpt-image-latest"
  - :"dall-e-2"
  - :"dall-e-3"
n: Integer

The number of images to generate. Must be between 1 and 10.
response_format: :url | :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.
- :url
- :b64_json
size: :"256x256" | :"512x512" | :"1024x1024"

The size of the generated images. Must be one of 256x256, 512x512, or 1024x1024.
- :"256x256"
- :"512x512"
- :"1024x1024"
user: String

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

Returns

class ImagesResponse

The response from the image generation endpoint.
- created: Integer
  
  The Unix timestamp (in seconds) of when the image was created.
- background: :transparent | :opaque
  
  The background parameter used for the image generation. Either transparent or opaque.
  - :transparent
  - :opaque
- data: Array[Image]
  
  The list of generated images.
  - b64_json: 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: 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.
- output_format: :png | :webp | :jpeg
  
  The output format of the image generation. Either png, webp, or jpeg.
  - :png
  - :webp
  - :jpeg
- quality: :low | :medium | :high
  
  The quality of the image generated. Either low, medium, or high.
  - :low
  - :medium
  - :high
- size: :"1024x1024" | :"1024x1536" | :"1536x1024"
  
  The size of the image generated. Either 1024x1024, 1024x1536, or 1536x1024.
  - :"1024x1024"
  - :"1024x1536"
  - :"1536x1024"
- usage: Usage{ input_tokens, input_tokens_details, output_tokens, 2 more}
  
  For gpt-image-1 only, the token usage information for the image generation.
  - input_tokens: Integer
    
    The number of tokens (images and text) in the input prompt.
  - input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}
    
    The input tokens detailed information for the image generation.
    - image_tokens: Integer
      
      The number of image tokens in the input prompt.
    - text_tokens: Integer
      
      The number of text tokens in the input prompt.
  - output_tokens: Integer
    
    The number of output tokens generated by the model.
  - total_tokens: Integer
    
    The total number of tokens (images and text) used for the image generation.
  - output_tokens_details: OutputTokensDetails{ image_tokens, text_tokens}
    
    The output token details for the image generation.
    - image_tokens: Integer
      
      The number of image output tokens generated by the model.
    - text_tokens: Integer
      
      The number of text output tokens generated by the model.

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

images_response = openai.images.create_variation(image: StringIO.new("Example data"))

puts(images_response)

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

ruby/resources/images/methods/create_variation/index.md +211 −0 created

1## Create image variation

3`images.create_variation(**kwargs) -> ImagesResponse`

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

7Create image variation

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: String | ImageModel`

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

19 - `String = String`

21 - `ImageModel = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 5 more`

23 - `:"gpt-image-1"`

25 - `:"gpt-image-1-mini"`

27 - `:"gpt-image-2"`

29 - `:"gpt-image-2-2026-04-21"`

31 - `:"gpt-image-1.5"`

33 - `:"chatgpt-image-latest"`

35 - `:"dall-e-2"`

37 - `:"dall-e-3"`

39- `n: Integer`

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

43- `response_format: :url | :b64_json`

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

47 - `:url`

49 - `:b64_json`

51- `size: :"256x256" | :"512x512" | :"1024x1024"`

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

55 - `:"256x256"`

57 - `:"512x512"`

59 - `:"1024x1024"`

61- `user: String`

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

65### Returns

67- `class ImagesResponse`

69 The response from the image generation endpoint.

71 - `created: Integer`

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

75 - `background: :transparent | :opaque`

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

79 - `:transparent`

81 - `:opaque`

83 - `data: Array[Image]`

85 The list of generated images.

87 - `b64_json: String`

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

91 - `revised_prompt: String`

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

95 - `url: String`

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

99 - `output_format: :png | :webp | :jpeg`

100

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

102

103 - `:png`

104

105 - `:webp`

106

107 - `:jpeg`

108

109 - `quality: :low | :medium | :high`

110

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

112

113 - `:low`

114

115 - `:medium`

116

117 - `:high`

118

119 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024"`

120

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

122

123 - `:"1024x1024"`

124

125 - `:"1024x1536"`

126

127 - `:"1536x1024"`

128

129 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, 2 more}`

130

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

132

133 - `input_tokens: Integer`

134

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

136

137 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`

138

139 The input tokens detailed information for the image generation.

140

141 - `image_tokens: Integer`

142

143 The number of image tokens in the input prompt.

144

145 - `text_tokens: Integer`

146

147 The number of text tokens in the input prompt.

148

149 - `output_tokens: Integer`

150

151 The number of output tokens generated by the model.

152

153 - `total_tokens: Integer`

154

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

156

157 - `output_tokens_details: OutputTokensDetails{ image_tokens, text_tokens}`

158

159 The output token details for the image generation.

160

161 - `image_tokens: Integer`

162

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

164

165 - `text_tokens: Integer`

166

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

168

169### Example

170

171```ruby

172require "openai"

173

174openai = OpenAI::Client.new(api_key: "My API Key")

175

176images_response = openai.images.create_variation(image: StringIO.new("Example data"))

177

178puts(images_response)

179```

180

181#### Response

182

183```json

184{

185 "created": 0,

186 "background": "transparent",

187 "data": [

188 {

189 "b64_json": "b64_json",

190 "revised_prompt": "revised_prompt",

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

192 }

193 ],

194 "output_format": "png",

195 "quality": "low",

196 "size": "1024x1024",

197 "usage": {

198 "input_tokens": 0,

199 "input_tokens_details": {

200 "image_tokens": 0,

201 "text_tokens": 0

202 },

203 "output_tokens": 0,

204 "total_tokens": 0,

205 "output_tokens_details": {

206 "image_tokens": 0,

207 "text_tokens": 0

208 }

209 }

210}

211```

ruby/resources/images/methods/create_variation/index.md 2026-07-07 08:02 UTC to 2026-07-09 20:58 UTC

Create image variation

Parameters

Returns

Example

Response