ruby/resources/images/index.md +0 −1637 deleted
File Deleted View Diff
1# Images
2
3## Create image
4
5`images.generate(**kwargs) -> ImagesResponse`
6
7**post** `/images/generations`
8
9Creates an image given a prompt. [Learn more](https://platform.openai.com/docs/guides/images).
10
11### Parameters
12
13- `prompt: String`
14
15 A text description of the desired image(s). The maximum length is 32000 characters for the GPT image models, 1000 characters for `dall-e-2` and 4000 characters for `dall-e-3`.
16
17- `background: :transparent | :opaque | :auto`
18
19 Allows to set transparency for the background of the generated image(s).
20 This parameter is only supported for GPT image models that support
21 transparent backgrounds. Must be one of `transparent`, `opaque`, or
22 `auto` (default value). When `auto` is used, the model will
23 automatically determine the best background for the image.
24
25 `gpt-image-2` and `gpt-image-2-2026-04-21` do not support
26 transparent backgrounds. Requests with `background` set to
27 `transparent` will return an error for these models; use `opaque` or
28 `auto` instead.
29
30 If `transparent`, the output format needs to support transparency,
31 so it should be set to either `png` (default value) or `webp`.
32
33 - `:transparent`
34
35 - `:opaque`
36
37 - `:auto`
38
39- `model: String | ImageModel`
40
41 The model to use for image generation. One of `dall-e-2`, `dall-e-3`, or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, or `gpt-image-2-2026-04-21`). Defaults to `dall-e-2` unless a parameter specific to the GPT image models is used.
42
43 - `String = String`
44
45 - `ImageModel = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 5 more`
46
47 - `:"gpt-image-1"`
48
49 - `:"gpt-image-1-mini"`
50
51 - `:"gpt-image-2"`
52
53 - `:"gpt-image-2-2026-04-21"`
54
55 - `:"gpt-image-1.5"`
56
57 - `:"chatgpt-image-latest"`
58
59 - `:"dall-e-2"`
60
61 - `:"dall-e-3"`
62
63- `moderation: :low | :auto`
64
65 Control the content-moderation level for images generated by the GPT image models. Must be either `low` for less restrictive filtering or `auto` (default value).
66
67 - `:low`
68
69 - `:auto`
70
71- `n: Integer`
72
73 The number of images to generate. Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported.
74
75- `output_compression: Integer`
76
77 The compression level (0-100%) for the generated images. This parameter is only supported for the GPT image models with the `webp` or `jpeg` output formats, and defaults to 100.
78
79- `output_format: :png | :jpeg | :webp`
80
81 The format in which the generated images are returned. This parameter is only supported for the GPT image models. Must be one of `png`, `jpeg`, or `webp`.
82
83 - `:png`
84
85 - `:jpeg`
86
87 - `:webp`
88
89- `partial_images: Integer`
90
91 The number of partial images to generate. This parameter is used for
92 streaming responses that return partial images. Value must be between 0 and 3.
93 When set to 0, the response will be a single image sent in one streaming event.
94
95 Note that the final image may be sent before the full number of partial images
96 are generated if the full image is generated more quickly.
97
98- `quality: :standard | :hd | :low | 3 more`
99
100 The quality of the image that will be generated.
101
102 - `auto` (default value) will automatically select the best quality for the given model.
103 - `high`, `medium` and `low` are supported for the GPT image models.
104 - `hd` and `standard` are supported for `dall-e-3`.
105 - `standard` is the only option for `dall-e-2`.
106
107 - `:standard`
108
109 - `:hd`
110
111 - `:low`
112
113 - `:medium`
114
115 - `:high`
116
117 - `:auto`
118
119- `response_format: :url | :b64_json`
120
121 The format in which generated images with `dall-e-2` and `dall-e-3` are returned. Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the image has been generated. This parameter isn't supported for the GPT image models, which always return base64-encoded images.
122
123 - `:url`
124
125 - `:b64_json`
126
127- `size: String | :auto | :"1024x1024" | :"1536x1024" | 5 more`
128
129 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.
130
131 - `String = String`
132
133 - `Size = :auto | :"1024x1024" | :"1536x1024" | 5 more`
134
135 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.
136
137 - `:auto`
138
139 - `:"1024x1024"`
140
141 - `:"1536x1024"`
142
143 - `:"1024x1536"`
144
145 - `:"256x256"`
146
147 - `:"512x512"`
148
149 - `:"1792x1024"`
150
151 - `:"1024x1792"`
152
153- `stream: bool`
154
155 Generate the image in streaming mode. Defaults to `false`. See the
156 [Image generation guide](https://platform.openai.com/docs/guides/image-generation) for more information.
157 This parameter is only supported for the GPT image models.
158
159- `style: :vivid | :natural`
160
161 The style of the generated images. This parameter is only supported for `dall-e-3`. Must be one of `vivid` or `natural`. Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images.
162
163 - `:vivid`
164
165 - `:natural`
166
167- `user: String`
168
169 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).
170
171### Returns
172
173- `class ImagesResponse`
174
175 The response from the image generation endpoint.
176
177 - `created: Integer`
178
179 The Unix timestamp (in seconds) of when the image was created.
180
181 - `background: :transparent | :opaque`
182
183 The background parameter used for the image generation. Either `transparent` or `opaque`.
184
185 - `:transparent`
186
187 - `:opaque`
188
189 - `data: Array[Image]`
190
191 The list of generated images.
192
193 - `b64_json: String`
194
195 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`.
196
197 - `revised_prompt: String`
198
199 For `dall-e-3` only, the revised prompt that was used to generate the image.
200
201 - `url: String`
202
203 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.
204
205 - `output_format: :png | :webp | :jpeg`
206
207 The output format of the image generation. Either `png`, `webp`, or `jpeg`.
208
209 - `:png`
210
211 - `:webp`
212
213 - `:jpeg`
214
215 - `quality: :low | :medium | :high`
216
217 The quality of the image generated. Either `low`, `medium`, or `high`.
218
219 - `:low`
220
221 - `:medium`
222
223 - `:high`
224
225 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024"`
226
227 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
228
229 - `:"1024x1024"`
230
231 - `:"1024x1536"`
232
233 - `:"1536x1024"`
234
235 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, 2 more}`
236
237 For `gpt-image-1` only, the token usage information for the image generation.
238
239 - `input_tokens: Integer`
240
241 The number of tokens (images and text) in the input prompt.
242
243 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
244
245 The input tokens detailed information for the image generation.
246
247 - `image_tokens: Integer`
248
249 The number of image tokens in the input prompt.
250
251 - `text_tokens: Integer`
252
253 The number of text tokens in the input prompt.
254
255 - `output_tokens: Integer`
256
257 The number of output tokens generated by the model.
258
259 - `total_tokens: Integer`
260
261 The total number of tokens (images and text) used for the image generation.
262
263 - `output_tokens_details: OutputTokensDetails{ image_tokens, text_tokens}`
264
265 The output token details for the image generation.
266
267 - `image_tokens: Integer`
268
269 The number of image output tokens generated by the model.
270
271 - `text_tokens: Integer`
272
273 The number of text output tokens generated by the model.
274
275### Example
276
277```ruby
278require "openai"
279
280openai = OpenAI::Client.new(api_key: "My API Key")
281
282images_response = openai.images.generate(prompt: "A cute baby sea otter")
283
284puts(images_response)
285```
286
287#### Response
288
289```json
290{
291 "created": 0,
292 "background": "transparent",
293 "data": [
294 {
295 "b64_json": "b64_json",
296 "revised_prompt": "revised_prompt",
297 "url": "https://example.com"
298 }
299 ],
300 "output_format": "png",
301 "quality": "low",
302 "size": "1024x1024",
303 "usage": {
304 "input_tokens": 0,
305 "input_tokens_details": {
306 "image_tokens": 0,
307 "text_tokens": 0
308 },
309 "output_tokens": 0,
310 "total_tokens": 0,
311 "output_tokens_details": {
312 "image_tokens": 0,
313 "text_tokens": 0
314 }
315 }
316}
317```
318
319## Create image edit
320
321`images.edit(**kwargs) -> ImagesResponse`
322
323**post** `/images/edits`
324
325Creates an edited or extended image given one or more source images and a prompt. This endpoint supports GPT Image models (`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`, and `chatgpt-image-latest`) and `dall-e-2`.
326
327### Parameters
328
329- `image: String | Array[String]`
330
331 The image(s) to edit. Must be a supported image file or an array of images.
332
333 For the GPT image models (`gpt-image-1`, `gpt-image-1-mini`,
334 `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, and
335 `chatgpt-image-latest`), each image should be a `png`, `webp`, or
336 `jpg` file less than 50MB. You can provide up to 16 images.
337
338 For `dall-e-2`, you can only provide one image, and it should be a
339 square `png` file less than 4MB.
340
341 - `String = String`
342
343 - `UnionMember1 = Array[String]`
344
345- `prompt: String`
346
347 A text description of the desired image(s). The maximum length is 1000 characters for `dall-e-2`, and 32000 characters for the GPT image models.
348
349- `background: :transparent | :opaque | :auto`
350
351 Allows to set transparency for the background of the generated image(s).
352 This parameter is only supported for GPT image models that support
353 transparent backgrounds. Must be one of `transparent`, `opaque`, or
354 `auto` (default value). When `auto` is used, the model will
355 automatically determine the best background for the image.
356
357 `gpt-image-2` and `gpt-image-2-2026-04-21` do not support
358 transparent backgrounds. Requests with `background` set to
359 `transparent` will return an error for these models; use `opaque` or
360 `auto` instead.
361
362 If `transparent`, the output format needs to support transparency,
363 so it should be set to either `png` (default value) or `webp`.
364
365 - `:transparent`
366
367 - `:opaque`
368
369 - `:auto`
370
371- `input_fidelity: :high | :low`
372
373 Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
374
375 - `:high`
376
377 - `:low`
378
379- `mask: String`
380
381 An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where `image` should be edited. If there are multiple images provided, the mask will be applied on the first image. Must be a valid PNG file, less than 4MB, and have the same dimensions as `image`.
382
383- `model: String | ImageModel`
384
385 The model to use for image generation. One of `dall-e-2` or a GPT image model (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, or `chatgpt-image-latest`). Defaults to `gpt-image-1.5`.
386
387 - `String = String`
388
389 - `ImageModel = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 5 more`
390
391 - `:"gpt-image-1"`
392
393 - `:"gpt-image-1-mini"`
394
395 - `:"gpt-image-2"`
396
397 - `:"gpt-image-2-2026-04-21"`
398
399 - `:"gpt-image-1.5"`
400
401 - `:"chatgpt-image-latest"`
402
403 - `:"dall-e-2"`
404
405 - `:"dall-e-3"`
406
407- `n: Integer`
408
409 The number of images to generate. Must be between 1 and 10.
410
411- `output_compression: Integer`
412
413 The compression level (0-100%) for the generated images. This parameter
414 is only supported for the GPT image models with the `webp` or `jpeg` output
415 formats, and defaults to 100.
416
417- `output_format: :png | :jpeg | :webp`
418
419 The format in which the generated images are returned. This parameter is
420 only supported for the GPT image models. Must be one of `png`, `jpeg`, or `webp`.
421 The default value is `png`.
422
423 - `:png`
424
425 - `:jpeg`
426
427 - `:webp`
428
429- `partial_images: Integer`
430
431 The number of partial images to generate. This parameter is used for
432 streaming responses that return partial images. Value must be between 0 and 3.
433 When set to 0, the response will be a single image sent in one streaming event.
434
435 Note that the final image may be sent before the full number of partial images
436 are generated if the full image is generated more quickly.
437
438- `quality: :standard | :low | :medium | 2 more`
439
440 The quality of the image that will be generated for GPT image models. Defaults to `auto`.
441
442 - `:standard`
443
444 - `:low`
445
446 - `:medium`
447
448 - `:high`
449
450 - `:auto`
451
452- `response_format: :url | :b64_json`
453
454 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. This parameter is only supported for `dall-e-2` (default is `url` for `dall-e-2`), as GPT image models always return base64-encoded images.
455
456 - `:url`
457
458 - `:b64_json`
459
460- `size: String | :"256x256" | :"512x512" | :"1024x1024" | 3 more`
461
462 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.
463
464 - `String = String`
465
466 - `Size = :"256x256" | :"512x512" | :"1024x1024" | 3 more`
467
468 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.
469
470 - `:"256x256"`
471
472 - `:"512x512"`
473
474 - `:"1024x1024"`
475
476 - `:"1536x1024"`
477
478 - `:"1024x1536"`
479
480 - `:auto`
481
482- `stream: bool`
483
484 Edit the image in streaming mode. Defaults to `false`. See the
485 [Image generation guide](https://platform.openai.com/docs/guides/image-generation) for more information.
486
487- `user: String`
488
489 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).
490
491### Returns
492
493- `class ImagesResponse`
494
495 The response from the image generation endpoint.
496
497 - `created: Integer`
498
499 The Unix timestamp (in seconds) of when the image was created.
500
501 - `background: :transparent | :opaque`
502
503 The background parameter used for the image generation. Either `transparent` or `opaque`.
504
505 - `:transparent`
506
507 - `:opaque`
508
509 - `data: Array[Image]`
510
511 The list of generated images.
512
513 - `b64_json: String`
514
515 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`.
516
517 - `revised_prompt: String`
518
519 For `dall-e-3` only, the revised prompt that was used to generate the image.
520
521 - `url: String`
522
523 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.
524
525 - `output_format: :png | :webp | :jpeg`
526
527 The output format of the image generation. Either `png`, `webp`, or `jpeg`.
528
529 - `:png`
530
531 - `:webp`
532
533 - `:jpeg`
534
535 - `quality: :low | :medium | :high`
536
537 The quality of the image generated. Either `low`, `medium`, or `high`.
538
539 - `:low`
540
541 - `:medium`
542
543 - `:high`
544
545 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024"`
546
547 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
548
549 - `:"1024x1024"`
550
551 - `:"1024x1536"`
552
553 - `:"1536x1024"`
554
555 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, 2 more}`
556
557 For `gpt-image-1` only, the token usage information for the image generation.
558
559 - `input_tokens: Integer`
560
561 The number of tokens (images and text) in the input prompt.
562
563 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
564
565 The input tokens detailed information for the image generation.
566
567 - `image_tokens: Integer`
568
569 The number of image tokens in the input prompt.
570
571 - `text_tokens: Integer`
572
573 The number of text tokens in the input prompt.
574
575 - `output_tokens: Integer`
576
577 The number of output tokens generated by the model.
578
579 - `total_tokens: Integer`
580
581 The total number of tokens (images and text) used for the image generation.
582
583 - `output_tokens_details: OutputTokensDetails{ image_tokens, text_tokens}`
584
585 The output token details for the image generation.
586
587 - `image_tokens: Integer`
588
589 The number of image output tokens generated by the model.
590
591 - `text_tokens: Integer`
592
593 The number of text output tokens generated by the model.
594
595### Example
596
597```ruby
598require "openai"
599
600openai = OpenAI::Client.new(api_key: "My API Key")
601
602images_response = openai.images.edit(image: StringIO.new("Example data"), prompt: "A cute baby sea otter wearing a beret")
603
604puts(images_response)
605```
606
607#### Response
608
609```json
610{
611 "created": 0,
612 "background": "transparent",
613 "data": [
614 {
615 "b64_json": "b64_json",
616 "revised_prompt": "revised_prompt",
617 "url": "https://example.com"
618 }
619 ],
620 "output_format": "png",
621 "quality": "low",
622 "size": "1024x1024",
623 "usage": {
624 "input_tokens": 0,
625 "input_tokens_details": {
626 "image_tokens": 0,
627 "text_tokens": 0
628 },
629 "output_tokens": 0,
630 "total_tokens": 0,
631 "output_tokens_details": {
632 "image_tokens": 0,
633 "text_tokens": 0
634 }
635 }
636}
637```
638
639## Create image variation
640
641`images.create_variation(**kwargs) -> ImagesResponse`
642
643**post** `/images/variations`
644
645Creates a variation of a given image. This endpoint only supports `dall-e-2`.
646
647### Parameters
648
649- `image: String`
650
651 The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.
652
653- `model: String | ImageModel`
654
655 The model to use for image generation. Only `dall-e-2` is supported at this time.
656
657 - `String = String`
658
659 - `ImageModel = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 5 more`
660
661 - `:"gpt-image-1"`
662
663 - `:"gpt-image-1-mini"`
664
665 - `:"gpt-image-2"`
666
667 - `:"gpt-image-2-2026-04-21"`
668
669 - `:"gpt-image-1.5"`
670
671 - `:"chatgpt-image-latest"`
672
673 - `:"dall-e-2"`
674
675 - `:"dall-e-3"`
676
677- `n: Integer`
678
679 The number of images to generate. Must be between 1 and 10.
680
681- `response_format: :url | :b64_json`
682
683 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.
684
685 - `:url`
686
687 - `:b64_json`
688
689- `size: :"256x256" | :"512x512" | :"1024x1024"`
690
691 The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.
692
693 - `:"256x256"`
694
695 - `:"512x512"`
696
697 - `:"1024x1024"`
698
699- `user: String`
700
701 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).
702
703### Returns
704
705- `class ImagesResponse`
706
707 The response from the image generation endpoint.
708
709 - `created: Integer`
710
711 The Unix timestamp (in seconds) of when the image was created.
712
713 - `background: :transparent | :opaque`
714
715 The background parameter used for the image generation. Either `transparent` or `opaque`.
716
717 - `:transparent`
718
719 - `:opaque`
720
721 - `data: Array[Image]`
722
723 The list of generated images.
724
725 - `b64_json: String`
726
727 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`.
728
729 - `revised_prompt: String`
730
731 For `dall-e-3` only, the revised prompt that was used to generate the image.
732
733 - `url: String`
734
735 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.
736
737 - `output_format: :png | :webp | :jpeg`
738
739 The output format of the image generation. Either `png`, `webp`, or `jpeg`.
740
741 - `:png`
742
743 - `:webp`
744
745 - `:jpeg`
746
747 - `quality: :low | :medium | :high`
748
749 The quality of the image generated. Either `low`, `medium`, or `high`.
750
751 - `:low`
752
753 - `:medium`
754
755 - `:high`
756
757 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024"`
758
759 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
760
761 - `:"1024x1024"`
762
763 - `:"1024x1536"`
764
765 - `:"1536x1024"`
766
767 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, 2 more}`
768
769 For `gpt-image-1` only, the token usage information for the image generation.
770
771 - `input_tokens: Integer`
772
773 The number of tokens (images and text) in the input prompt.
774
775 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
776
777 The input tokens detailed information for the image generation.
778
779 - `image_tokens: Integer`
780
781 The number of image tokens in the input prompt.
782
783 - `text_tokens: Integer`
784
785 The number of text tokens in the input prompt.
786
787 - `output_tokens: Integer`
788
789 The number of output tokens generated by the model.
790
791 - `total_tokens: Integer`
792
793 The total number of tokens (images and text) used for the image generation.
794
795 - `output_tokens_details: OutputTokensDetails{ image_tokens, text_tokens}`
796
797 The output token details for the image generation.
798
799 - `image_tokens: Integer`
800
801 The number of image output tokens generated by the model.
802
803 - `text_tokens: Integer`
804
805 The number of text output tokens generated by the model.
806
807### Example
808
809```ruby
810require "openai"
811
812openai = OpenAI::Client.new(api_key: "My API Key")
813
814images_response = openai.images.create_variation(image: StringIO.new("Example data"))
815
816puts(images_response)
817```
818
819#### Response
820
821```json
822{
823 "created": 0,
824 "background": "transparent",
825 "data": [
826 {
827 "b64_json": "b64_json",
828 "revised_prompt": "revised_prompt",
829 "url": "https://example.com"
830 }
831 ],
832 "output_format": "png",
833 "quality": "low",
834 "size": "1024x1024",
835 "usage": {
836 "input_tokens": 0,
837 "input_tokens_details": {
838 "image_tokens": 0,
839 "text_tokens": 0
840 },
841 "output_tokens": 0,
842 "total_tokens": 0,
843 "output_tokens_details": {
844 "image_tokens": 0,
845 "text_tokens": 0
846 }
847 }
848}
849```
850
851## Domain Types
852
853### Image
854
855- `class Image`
856
857 Represents the content or the URL of an image generated by the OpenAI API.
858
859 - `b64_json: String`
860
861 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`.
862
863 - `revised_prompt: String`
864
865 For `dall-e-3` only, the revised prompt that was used to generate the image.
866
867 - `url: String`
868
869 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.
870
871### Image Edit Completed Event
872
873- `class ImageEditCompletedEvent`
874
875 Emitted when image editing has completed and the final image is available.
876
877 - `b64_json: String`
878
879 Base64-encoded final edited image data, suitable for rendering as an image.
880
881 - `background: :transparent | :opaque | :auto`
882
883 The background setting for the edited image.
884
885 - `:transparent`
886
887 - `:opaque`
888
889 - `:auto`
890
891 - `created_at: Integer`
892
893 The Unix timestamp when the event was created.
894
895 - `output_format: :png | :webp | :jpeg`
896
897 The output format for the edited image.
898
899 - `:png`
900
901 - `:webp`
902
903 - `:jpeg`
904
905 - `quality: :low | :medium | :high | :auto`
906
907 The quality setting for the edited image.
908
909 - `:low`
910
911 - `:medium`
912
913 - `:high`
914
915 - `:auto`
916
917 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
918
919 The size of the edited image.
920
921 - `:"1024x1024"`
922
923 - `:"1024x1536"`
924
925 - `:"1536x1024"`
926
927 - `:auto`
928
929 - `type: :"image_edit.completed"`
930
931 The type of the event. Always `image_edit.completed`.
932
933 - `:"image_edit.completed"`
934
935 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, total_tokens}`
936
937 For the GPT image models only, the token usage information for the image generation.
938
939 - `input_tokens: Integer`
940
941 The number of tokens (images and text) in the input prompt.
942
943 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
944
945 The input tokens detailed information for the image generation.
946
947 - `image_tokens: Integer`
948
949 The number of image tokens in the input prompt.
950
951 - `text_tokens: Integer`
952
953 The number of text tokens in the input prompt.
954
955 - `output_tokens: Integer`
956
957 The number of image tokens in the output image.
958
959 - `total_tokens: Integer`
960
961 The total number of tokens (images and text) used for the image generation.
962
963### Image Edit Partial Image Event
964
965- `class ImageEditPartialImageEvent`
966
967 Emitted when a partial image is available during image editing streaming.
968
969 - `b64_json: String`
970
971 Base64-encoded partial image data, suitable for rendering as an image.
972
973 - `background: :transparent | :opaque | :auto`
974
975 The background setting for the requested edited image.
976
977 - `:transparent`
978
979 - `:opaque`
980
981 - `:auto`
982
983 - `created_at: Integer`
984
985 The Unix timestamp when the event was created.
986
987 - `output_format: :png | :webp | :jpeg`
988
989 The output format for the requested edited image.
990
991 - `:png`
992
993 - `:webp`
994
995 - `:jpeg`
996
997 - `partial_image_index: Integer`
998
999 0-based index for the partial image (streaming).
1000
1001 - `quality: :low | :medium | :high | :auto`
1002
1003 The quality setting for the requested edited image.
1004
1005 - `:low`
1006
1007 - `:medium`
1008
1009 - `:high`
1010
1011 - `:auto`
1012
1013 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
1014
1015 The size of the requested edited image.
1016
1017 - `:"1024x1024"`
1018
1019 - `:"1024x1536"`
1020
1021 - `:"1536x1024"`
1022
1023 - `:auto`
1024
1025 - `type: :"image_edit.partial_image"`
1026
1027 The type of the event. Always `image_edit.partial_image`.
1028
1029 - `:"image_edit.partial_image"`
1030
1031### Image Edit Stream Event
1032
1033- `ImageEditStreamEvent = ImageEditPartialImageEvent | ImageEditCompletedEvent`
1034
1035 Emitted when a partial image is available during image editing streaming.
1036
1037 - `class ImageEditPartialImageEvent`
1038
1039 Emitted when a partial image is available during image editing streaming.
1040
1041 - `b64_json: String`
1042
1043 Base64-encoded partial image data, suitable for rendering as an image.
1044
1045 - `background: :transparent | :opaque | :auto`
1046
1047 The background setting for the requested edited image.
1048
1049 - `:transparent`
1050
1051 - `:opaque`
1052
1053 - `:auto`
1054
1055 - `created_at: Integer`
1056
1057 The Unix timestamp when the event was created.
1058
1059 - `output_format: :png | :webp | :jpeg`
1060
1061 The output format for the requested edited image.
1062
1063 - `:png`
1064
1065 - `:webp`
1066
1067 - `:jpeg`
1068
1069 - `partial_image_index: Integer`
1070
1071 0-based index for the partial image (streaming).
1072
1073 - `quality: :low | :medium | :high | :auto`
1074
1075 The quality setting for the requested edited image.
1076
1077 - `:low`
1078
1079 - `:medium`
1080
1081 - `:high`
1082
1083 - `:auto`
1084
1085 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
1086
1087 The size of the requested edited image.
1088
1089 - `:"1024x1024"`
1090
1091 - `:"1024x1536"`
1092
1093 - `:"1536x1024"`
1094
1095 - `:auto`
1096
1097 - `type: :"image_edit.partial_image"`
1098
1099 The type of the event. Always `image_edit.partial_image`.
1100
1101 - `:"image_edit.partial_image"`
1102
1103 - `class ImageEditCompletedEvent`
1104
1105 Emitted when image editing has completed and the final image is available.
1106
1107 - `b64_json: String`
1108
1109 Base64-encoded final edited image data, suitable for rendering as an image.
1110
1111 - `background: :transparent | :opaque | :auto`
1112
1113 The background setting for the edited image.
1114
1115 - `:transparent`
1116
1117 - `:opaque`
1118
1119 - `:auto`
1120
1121 - `created_at: Integer`
1122
1123 The Unix timestamp when the event was created.
1124
1125 - `output_format: :png | :webp | :jpeg`
1126
1127 The output format for the edited image.
1128
1129 - `:png`
1130
1131 - `:webp`
1132
1133 - `:jpeg`
1134
1135 - `quality: :low | :medium | :high | :auto`
1136
1137 The quality setting for the edited image.
1138
1139 - `:low`
1140
1141 - `:medium`
1142
1143 - `:high`
1144
1145 - `:auto`
1146
1147 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
1148
1149 The size of the edited image.
1150
1151 - `:"1024x1024"`
1152
1153 - `:"1024x1536"`
1154
1155 - `:"1536x1024"`
1156
1157 - `:auto`
1158
1159 - `type: :"image_edit.completed"`
1160
1161 The type of the event. Always `image_edit.completed`.
1162
1163 - `:"image_edit.completed"`
1164
1165 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, total_tokens}`
1166
1167 For the GPT image models only, the token usage information for the image generation.
1168
1169 - `input_tokens: Integer`
1170
1171 The number of tokens (images and text) in the input prompt.
1172
1173 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
1174
1175 The input tokens detailed information for the image generation.
1176
1177 - `image_tokens: Integer`
1178
1179 The number of image tokens in the input prompt.
1180
1181 - `text_tokens: Integer`
1182
1183 The number of text tokens in the input prompt.
1184
1185 - `output_tokens: Integer`
1186
1187 The number of image tokens in the output image.
1188
1189 - `total_tokens: Integer`
1190
1191 The total number of tokens (images and text) used for the image generation.
1192
1193### Image Gen Completed Event
1194
1195- `class ImageGenCompletedEvent`
1196
1197 Emitted when image generation has completed and the final image is available.
1198
1199 - `b64_json: String`
1200
1201 Base64-encoded image data, suitable for rendering as an image.
1202
1203 - `background: :transparent | :opaque | :auto`
1204
1205 The background setting for the generated image.
1206
1207 - `:transparent`
1208
1209 - `:opaque`
1210
1211 - `:auto`
1212
1213 - `created_at: Integer`
1214
1215 The Unix timestamp when the event was created.
1216
1217 - `output_format: :png | :webp | :jpeg`
1218
1219 The output format for the generated image.
1220
1221 - `:png`
1222
1223 - `:webp`
1224
1225 - `:jpeg`
1226
1227 - `quality: :low | :medium | :high | :auto`
1228
1229 The quality setting for the generated image.
1230
1231 - `:low`
1232
1233 - `:medium`
1234
1235 - `:high`
1236
1237 - `:auto`
1238
1239 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
1240
1241 The size of the generated image.
1242
1243 - `:"1024x1024"`
1244
1245 - `:"1024x1536"`
1246
1247 - `:"1536x1024"`
1248
1249 - `:auto`
1250
1251 - `type: :"image_generation.completed"`
1252
1253 The type of the event. Always `image_generation.completed`.
1254
1255 - `:"image_generation.completed"`
1256
1257 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, total_tokens}`
1258
1259 For the GPT image models only, the token usage information for the image generation.
1260
1261 - `input_tokens: Integer`
1262
1263 The number of tokens (images and text) in the input prompt.
1264
1265 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
1266
1267 The input tokens detailed information for the image generation.
1268
1269 - `image_tokens: Integer`
1270
1271 The number of image tokens in the input prompt.
1272
1273 - `text_tokens: Integer`
1274
1275 The number of text tokens in the input prompt.
1276
1277 - `output_tokens: Integer`
1278
1279 The number of image tokens in the output image.
1280
1281 - `total_tokens: Integer`
1282
1283 The total number of tokens (images and text) used for the image generation.
1284
1285### Image Gen Partial Image Event
1286
1287- `class ImageGenPartialImageEvent`
1288
1289 Emitted when a partial image is available during image generation streaming.
1290
1291 - `b64_json: String`
1292
1293 Base64-encoded partial image data, suitable for rendering as an image.
1294
1295 - `background: :transparent | :opaque | :auto`
1296
1297 The background setting for the requested image.
1298
1299 - `:transparent`
1300
1301 - `:opaque`
1302
1303 - `:auto`
1304
1305 - `created_at: Integer`
1306
1307 The Unix timestamp when the event was created.
1308
1309 - `output_format: :png | :webp | :jpeg`
1310
1311 The output format for the requested image.
1312
1313 - `:png`
1314
1315 - `:webp`
1316
1317 - `:jpeg`
1318
1319 - `partial_image_index: Integer`
1320
1321 0-based index for the partial image (streaming).
1322
1323 - `quality: :low | :medium | :high | :auto`
1324
1325 The quality setting for the requested image.
1326
1327 - `:low`
1328
1329 - `:medium`
1330
1331 - `:high`
1332
1333 - `:auto`
1334
1335 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
1336
1337 The size of the requested image.
1338
1339 - `:"1024x1024"`
1340
1341 - `:"1024x1536"`
1342
1343 - `:"1536x1024"`
1344
1345 - `:auto`
1346
1347 - `type: :"image_generation.partial_image"`
1348
1349 The type of the event. Always `image_generation.partial_image`.
1350
1351 - `:"image_generation.partial_image"`
1352
1353### Image Gen Stream Event
1354
1355- `ImageGenStreamEvent = ImageGenPartialImageEvent | ImageGenCompletedEvent`
1356
1357 Emitted when a partial image is available during image generation streaming.
1358
1359 - `class ImageGenPartialImageEvent`
1360
1361 Emitted when a partial image is available during image generation streaming.
1362
1363 - `b64_json: String`
1364
1365 Base64-encoded partial image data, suitable for rendering as an image.
1366
1367 - `background: :transparent | :opaque | :auto`
1368
1369 The background setting for the requested image.
1370
1371 - `:transparent`
1372
1373 - `:opaque`
1374
1375 - `:auto`
1376
1377 - `created_at: Integer`
1378
1379 The Unix timestamp when the event was created.
1380
1381 - `output_format: :png | :webp | :jpeg`
1382
1383 The output format for the requested image.
1384
1385 - `:png`
1386
1387 - `:webp`
1388
1389 - `:jpeg`
1390
1391 - `partial_image_index: Integer`
1392
1393 0-based index for the partial image (streaming).
1394
1395 - `quality: :low | :medium | :high | :auto`
1396
1397 The quality setting for the requested image.
1398
1399 - `:low`
1400
1401 - `:medium`
1402
1403 - `:high`
1404
1405 - `:auto`
1406
1407 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
1408
1409 The size of the requested image.
1410
1411 - `:"1024x1024"`
1412
1413 - `:"1024x1536"`
1414
1415 - `:"1536x1024"`
1416
1417 - `:auto`
1418
1419 - `type: :"image_generation.partial_image"`
1420
1421 The type of the event. Always `image_generation.partial_image`.
1422
1423 - `:"image_generation.partial_image"`
1424
1425 - `class ImageGenCompletedEvent`
1426
1427 Emitted when image generation has completed and the final image is available.
1428
1429 - `b64_json: String`
1430
1431 Base64-encoded image data, suitable for rendering as an image.
1432
1433 - `background: :transparent | :opaque | :auto`
1434
1435 The background setting for the generated image.
1436
1437 - `:transparent`
1438
1439 - `:opaque`
1440
1441 - `:auto`
1442
1443 - `created_at: Integer`
1444
1445 The Unix timestamp when the event was created.
1446
1447 - `output_format: :png | :webp | :jpeg`
1448
1449 The output format for the generated image.
1450
1451 - `:png`
1452
1453 - `:webp`
1454
1455 - `:jpeg`
1456
1457 - `quality: :low | :medium | :high | :auto`
1458
1459 The quality setting for the generated image.
1460
1461 - `:low`
1462
1463 - `:medium`
1464
1465 - `:high`
1466
1467 - `:auto`
1468
1469 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024" | :auto`
1470
1471 The size of the generated image.
1472
1473 - `:"1024x1024"`
1474
1475 - `:"1024x1536"`
1476
1477 - `:"1536x1024"`
1478
1479 - `:auto`
1480
1481 - `type: :"image_generation.completed"`
1482
1483 The type of the event. Always `image_generation.completed`.
1484
1485 - `:"image_generation.completed"`
1486
1487 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, total_tokens}`
1488
1489 For the GPT image models only, the token usage information for the image generation.
1490
1491 - `input_tokens: Integer`
1492
1493 The number of tokens (images and text) in the input prompt.
1494
1495 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
1496
1497 The input tokens detailed information for the image generation.
1498
1499 - `image_tokens: Integer`
1500
1501 The number of image tokens in the input prompt.
1502
1503 - `text_tokens: Integer`
1504
1505 The number of text tokens in the input prompt.
1506
1507 - `output_tokens: Integer`
1508
1509 The number of image tokens in the output image.
1510
1511 - `total_tokens: Integer`
1512
1513 The total number of tokens (images and text) used for the image generation.
1514
1515### Image Model
1516
1517- `ImageModel = :"gpt-image-1" | :"gpt-image-1-mini" | :"gpt-image-2" | 5 more`
1518
1519 - `:"gpt-image-1"`
1520
1521 - `:"gpt-image-1-mini"`
1522
1523 - `:"gpt-image-2"`
1524
1525 - `:"gpt-image-2-2026-04-21"`
1526
1527 - `:"gpt-image-1.5"`
1528
1529 - `:"chatgpt-image-latest"`
1530
1531 - `:"dall-e-2"`
1532
1533 - `:"dall-e-3"`
1534
1535### Images Response
1536
1537- `class ImagesResponse`
1538
1539 The response from the image generation endpoint.
1540
1541 - `created: Integer`
1542
1543 The Unix timestamp (in seconds) of when the image was created.
1544
1545 - `background: :transparent | :opaque`
1546
1547 The background parameter used for the image generation. Either `transparent` or `opaque`.
1548
1549 - `:transparent`
1550
1551 - `:opaque`
1552
1553 - `data: Array[Image]`
1554
1555 The list of generated images.
1556
1557 - `b64_json: String`
1558
1559 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`.
1560
1561 - `revised_prompt: String`
1562
1563 For `dall-e-3` only, the revised prompt that was used to generate the image.
1564
1565 - `url: String`
1566
1567 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.
1568
1569 - `output_format: :png | :webp | :jpeg`
1570
1571 The output format of the image generation. Either `png`, `webp`, or `jpeg`.
1572
1573 - `:png`
1574
1575 - `:webp`
1576
1577 - `:jpeg`
1578
1579 - `quality: :low | :medium | :high`
1580
1581 The quality of the image generated. Either `low`, `medium`, or `high`.
1582
1583 - `:low`
1584
1585 - `:medium`
1586
1587 - `:high`
1588
1589 - `size: :"1024x1024" | :"1024x1536" | :"1536x1024"`
1590
1591 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
1592
1593 - `:"1024x1024"`
1594
1595 - `:"1024x1536"`
1596
1597 - `:"1536x1024"`
1598
1599 - `usage: Usage{ input_tokens, input_tokens_details, output_tokens, 2 more}`
1600
1601 For `gpt-image-1` only, the token usage information for the image generation.
1602
1603 - `input_tokens: Integer`
1604
1605 The number of tokens (images and text) in the input prompt.
1606
1607 - `input_tokens_details: InputTokensDetails{ image_tokens, text_tokens}`
1608
1609 The input tokens detailed information for the image generation.
1610
1611 - `image_tokens: Integer`
1612
1613 The number of image tokens in the input prompt.
1614
1615 - `text_tokens: Integer`
1616
1617 The number of text tokens in the input prompt.
1618
1619 - `output_tokens: Integer`
1620
1621 The number of output tokens generated by the model.
1622
1623 - `total_tokens: Integer`
1624
1625 The total number of tokens (images and text) used for the image generation.
1626
1627 - `output_tokens_details: OutputTokensDetails{ image_tokens, text_tokens}`
1628
1629 The output token details for the image generation.
1630
1631 - `image_tokens: Integer`
1632
1633 The number of image output tokens generated by the model.
1634
1635 - `text_tokens: Integer`
1636
1637 The number of text output tokens generated by the model.