resources/images/methods/edit/index.md +0 −342 deleted
File Deleted View Diff
1## Create image edit
2
3**post** `/images/edits`
4
5Creates 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`.
6
7### Body Parameters
8
9- `images: array of object { file_id, image_url }`
10
11 Input image references to edit.
12 For GPT image models, you can provide up to 16 images.
13
14 - `file_id: optional string`
15
16 The File API ID of an uploaded image to use as input.
17
18 - `image_url: optional string`
19
20 A fully qualified URL or base64-encoded data URL.
21
22- `prompt: string`
23
24 A text description of the desired image edit.
25
26- `background: optional "transparent" or "opaque" or "auto"`
27
28 Background behavior for generated image output.
29
30 - `"transparent"`
31
32 - `"opaque"`
33
34 - `"auto"`
35
36- `input_fidelity: optional "high" or "low"`
37
38 Controls fidelity to the original input image(s).
39
40 - `"high"`
41
42 - `"low"`
43
44- `mask: optional object { file_id, image_url }`
45
46 Reference an input image by either URL or uploaded file ID.
47 Provide exactly one of `image_url` or `file_id`.
48
49 - `file_id: optional string`
50
51 The File API ID of an uploaded image to use as input.
52
53 - `image_url: optional string`
54
55 A fully qualified URL or base64-encoded data URL.
56
57- `model: optional string or "gpt-image-1.5" or "gpt-image-1" or "gpt-image-1-mini" or "chatgpt-image-latest"`
58
59 The model to use for image editing.
60
61 - `string`
62
63 - `"gpt-image-1.5" or "gpt-image-1" or "gpt-image-1-mini" or "chatgpt-image-latest"`
64
65 The model to use for image editing.
66
67 - `"gpt-image-1.5"`
68
69 - `"gpt-image-1"`
70
71 - `"gpt-image-1-mini"`
72
73 - `"chatgpt-image-latest"`
74
75- `moderation: optional "low" or "auto"`
76
77 Moderation level for GPT image models.
78
79 - `"low"`
80
81 - `"auto"`
82
83- `n: optional number`
84
85 The number of edited images to generate.
86
87- `output_compression: optional number`
88
89 Compression level for `jpeg` or `webp` output.
90
91- `output_format: optional "png" or "jpeg" or "webp"`
92
93 Output image format. Supported for GPT image models.
94
95 - `"png"`
96
97 - `"jpeg"`
98
99 - `"webp"`
100
101- `partial_images: optional number`
102
103 The number of partial images to generate. This parameter is used for
104 streaming responses that return partial images. Value must be between 0 and 3.
105 When set to 0, the response will be a single image sent in one streaming event.
106
107 Note that the final image may be sent before the full number of partial images
108 are generated if the full image is generated more quickly.
109
110- `quality: optional "low" or "medium" or "high" or "auto"`
111
112 Output quality for GPT image models.
113
114 - `"low"`
115
116 - `"medium"`
117
118 - `"high"`
119
120 - `"auto"`
121
122- `size: optional "auto" or "1024x1024" or "1536x1024" or "1024x1536"`
123
124 Requested output image size.
125
126 - `"auto"`
127
128 - `"1024x1024"`
129
130 - `"1536x1024"`
131
132 - `"1024x1536"`
133
134- `stream: optional boolean`
135
136 Stream partial image results as events.
137
138- `user: optional string`
139
140 A unique identifier representing your end-user, which can help OpenAI
141 monitor and detect abuse.
142
143### Returns
144
145- `ImagesResponse object { created, background, data, 4 more }`
146
147 The response from the image generation endpoint.
148
149 - `created: number`
150
151 The Unix timestamp (in seconds) of when the image was created.
152
153 - `background: optional "transparent" or "opaque"`
154
155 The background parameter used for the image generation. Either `transparent` or `opaque`.
156
157 - `"transparent"`
158
159 - `"opaque"`
160
161 - `data: optional array of Image`
162
163 The list of generated images.
164
165 - `b64_json: optional string`
166
167 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`.
168
169 - `revised_prompt: optional string`
170
171 For `dall-e-3` only, the revised prompt that was used to generate the image.
172
173 - `url: optional string`
174
175 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.
176
177 - `output_format: optional "png" or "webp" or "jpeg"`
178
179 The output format of the image generation. Either `png`, `webp`, or `jpeg`.
180
181 - `"png"`
182
183 - `"webp"`
184
185 - `"jpeg"`
186
187 - `quality: optional "low" or "medium" or "high"`
188
189 The quality of the image generated. Either `low`, `medium`, or `high`.
190
191 - `"low"`
192
193 - `"medium"`
194
195 - `"high"`
196
197 - `size: optional "1024x1024" or "1024x1536" or "1536x1024"`
198
199 The size of the image generated. Either `1024x1024`, `1024x1536`, or `1536x1024`.
200
201 - `"1024x1024"`
202
203 - `"1024x1536"`
204
205 - `"1536x1024"`
206
207 - `usage: optional object { input_tokens, input_tokens_details, output_tokens, 2 more }`
208
209 For `gpt-image-1` only, the token usage information for the image generation.
210
211 - `input_tokens: number`
212
213 The number of tokens (images and text) in the input prompt.
214
215 - `input_tokens_details: object { image_tokens, text_tokens }`
216
217 The input tokens detailed information for the image generation.
218
219 - `image_tokens: number`
220
221 The number of image tokens in the input prompt.
222
223 - `text_tokens: number`
224
225 The number of text tokens in the input prompt.
226
227 - `output_tokens: number`
228
229 The number of output tokens generated by the model.
230
231 - `total_tokens: number`
232
233 The total number of tokens (images and text) used for the image generation.
234
235 - `output_tokens_details: optional object { image_tokens, text_tokens }`
236
237 The output token details for the image generation.
238
239 - `image_tokens: number`
240
241 The number of image output tokens generated by the model.
242
243 - `text_tokens: number`
244
245 The number of text output tokens generated by the model.
246
247### Example
248
249```http
250curl https://api.openai.com/v1/images/edits \
251 -H 'Content-Type: application/json' \
252 -H "Authorization: Bearer $OPENAI_API_KEY" \
253 -d '{
254 "images": [
255 {
256 "image_url": "https://example.com/source-image.png"
257 }
258 ],
259 "prompt": "Add a watercolor effect to this image",
260 "background": "transparent",
261 "model": "gpt-image-1.5",
262 "moderation": "auto",
263 "n": 1,
264 "output_compression": 100,
265 "output_format": "png",
266 "partial_images": 1,
267 "quality": "high",
268 "size": "1024x1024",
269 "user": "user-1234"
270 }'
271```
272
273#### Response
274
275```json
276{
277 "created": 0,
278 "background": "transparent",
279 "data": [
280 {
281 "b64_json": "b64_json",
282 "revised_prompt": "revised_prompt",
283 "url": "https://example.com"
284 }
285 ],
286 "output_format": "png",
287 "quality": "low",
288 "size": "1024x1024",
289 "usage": {
290 "input_tokens": 0,
291 "input_tokens_details": {
292 "image_tokens": 0,
293 "text_tokens": 0
294 },
295 "output_tokens": 0,
296 "total_tokens": 0,
297 "output_tokens_details": {
298 "image_tokens": 0,
299 "text_tokens": 0
300 }
301 }
302}
303```
304
305### Edit image
306
307```http
308curl -s -D >(grep -i x-request-id >&2) \
309 -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
310 -X POST "https://api.openai.com/v1/images/edits" \
311 -H "Authorization: Bearer $OPENAI_API_KEY" \
312 -F "model=gpt-image-1.5" \
313 -F "image[]=@body-lotion.png" \
314 -F "image[]=@bath-bomb.png" \
315 -F "image[]=@incense-kit.png" \
316 -F "image[]=@soap.png" \
317 -F 'prompt=Create a lovely gift basket with these four items in it'
318```
319
320### Streaming
321
322```http
323curl -s -N -X POST "https://api.openai.com/v1/images/edits" \
324 -H "Authorization: Bearer $OPENAI_API_KEY" \
325 -F "model=gpt-image-1.5" \
326 -F "image[]=@body-lotion.png" \
327 -F "image[]=@bath-bomb.png" \
328 -F "image[]=@incense-kit.png" \
329 -F "image[]=@soap.png" \
330 -F 'prompt=Create a lovely gift basket with these four items in it' \
331 -F "stream=true"
332```
333
334#### Response
335
336```json
337event: image_edit.partial_image
338data: {"type":"image_edit.partial_image","b64_json":"...","partial_image_index":0}
339
340event: image_edit.completed
341data: {"type":"image_edit.completed","b64_json":"...","usage":{"total_tokens":100,"input_tokens":50,"output_tokens":50,"input_tokens_details":{"text_tokens":10,"image_tokens":40}}}
342```