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