python/resources/images/methods/create_variation/index.md +0 −243 deleted
File Deleted View Diff
1## Create image variation
2
3`images.create_variation(ImageCreateVariationParams**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: FileTypes`
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: Optional[Union[str, ImageModel, null]]`
16
17 The model to use for image generation. Only `dall-e-2` is supported at this time.
18
19 - `str`
20
21 - `Literal["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: Optional[int]`
40
41 The number of images to generate. Must be between 1 and 10.
42
43- `response_format: Optional[Literal["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: Optional[Literal["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: Optional[str]`
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: int`
72
73 The Unix timestamp (in seconds) of when the image was created.
74
75 - `background: Optional[Literal["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: Optional[List[Image]]`
84
85 The list of generated images.
86
87 - `b64_json: Optional[str]`
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: Optional[str]`
92
93 For `dall-e-3` only, the revised prompt that was used to generate the image.
94
95 - `url: Optional[str]`
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: Optional[Literal["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: Optional[Literal["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: Optional[Literal["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: Optional[Usage]`
130
131 For `gpt-image-1` only, the token usage information for the image generation.
132
133 - `input_tokens: int`
134
135 The number of tokens (images and text) in the input prompt.
136
137 - `input_tokens_details: UsageInputTokensDetails`
138
139 The input tokens detailed information for the image generation.
140
141 - `image_tokens: int`
142
143 The number of image tokens in the input prompt.
144
145 - `text_tokens: int`
146
147 The number of text tokens in the input prompt.
148
149 - `output_tokens: int`
150
151 The number of output tokens generated by the model.
152
153 - `total_tokens: int`
154
155 The total number of tokens (images and text) used for the image generation.
156
157 - `output_tokens_details: Optional[UsageOutputTokensDetails]`
158
159 The output token details for the image generation.
160
161 - `image_tokens: int`
162
163 The number of image output tokens generated by the model.
164
165 - `text_tokens: int`
166
167 The number of text output tokens generated by the model.
168
169### Example
170
171```python
172import os
173from openai import OpenAI
174
175client = OpenAI(
176 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
177)
178images_response = client.images.create_variation(
179 image=b"Example data",
180)
181print(images_response.created)
182```
183
184#### Response
185
186```json
187{
188 "created": 0,
189 "background": "transparent",
190 "data": [
191 {
192 "b64_json": "b64_json",
193 "revised_prompt": "revised_prompt",
194 "url": "https://example.com"
195 }
196 ],
197 "output_format": "png",
198 "quality": "low",
199 "size": "1024x1024",
200 "usage": {
201 "input_tokens": 0,
202 "input_tokens_details": {
203 "image_tokens": 0,
204 "text_tokens": 0
205 },
206 "output_tokens": 0,
207 "total_tokens": 0,
208 "output_tokens_details": {
209 "image_tokens": 0,
210 "text_tokens": 0
211 }
212 }
213}
214```
215
216### Example
217
218```python
219from openai import OpenAI
220client = OpenAI()
221
222response = client.images.create_variation(
223 image=open("image_edit_original.png", "rb"),
224 n=2,
225 size="1024x1024"
226)
227```
228
229#### Response
230
231```json
232{
233 "created": 1589478378,
234 "data": [
235 {
236 "url": "https://..."
237 },
238 {
239 "url": "https://..."
240 }
241 ]
242}
243```