ruby/resources/images/methods/create_variation/index.md +0 −211 deleted
File Deleted View Diff
1## Create image variation
2
3`images.create_variation(**kwargs) -> ImagesResponse`
4
5**post** `/images/variations`
6
7Creates a variation of a given image. This endpoint only supports `dall-e-2`.
8
9### Parameters
10
11- `image: String`
12
13 The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
14
15- `model: String | ImageModel`
16
17 The model to use for image generation. Only `dall-e-2` is supported at this time.
18
19 - `String = String`
20
21 - `ImageModel = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 5 more`
22
23 - `:"gpt-image-1"`
24
25 - `:"gpt-image-1-mini"`
26
27 - `:"gpt-image-2"`
28
29 - `:"gpt-image-2-2026-04-21"`
30
31 - `:"gpt-image-1.5"`
32
33 - `:"chatgpt-image-latest"`
34
35 - `:"dall-e-2"`
36
37 - `:"dall-e-3"`
38
39- `n: Integer`
40
41 The number of images to generate. Must be between 1 and 10.
42
43- `response_format: :url | :b64_json`
44
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.
46
47 - `:url`
48
49 - `:b64_json`
50
51- `size: :"256x256" | :"512x512" | :"1024x1024"`
52
53 The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.
54
55 - `:"256x256"`
56
57 - `:"512x512"`
58
59 - `:"1024x1024"`
60
61- `user: String`
62
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).
64
65### Returns
66
67- `class ImagesResponse`
68
69 The response from the image generation endpoint.
70
71 - `created: Integer`
72
73 The Unix timestamp (in seconds) of when the image was created.
74
75 - `background: :transparent | :opaque`
76
77 The background parameter used for the image generation. Either `transparent` or `opaque`.
78
79 - `:transparent`
80
81 - `:opaque`
82
83 - `data: Array[Image]`
84
85 The list of generated images.
86
87 - `b64_json: String`
88
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`.
90
91 - `revised_prompt: String`
92
93 For `dall-e-3` only, the revised prompt that was used to generate the image.
94
95 - `url: String`
96
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.
98
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```