0
# Images
1

2
Generate, edit, and create variations of images using DALL-E models. Supports creating images from text prompts, editing existing images with masks, and generating variations.
3

4
## Capabilities
5

6
### Generate Images
7

8
Create images from text descriptions using DALL-E or GPT-Image-1 models.
9

10
```python { .api }
11
def generate(
12
    self,
13
    *,
14
    prompt: str,
15
    background: Literal["transparent", "opaque", "auto"] | Omit = omit,
16
    model: str | ImageModel | Omit = omit,
17
    moderation: Literal["low", "auto"] | Omit = omit,
18
    n: int | Omit = omit,
19
    output_compression: int | Omit = omit,
20
    output_format: Literal["png", "jpeg", "webp"] | Omit = omit,
21
    partial_images: int | Omit = omit,
22
    quality: Literal["standard", "hd", "low", "medium", "high", "auto"] | Omit = omit,
23
    response_format: Literal["url", "b64_json"] | Omit = omit,
24
    size: Literal["auto", "1024x1024", "1536x1024", "1024x1536", "256x256", "512x512", "1792x1024", "1024x1792"] | Omit = omit,
25
    stream: bool | Omit = omit,
26
    style: Literal["vivid", "natural"] | Omit = omit,
27
    user: str | Omit = omit,
28
    extra_headers: dict[str, str] | None = None,
29
    extra_query: dict[str, object] | None = None,
30
    extra_body: dict[str, object] | None = None,
31
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
32
) -> ImagesResponse | Stream[ImageGenStreamEvent]:
33
    """
34
    Generate images from text prompts.
35

36
    Args:
37
        prompt: Text description of the desired image(s). Max length:
38
            - gpt-image-1: 32000 characters
39
            - dall-e-3: 4000 characters
40
            - dall-e-2: 1000 characters
41

42
        background: (gpt-image-1 only) Background transparency control. Options:
43
            - "transparent": Transparent background (requires png or webp output)
44
            - "opaque": Opaque background
45
            - "auto": Model determines best option (default)
46

47
        model: Model to use. Options:
48
            - "dall-e-3": Latest DALL-E, highest quality
49
            - "dall-e-2": Previous DALL-E generation
50
            - "gpt-image-1": Latest generation model with advanced features
51
            Defaults to dall-e-2 unless gpt-image-1 specific parameters are used.
52

53
        moderation: (gpt-image-1 only) Content moderation level. Options:
54
            - "auto": Standard filtering (default)
55
            - "low": Less restrictive filtering
56

57
        n: Number of images to generate. Default 1.
58
            - gpt-image-1: Supports 1-10
59
            - dall-e-3: Only supports n=1
60
            - dall-e-2: Supports 1-10
61

62
        output_compression: (gpt-image-1 only) Compression level (0-100%) for webp or jpeg
63
            output formats. Default 100. Higher values = better quality, larger file size.
64

65
        output_format: (gpt-image-1 only) Output image format. Options:
66
            - "png": PNG format (default), supports transparency
67
            - "jpeg": JPEG format, smaller files, no transparency
68
            - "webp": WebP format, good compression with quality
69

70
        partial_images: (gpt-image-1 only) Number of partial images for streaming (0-3).
71
            Set to 0 for single final image. Default returns progressive partial images.
72
            Final image may arrive before all partials if generation completes quickly.
73

74
        quality: Image quality. Options depend on model:
75
            - gpt-image-1: "auto" (default), "high", "medium", "low"
76
            - dall-e-3: "standard" (default), "hd"
77
            - dall-e-2: Only "standard"
78

79
        response_format: Response data format. Options:
80
            - "url": Returns URL (default), expires after 1 hour (dall-e-2 and dall-e-3 only)
81
            - "b64_json": Returns base64-encoded JSON
82
            Note: gpt-image-1 always returns base64-encoded images.
83

84
        size: Image dimensions. Options depend on model:
85
            - gpt-image-1: "auto" (default), "1024x1024", "1536x1024", "1024x1536"
86
            - dall-e-3: "1024x1024", "1792x1024", "1024x1792"
87
            - dall-e-2: "256x256", "512x512", "1024x1024"
88

89
        stream: (gpt-image-1 only) If true, returns Stream[ImageGenStreamEvent] for
90
            progressive image generation. Set partial_images to control streaming behavior.
91

92
        style: Visual style. Only for dall-e-3. Options:
93
            - "vivid": Hyper-real and dramatic (default)
94
            - "natural": More natural, less hyper-real
95

96
        user: Unique end-user identifier for abuse monitoring.
97

98
        extra_headers: Additional HTTP headers.
99
        extra_query: Additional query parameters.
100
        extra_body: Additional JSON fields.
101
        timeout: Request timeout in seconds.
102

103
    Returns:
104
        ImagesResponse: Contains generated image(s) when stream=False.
105
        Stream[ImageGenStreamEvent]: Streaming events when stream=True (gpt-image-1 only).
106

107
    Raises:
108
        BadRequestError: Invalid parameters or prompt violates content policy
109
        RateLimitError: Rate limit exceeded
110
    """
111
```
112

113
Usage examples:
114

115
```python
116
from openai import OpenAI
117

118
client = OpenAI()
119

120
# Basic image generation
121
response = client.images.generate(
122
    model="dall-e-3",
123
    prompt="A cute baby sea otter wearing a beret",
124
    n=1,
125
    size="1024x1024"
126
)
127

128
image_url = response.data[0].url
129
print(f"Image URL: {image_url}")
130

131
# HD quality
132
response = client.images.generate(
133
    model="dall-e-3",
134
    prompt="A serene mountain landscape at sunset",
135
    quality="hd",
136
    size="1792x1024"
137
)
138

139
# Natural style
140
response = client.images.generate(
141
    model="dall-e-3",
142
    prompt="A portrait of a programmer at work",
143
    style="natural"
144
)
145

146
# Base64 response (no expiration)
147
response = client.images.generate(
148
    model="dall-e-3",
149
    prompt="A futuristic cityscape",
150
    response_format="b64_json"
151
)
152

153
import base64
154
from pathlib import Path
155

156
# Save base64 image
157
image_data = base64.b64decode(response.data[0].b64_json)
158
Path("generated_image.png").write_bytes(image_data)
159

160
# Download from URL
161
import requests
162

163
response = client.images.generate(
164
    model="dall-e-3",
165
    prompt="A cat playing chess"
166
)
167

168
image_url = response.data[0].url
169
image_response = requests.get(image_url)
170
Path("cat_chess.png").write_bytes(image_response.content)
171

172
# Multiple images with DALL-E 2
173
response = client.images.generate(
174
    model="dall-e-2",
175
    prompt="Abstract art with geometric shapes",
176
    n=4,
177
    size="512x512"
178
)
179

180
for i, image in enumerate(response.data):
181
    print(f"Image {i+1}: {image.url}")
182

183
# Check revised prompt (DALL-E 3 may modify prompts)
184
response = client.images.generate(
185
    model="dall-e-3",
186
    prompt="A dog"
187
)
188

189
print(f"Original prompt: A dog")
190
print(f"Revised prompt: {response.data[0].revised_prompt}")
191
```
192

193
### Edit Images
194

195
Modify an existing image using a mask and text prompt. Supports both DALL-E 2 and GPT-Image-1 models.
196

197
```python { .api }
198
def edit(
199
    self,
200
    *,
201
    image: FileTypes | list[FileTypes],
202
    prompt: str,
203
    background: Literal["transparent", "opaque", "auto"] | Omit = omit,
204
    input_fidelity: Literal["high", "low"] | Omit = omit,
205
    mask: FileTypes | Omit = omit,
206
    model: str | ImageModel | Omit = omit,
207
    n: int | Omit = omit,
208
    output_compression: int | Omit = omit,
209
    output_format: Literal["png", "jpeg", "webp"] | Omit = omit,
210
    partial_images: int | Omit = omit,
211
    quality: Literal["standard", "low", "medium", "high", "auto"] | Omit = omit,
212
    response_format: Literal["url", "b64_json"] | Omit = omit,
213
    size: Literal["256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "auto"] | Omit = omit,
214
    stream: bool | Omit = omit,
215
    user: str | Omit = omit,
216
    extra_headers: dict[str, str] | None = None,
217
    extra_query: dict[str, object] | None = None,
218
    extra_body: dict[str, object] | None = None,
219
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
220
) -> ImagesResponse | Stream[ImageEditStreamEvent]:
221
    """
222
    Edit or extend an image using a mask and prompt. Supports dall-e-2 and gpt-image-1.
223

224
    Args:
225
        image: Image(s) to edit.
226
            - dall-e-2: Single PNG image, must be square, less than 4MB
227
            - gpt-image-1: Single image or list of up to 16 images (png/webp/jpg), less than 50MB each
228
            Transparent areas indicate where to edit if no mask provided.
229

230
        prompt: Text description of desired edits.
231
            - dall-e-2: Max 1000 characters
232
            - gpt-image-1: Max 32000 characters
233

234
        background: (gpt-image-1 only) Background transparency control. Options:
235
            - "transparent": Transparent background (requires png or webp output)
236
            - "opaque": Opaque background
237
            - "auto": Model determines best option (default)
238

239
        input_fidelity: (gpt-image-1 only, not supported for gpt-image-1-mini) Control how much
240
            the model matches input image style and features, especially facial features. Options:
241
            - "low": Less strict matching (default)
242
            - "high": Stricter matching of input features
243

244
        mask: Optional mask image. Must be PNG, same dimensions as image, less than 4MB.
245
            Fully transparent areas (alpha=0) indicate where to edit. If multiple input images
246
            are provided, mask applies to the first image.
247

248
        model: Model to use. Options:
249
            - "dall-e-2": Original model, limited features
250
            - "gpt-image-1": Latest model with advanced features (default if gpt-image-1
251
              specific parameters are used)
252

253
        n: Number of variations to generate (1-10). Default 1.
254

255
        output_compression: (gpt-image-1 only) Compression level (0-100%) for webp or jpeg
256
            output formats. Default 100. Higher values = better quality, larger file size.
257

258
        output_format: (gpt-image-1 only) Output image format. Options:
259
            - "png": PNG format (default), supports transparency
260
            - "jpeg": JPEG format, smaller files, no transparency
261
            - "webp": WebP format, good compression with quality
262

263
        partial_images: (gpt-image-1 only) Number of partial images for streaming (0-3).
264
            Set to 0 for single final image. Default returns progressive partial images.
265
            Final image may arrive before all partials if generation completes quickly.
266

267
        quality: (gpt-image-1 only) Output quality level. Options:
268
            - "standard": Standard quality
269
            - "low": Lower quality, faster
270
            - "medium": Medium quality
271
            - "high": High quality, slower
272
            - "auto": Model determines best quality
273

274
        response_format: Response data format. Options:
275
            - "url": Returns URL (default), expires after 1 hour
276
            - "b64_json": Returns base64-encoded JSON
277

278
        size: Output dimensions. Options:
279
            - dall-e-2: "256x256", "512x512", "1024x1024" (default)
280
            - gpt-image-1: Same as dall-e-2 plus "1536x1024", "1024x1536", "auto"
281

282
        stream: (gpt-image-1 only) If true, returns Stream[ImageEditStreamEvent] for
283
            progressive image generation. Set partial_images to control streaming behavior.
284

285
        user: Unique end-user identifier for abuse monitoring.
286

287
        extra_headers: Additional HTTP headers.
288
        extra_query: Additional query parameters.
289
        extra_body: Additional JSON fields.
290
        timeout: Request timeout in seconds.
291

292
    Returns:
293
        ImagesResponse: Contains edited image(s) when stream=False.
294
        Stream[ImageEditStreamEvent]: Streaming events when stream=True (gpt-image-1 only).
295

296
    Raises:
297
        BadRequestError: Invalid image format, size, or prompt
298
    """
299
```
300

301
Usage examples:
302

303
```python
304
from openai import OpenAI
305
from pathlib import Path
306

307
client = OpenAI()
308

309
# Basic edit with DALL-E 2
310
with open("base_image.png", "rb") as image_file, \
311
     open("mask.png", "rb") as mask_file:
312

313
    response = client.images.edit(
314
        image=image_file,
315
        mask=mask_file,
316
        prompt="Add a red hat",
317
        model="dall-e-2",
318
        n=1,
319
        size="1024x1024"
320
    )
321

322
# Save result
323
import requests
324
image_url = response.data[0].url
325
image_data = requests.get(image_url).content
326
Path("edited_image.png").write_bytes(image_data)
327

328
# Edit with GPT-Image-1 - multiple images
329
with open("image1.png", "rb") as img1, \
330
     open("image2.png", "rb") as img2:
331

332
    response = client.images.edit(
333
        image=[img1, img2],  # Multiple images for context
334
        prompt="Blend these images together with a sunset background",
335
        model="gpt-image-1",
336
        output_format="webp",
337
        quality="high",
338
        background="auto"
339
    )
340

341
# GPT-Image-1 with high input fidelity
342
with open("portrait.png", "rb") as image_file:
343
    response = client.images.edit(
344
        image=image_file,
345
        prompt="Change the background to a beach scene, keep facial features",
346
        model="gpt-image-1",
347
        input_fidelity="high",  # Preserve facial features
348
        output_format="png",
349
        size="1536x1024"
350
    )
351

352
# GPT-Image-1 with transparent background
353
with open("object.png", "rb") as image_file:
354
    response = client.images.edit(
355
        image=image_file,
356
        prompt="Remove the background",
357
        model="gpt-image-1",
358
        background="transparent",
359
        output_format="png"  # Must use png or webp for transparency
360
    )
361

362
# Streaming edit with GPT-Image-1
363
with open("base_image.png", "rb") as image_file:
364
    stream = client.images.edit(
365
        image=image_file,
366
        prompt="Add dramatic lighting",
367
        model="gpt-image-1",
368
        stream=True,
369
        partial_images=3  # Get 3 progressive partial images
370
    )
371

372
    for event in stream:
373
        if event.type == "image":
374
            print(f"Received image chunk: {len(event.data)} bytes")
375
        elif event.type == "done":
376
            print("Final image complete")
377

378
# Compressed output for web use
379
with open("large_image.png", "rb") as image_file:
380
    response = client.images.edit(
381
        image=image_file,
382
        prompt="Enhance colors",
383
        model="gpt-image-1",
384
        output_format="webp",
385
        output_compression=85,  # 85% quality for smaller file size
386
        quality="medium"
387
    )
388

389
# Edit using transparency (no mask) - works with both models
390
with open("image_with_transparency.png", "rb") as image_file:
391
    response = client.images.edit(
392
        image=image_file,
393
        prompt="Fill transparent areas with flowers"
394
    )
395
```
396

397
### Create Variations
398

399
Generate variations of an existing image (DALL-E 2 only).
400

401
```python { .api }
402
def create_variation(
403
    self,
404
    *,
405
    image: FileTypes,
406
    model: str | ImageModel | Omit = omit,
407
    n: int | Omit = omit,
408
    response_format: Literal["url", "b64_json"] | Omit = omit,
409
    size: Literal["256x256", "512x512", "1024x1024"] | Omit = omit,
410
    user: str | Omit = omit,
411
    extra_headers: dict[str, str] | None = None,
412
    extra_query: dict[str, object] | None = None,
413
    extra_body: dict[str, object] | None = None,
414
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
415
) -> ImagesResponse:
416
    """
417
    Create variations of an existing image. Only supports dall-e-2.
418

419
    Args:
420
        image: Base image for variations. Must be valid PNG, less than 4MB, and square.
421

422
        model: Model to use. Only "dall-e-2" is supported for variations.
423

424
        n: Number of variations to generate (1-10). Default 1.
425

426
        response_format: Output format.
427
            - "url": Returns URL (default), expires after 1 hour
428
            - "b64_json": Returns base64-encoded JSON
429

430
        size: Output dimensions. Options: "256x256", "512x512", "1024x1024".
431
            Default "1024x1024".
432

433
        user: Unique end-user identifier.
434

435
        extra_headers: Additional HTTP headers.
436
        extra_query: Additional query parameters.
437
        extra_body: Additional JSON fields.
438
        timeout: Request timeout in seconds.
439

440
    Returns:
441
        ImagesResponse: Contains variation image(s).
442

443
    Raises:
444
        BadRequestError: Invalid image format or size
445
    """
446
```
447

448
Usage example:
449

450
```python
451
from openai import OpenAI
452
import requests
453
from pathlib import Path
454

455
client = OpenAI()
456

457
# Create multiple variations
458
with open("base_image.png", "rb") as image_file:
459
    response = client.images.create_variation(
460
        image=image_file,
461
        n=3,
462
        size="1024x1024"
463
    )
464

465
# Save all variations
466
for i, image in enumerate(response.data):
467
    image_data = requests.get(image.url).content
468
    Path(f"variation_{i+1}.png").write_bytes(image_data)
469

470
# Base64 format
471
with open("base_image.png", "rb") as image_file:
472
    response = client.images.create_variation(
473
        image=image_file,
474
        response_format="b64_json"
475
    )
476

477
import base64
478
image_data = base64.b64decode(response.data[0].b64_json)
479
Path("variation.png").write_bytes(image_data)
480
```
481

482
## Types
483

484
```python { .api }
485
from typing import Literal, Union
486
from pydantic import BaseModel
487

488
class ImagesResponse(BaseModel):
489
    """Response from image endpoints."""
490
    created: int
491
    data: list[Image]
492

493
class Image(BaseModel):
494
    """Single generated/edited image."""
495
    url: str | None  # Present when response_format="url"
496
    b64_json: str | None  # Present when response_format="b64_json"
497
    revised_prompt: str | None  # Only for dall-e-3 generations
498

499
class ImageEditStreamEvent(BaseModel):
500
    """Streaming event from images.edit() with stream=True (gpt-image-1 only)."""
501
    type: Literal["image", "done", "error"]
502
    data: bytes | None  # Image data for type="image"
503
    error: str | None  # Error message for type="error"
504

505
class ImageGenStreamEvent(BaseModel):
506
    """Streaming event from images.generate() with stream=True (gpt-image-1 only)."""
507
    type: Literal["image", "done", "error"]
508
    data: bytes | None  # Image data for type="image"
509
    error: str | None  # Error message for type="error"
510

511
# Model types
512
ImageModel = Literal["dall-e-2", "dall-e-3", "gpt-image-1", "gpt-image-1-mini"]
513

514
# File types
515
FileTypes = Union[
516
    FileContent,  # File-like object
517
    tuple[str | None, FileContent],  # (filename, content)
518
    tuple[str | None, FileContent, str | None]  # (filename, content, content_type)
519
]
520
```
521

522
## Model Comparison
523

524
| Feature | DALL-E 3 | GPT-Image-1 | DALL-E 2 |
525
|---------|----------|-------------|----------|
526
| Generation Quality | Highest | Very High | Good |
527
| Max Prompt Length (generate) | 4000 chars | N/A | 1000 chars |
528
| Max Prompt Length (edit) | N/A | 32000 chars | 1000 chars |
529
| Images per Request (generate) | 1 only | N/A | 1-10 |
530
| Images per Request (edit) | N/A | Up to 16 input | 1 input |
531
| Generation Sizes | 1024x1024, 1792x1024, 1024x1792 | N/A | 256x256, 512x512, 1024x1024 |
532
| Edit Sizes | N/A | 256x256-1536x1024, auto | 256x256-1024x1024 |
533
| Quality Options | standard, hd | standard, low, medium, high, auto | N/A |
534
| Style Options | vivid, natural | N/A | N/A |
535
| Prompt Revision | Yes | N/A | No |
536
| Image Generation | Yes | No | Yes |
537
| Image Editing | No | Yes | Yes |
538
| Variations | No | No | Yes |
539
| Multiple Input Images | N/A | Yes (up to 16) | No |
540
| Output Formats | png | png, jpeg, webp | png |
541
| Transparency Control | N/A | Yes | Limited |
542
| Input Fidelity Control | N/A | Yes | No |
543
| Streaming Support | No | Yes | No |
544
| Compression Control | No | Yes | No |
545
546
## Best Practices
547

548
```python
549
from openai import OpenAI
550

551
client = OpenAI()
552

553
# 1. Use detailed, specific prompts
554
response = client.images.generate(
555
    model="dall-e-3",
556
    prompt="A photorealistic portrait of a golden retriever wearing "
557
           "aviator sunglasses, sitting in a red vintage convertible, "
558
           "with a sunny beach in the background, shot on 35mm film"
559
)
560

561
# 2. Check revised prompts (DALL-E 3)
562
response = client.images.generate(
563
    model="dall-e-3",
564
    prompt="A dog"
565
)
566
print(f"Revised: {response.data[0].revised_prompt}")
567

568
# 3. Use appropriate quality for use case
569
# Standard for drafts/iterations
570
response = client.images.generate(
571
    model="dall-e-3",
572
    prompt="Concept art",
573
    quality="standard"
574
)
575

576
# HD for final production
577
response = client.images.generate(
578
    model="dall-e-3",
579
    prompt="Final poster design",
580
    quality="hd"
581
)
582

583
# 4. Handle errors gracefully
584
from openai import BadRequestError
585

586
try:
587
    response = client.images.generate(
588
        prompt="inappropriate content"
589
    )
590
except BadRequestError as e:
591
    if "content_policy_violation" in str(e):
592
        print("Prompt violated content policy")
593
    else:
594
        print(f"Error: {e}")
595
```
596

597
## Async Usage
598

599
```python
600
import asyncio
601
from openai import AsyncOpenAI
602

603
async def generate_image():
604
    client = AsyncOpenAI()
605

606
    response = await client.images.generate(
607
        model="dall-e-3",
608
        prompt="A futuristic robot",
609
        size="1024x1024"
610
    )
611

612
    return response.data[0].url
613

614
# Run async
615
image_url = asyncio.run(generate_image())
616
```
617