0
# Image Generation and Editing
1

2
Comprehensive guide to OpenAI's image generation and editing capabilities including text-to-image generation, image editing with masks, creating variations, and streaming support.
3

4
## Capabilities
5

6
The Images resource provides three core methods for working with images:
7

8
### Generate - Text-to-Image Generation
9

10
Creates images from text descriptions using state-of-the-art models. Supports both standard and streaming modes.
11

12
```typescript { .api }
13
/**
14
 * Creates an image given a prompt
15
 * @param params - Generation parameters including model, prompt, size, quality
16
 * @returns Image response with generated images or stream of partial images
17
 */
18
generate(
19
  params: ImageGenerateParams
20
): Promise<ImagesResponse> | Promise<Stream<ImageGenStreamEvent>>;
21
```
22

23
[Generation Examples](#text-to-image-generation)
24

25
### Edit - Image Editing with Masks
26

27
Edits or extends images given a source image and prompt description. Supports mask-based editing to specify regions for modification.
28

29
```typescript { .api }
30
/**
31
 * Creates an edited or extended image given source images and a prompt
32
 * @param params - Edit parameters including image, prompt, mask, model
33
 * @returns Image response with edited images or stream of partial images
34
 */
35
edit(
36
  params: ImageEditParams
37
): Promise<ImagesResponse> | Promise<Stream<ImageEditStreamEvent>>;
38
```
39

40
[Editing Examples](#image-editing-with-masks)
41

42
### Create Variation - Image Variations
43

44
Creates variations of an existing image. Only supported for `dall-e-2`.
45

46
```typescript { .api }
47
/**
48
 * Creates variations of a given image
49
 * @param params - Variation parameters including image and model
50
 * @returns Image response with variation images
51
 */
52
createVariation(
53
  params: ImageCreateVariationParams
54
): Promise<ImagesResponse>;
55
```
56

57
[Variation Examples](#creating-image-variations)
58

59
---
60

61
## Core Types { .api }
62

63
### Image { .api }
64

65
Represents a generated or edited image object in the response.
66

67
```typescript { .api }
68
interface Image {
69
  /** Base64-encoded JSON of the generated image (for b64_json response format) */
70
  b64_json?: string;
71

72
  /** URL of the generated image (for dall-e-2 and dall-e-3 with url response format) */
73
  url?: string;
74

75
  /** For dall-e-3 only: the revised prompt used to generate the image */
76
  revised_prompt?: string;
77
}
78
```
79

80
### ImagesResponse { .api }
81

82
The response object containing generated or edited images and metadata.
83

84
```typescript { .api }
85
interface ImagesResponse {
86
  /** Unix timestamp (in seconds) when the image was created */
87
  created: number;
88

89
  /** Array of generated Image objects */
90
  data?: Array<Image>;
91

92
  /** Background setting: 'transparent' or 'opaque' (gpt-image-1 only) */
93
  background?: 'transparent' | 'opaque';
94

95
  /** Output format of images: 'png', 'webp', or 'jpeg' */
96
  output_format?: 'png' | 'webp' | 'jpeg';
97

98
  /** Quality of generated images: 'low', 'medium', or 'high' */
99
  quality?: 'low' | 'medium' | 'high';
100

101
  /** Size of generated images: '1024x1024', '1024x1536', or '1536x1024' */
102
  size?: '1024x1024' | '1024x1536' | '1536x1024';
103

104
  /** Token usage information (gpt-image-1 only) */
105
  usage?: ImagesResponse.Usage;
106
}
107

108
namespace ImagesResponse {
109
  interface Usage {
110
    /** Number of tokens in the input prompt */
111
    input_tokens: number;
112

113
    /** Detailed input token breakdown */
114
    input_tokens_details: {
115
      /** Number of image tokens in input */
116
      image_tokens: number;
117
      /** Number of text tokens in input */
118
      text_tokens: number;
119
    };
120

121
    /** Number of tokens in the output image */
122
    output_tokens: number;
123

124
    /** Total tokens used */
125
    total_tokens: number;
126
  }
127
}
128
```
129

130
### ImageModel { .api }
131

132
Supported image generation models.
133

134
```typescript { .api }
135
type ImageModel = 'dall-e-2' | 'dall-e-3' | 'gpt-image-1' | 'gpt-image-1-mini';
136
```
137

138
---
139

140
## Streaming Event Types { .api }
141

142
Streaming is supported for `generate()` and `edit()` methods for `gpt-image-1`. Events are emitted as partial images are generated and when generation completes.
143

144
### ImageGenStreamEvent { .api }
145

146
Union of all streaming events for image generation.
147

148
```typescript { .api }
149
type ImageGenStreamEvent = ImageGenPartialImageEvent | ImageGenCompletedEvent;
150
```
151

152
### ImageGenPartialImageEvent { .api }
153

154
Emitted when a partial image is available during generation streaming.
155

156
```typescript { .api }
157
interface ImageGenPartialImageEvent {
158
  /** Type of event: always 'image_generation.partial_image' */
159
  type: 'image_generation.partial_image';
160

161
  /** Base64-encoded partial image data */
162
  b64_json: string;
163

164
  /** 0-based index for the partial image in the sequence */
165
  partial_image_index: number;
166

167
  /** Size of the image: '1024x1024', '1024x1536', or '1536x1024' */
168
  size: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
169

170
  /** Quality setting: 'low', 'medium', 'high', or 'auto' */
171
  quality: 'low' | 'medium' | 'high' | 'auto';
172

173
  /** Output format: 'png', 'webp', or 'jpeg' */
174
  output_format: 'png' | 'webp' | 'jpeg';
175

176
  /** Background setting: 'transparent', 'opaque', or 'auto' */
177
  background: 'transparent' | 'opaque' | 'auto';
178

179
  /** Unix timestamp when the event was created */
180
  created_at: number;
181
}
182
```
183

184
### ImageGenCompletedEvent { .api }
185

186
Emitted when image generation completes and the final image is available.
187

188
```typescript { .api }
189
interface ImageGenCompletedEvent {
190
  /** Type of event: always 'image_generation.completed' */
191
  type: 'image_generation.completed';
192

193
  /** Base64-encoded final image data */
194
  b64_json: string;
195

196
  /** Size of the image */
197
  size: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
198

199
  /** Quality setting */
200
  quality: 'low' | 'medium' | 'high' | 'auto';
201

202
  /** Output format */
203
  output_format: 'png' | 'webp' | 'jpeg';
204

205
  /** Background setting */
206
  background: 'transparent' | 'opaque' | 'auto';
207

208
  /** Unix timestamp when the event was created */
209
  created_at: number;
210

211
  /** Token usage information (gpt-image-1 only) */
212
  usage: {
213
    input_tokens: number;
214
    input_tokens_details: {
215
      image_tokens: number;
216
      text_tokens: number;
217
    };
218
    output_tokens: number;
219
    total_tokens: number;
220
  };
221
}
222
```
223

224
### ImageEditStreamEvent { .api }
225

226
Union of all streaming events for image editing.
227

228
```typescript { .api }
229
type ImageEditStreamEvent = ImageEditPartialImageEvent | ImageEditCompletedEvent;
230
```
231

232
### ImageEditPartialImageEvent { .api }
233

234
Emitted when a partial image is available during editing streaming.
235

236
```typescript { .api }
237
interface ImageEditPartialImageEvent {
238
  /** Type of event: always 'image_edit.partial_image' */
239
  type: 'image_edit.partial_image';
240

241
  /** Base64-encoded partial edited image data */
242
  b64_json: string;
243

244
  /** 0-based index for the partial image in the sequence */
245
  partial_image_index: number;
246

247
  /** Size of the edited image */
248
  size: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
249

250
  /** Quality setting */
251
  quality: 'low' | 'medium' | 'high' | 'auto';
252

253
  /** Output format */
254
  output_format: 'png' | 'webp' | 'jpeg';
255

256
  /** Background setting */
257
  background: 'transparent' | 'opaque' | 'auto';
258

259
  /** Unix timestamp when the event was created */
260
  created_at: number;
261
}
262
```
263

264
### ImageEditCompletedEvent { .api }
265

266
Emitted when image editing completes and the final image is available.
267

268
```typescript { .api }
269
interface ImageEditCompletedEvent {
270
  /** Type of event: always 'image_edit.completed' */
271
  type: 'image_edit.completed';
272

273
  /** Base64-encoded final edited image data */
274
  b64_json: string;
275

276
  /** Size of the edited image */
277
  size: '1024x1024' | '1024x1536' | '1536x1024' | 'auto';
278

279
  /** Quality setting */
280
  quality: 'low' | 'medium' | 'high' | 'auto';
281

282
  /** Output format */
283
  output_format: 'png' | 'webp' | 'jpeg';
284

285
  /** Background setting */
286
  background: 'transparent' | 'opaque' | 'auto';
287

288
  /** Unix timestamp when the event was created */
289
  created_at: number;
290

291
  /** Token usage information (gpt-image-1 only) */
292
  usage: {
293
    input_tokens: number;
294
    input_tokens_details: {
295
      image_tokens: number;
296
      text_tokens: number;
297
    };
298
    output_tokens: number;
299
    total_tokens: number;
300
  };
301
}
302
```
303

304
---
305

306
## Parameter Types { .api }
307

308
### ImageGenerateParams { .api }
309

310
Parameters for the `generate()` method.
311

312
```typescript { .api }
313
interface ImageGenerateParams {
314
  /** Text description of desired image(s). Max 32000 chars for gpt-image-1, 1000 for dall-e-2, 4000 for dall-e-3 */
315
  prompt: string;
316

317
  /** Model to use: 'dall-e-2', 'dall-e-3', or 'gpt-image-1' (default: 'dall-e-2') */
318
  model?: (string & {}) | ImageModel | null;
319

320
  /** Number of images to generate (1-10, default: 1). Note: dall-e-3 only supports n=1 */
321
  n?: number | null;
322

323
  /** Image size. For gpt-image-1: '1024x1024', '1536x1024', '1024x1536', or 'auto' */
324
  size?: 'auto' | '1024x1024' | '1536x1024' | '1024x1536' | '256x256' | '512x512' | '1792x1024' | '1024x1792' | null;
325

326
  /** Quality level: 'auto', 'standard' (dall-e-2/3), 'hd' (dall-e-3), 'high'/'medium'/'low' (gpt-image-1) */
327
  quality?: 'standard' | 'hd' | 'low' | 'medium' | 'high' | 'auto' | null;
328

329
  /** Response format: 'url' or 'b64_json' (default: 'url' for dall-e-2/3; b64 for gpt-image-1) */
330
  response_format?: 'url' | 'b64_json' | null;
331

332
  /** Style (dall-e-3 only): 'vivid' or 'natural' */
333
  style?: 'vivid' | 'natural' | null;
334

335
  /** Background setting (gpt-image-1 only): 'transparent', 'opaque', or 'auto' (default) */
336
  background?: 'transparent' | 'opaque' | 'auto' | null;
337

338
  /** Moderation level for gpt-image-1: 'low' or 'auto' (default) */
339
  moderation?: 'low' | 'auto' | null;
340

341
  /** Enable streaming mode (gpt-image-1 only, default: false) */
342
  stream?: boolean | null;
343

344
  /** Number of partial images to generate in streaming (0-3, default: 1) */
345
  partial_images?: number | null;
346

347
  /** Output compression level 0-100% (gpt-image-1 with webp/jpeg only, default: 100) */
348
  output_compression?: number | null;
349

350
  /** Output format (gpt-image-1 only): 'png', 'jpeg', or 'webp' */
351
  output_format?: 'png' | 'jpeg' | 'webp' | null;
352

353
  /** End-user identifier for monitoring abuse */
354
  user?: string;
355
}
356
```
357

358
### ImageEditParams { .api }
359

360
Parameters for the `edit()` method.
361

362
```typescript { .api }
363
interface ImageEditParams {
364
  /** Source image(s) to edit. For gpt-image-1: png/webp/jpg up to 50MB each, max 16 images */
365
  image: Uploadable | Array<Uploadable>;
366

367
  /** Text description of desired edits. Max 1000 chars for dall-e-2, 32000 for gpt-image-1 */
368
  prompt: string;
369

370
  /** Optional mask image with transparent areas (PNG, same dimensions as image) */
371
  mask?: Uploadable;
372

373
  /** Model to use: 'dall-e-2', 'gpt-image-1' (default: 'dall-e-2') */
374
  model?: (string & {}) | ImageModel | null;
375

376
  /** Number of images to generate (1-10, default: 1) */
377
  n?: number | null;
378

379
  /** Image size. For gpt-image-1: '1024x1024', '1536x1024', '1024x1536', or 'auto' */
380
  size?: '256x256' | '512x512' | '1024x1024' | '1536x1024' | '1024x1536' | 'auto' | null;
381

382
  /** Quality level: 'standard', 'low', 'medium', 'high' (gpt-image-1), 'auto' */
383
  quality?: 'standard' | 'low' | 'medium' | 'high' | 'auto' | null;
384

385
  /** Response format: 'url' or 'b64_json' (dall-e-2 only) */
386
  response_format?: 'url' | 'b64_json' | null;
387

388
  /** Background setting (gpt-image-1 only): 'transparent', 'opaque', or 'auto' */
389
  background?: 'transparent' | 'opaque' | 'auto' | null;
390

391
  /** Input fidelity control (gpt-image-1 only): 'high' or 'low' (default). Unsupported for gpt-image-1-mini */
392
  input_fidelity?: 'high' | 'low' | null;
393

394
  /** Enable streaming mode (default: false) */
395
  stream?: boolean | null;
396

397
  /** Number of partial images to generate in streaming (0-3) */
398
  partial_images?: number | null;
399

400
  /** Output compression level 0-100% (gpt-image-1 with webp/jpeg, default: 100) */
401
  output_compression?: number | null;
402

403
  /** Output format (gpt-image-1 only): 'png', 'jpeg', or 'webp' */
404
  output_format?: 'png' | 'jpeg' | 'webp' | null;
405

406
  /** End-user identifier for monitoring abuse */
407
  user?: string;
408
}
409
```
410

411
### ImageCreateVariationParams { .api }
412

413
Parameters for the `createVariation()` method.
414

415
```typescript { .api }
416
interface ImageCreateVariationParams {
417
  /** Source image to create variations from. Must be square PNG < 4MB (dall-e-2 only) */
418
  image: Uploadable;
419

420
  /** Model to use: 'dall-e-2' only (default: 'dall-e-2') */
421
  model?: (string & {}) | ImageModel | null;
422

423
  /** Number of variations to generate (1-10, default: 1) */
424
  n?: number | null;
425

426
  /** Image size: '256x256', '512x512', or '1024x1024' (default: '1024x1024') */
427
  size?: '256x256' | '512x512' | '1024x1024' | null;
428

429
  /** Response format: 'url' or 'b64_json' (default: 'url') */
430
  response_format?: 'url' | 'b64_json' | null;
431

432
  /** End-user identifier for monitoring abuse */
433
  user?: string;
434
}
435
```
436

437
---
438

439
## Examples
440

441
### Text-to-Image Generation
442

443
#### Basic Generation with dall-e-3
444

445
Generate a single image with dall-e-3 using vivid style.
446

447
```typescript
448
import OpenAI from 'openai';
449
import fs from 'fs';
450

451
const client = new OpenAI();
452

453
async function generateImageDallE3() {
454
  const response = await client.images.generate({
455
    model: 'dall-e-3',
456
    prompt: 'A futuristic cityscape at sunset with flying vehicles, neon lights, and detailed architecture',
457
    n: 1,
458
    size: '1024x1024',
459
    quality: 'hd',
460
    style: 'vivid',
461
    response_format: 'b64_json'
462
  });
463

464
  // Save the base64 image
465
  if (response.data[0].b64_json) {
466
    const imageBuffer = Buffer.from(response.data[0].b64_json, 'base64');
467
    fs.writeFileSync('generated_image.png', imageBuffer);
468
    console.log('Image saved as generated_image.png');
469
  }
470

471
  // Display revised prompt (dall-e-3 automatically refines prompts)
472
  console.log('Revised prompt:', response.data[0].revised_prompt);
473
  console.log('Created at:', new Date(response.created * 1000).toISOString());
474
}
475

476
generateImageDallE3().catch(console.error);
477
```
478

479
#### Multiple Images with gpt-image-1
480

481
Generate multiple variations with gpt-image-1.
482

483
```typescript
484
import OpenAI from 'openai';
485
import fs from 'fs';
486

487
const client = new OpenAI();
488

489
async function generateMultipleImages() {
490
  const response = await client.images.generate({
491
    model: 'gpt-image-1',
492
    prompt: 'A serene beach scene with crystal clear water, white sand, and tropical islands',
493
    n: 4,
494
    size: '1024x1024',
495
    quality: 'high',
496
    response_format: 'b64_json'
497
  });
498

499
  response.data.forEach((image, index) => {
500
    if (image.b64_json) {
501
      const buffer = Buffer.from(image.b64_json, 'base64');
502
      fs.writeFileSync(`beach_${index + 1}.png`, buffer);
503
    }
504
  });
505

506
  console.log(`Generated ${response.data.length} images`);
507
  console.log('Token usage:', response.usage);
508
}
509

510
generateMultipleImages().catch(console.error);
511
```
512

513
#### Image Generation with URL Response
514

515
Generate images and receive URLs instead of base64.
516

517
```typescript
518
import OpenAI from 'openai';
519

520
const client = new OpenAI();
521

522
async function generateWithUrls() {
523
  const response = await client.images.generate({
524
    model: 'dall-e-2',
525
    prompt: 'A majestic mountain landscape with snow peaks, alpine meadows, and clear blue sky',
526
    n: 2,
527
    size: '1024x1024',
528
    quality: 'standard',
529
    response_format: 'url' // URLs expire after 60 minutes
530
  });
531

532
  response.data.forEach((image, index) => {
533
    console.log(`Image ${index + 1} URL: ${image.url}`);
534
  });
535

536
  // Note: Store URLs immediately as they expire in 60 minutes
537
  return response.data.map(img => img.url);
538
}
539

540
generateWithUrls().catch(console.error);
541
```
542

543
### Streaming Generation
544

545
#### Streaming Text-to-Image with gpt-image-1
546

547
Stream partial images as they're generated for progressive rendering.
548

549
```typescript
550
import OpenAI from 'openai';
551
import fs from 'fs';
552

553
const client = new OpenAI();
554

555
async function streamImageGeneration() {
556
  console.log('Starting image generation stream...');
557

558
  const stream = await client.images.generate({
559
    model: 'gpt-image-1',
560
    prompt: 'An intricate steampunk airship flying over clouds with brass gears and mechanical wings',
561
    n: 1,
562
    size: '1024x1024',
563
    quality: 'high',
564
    stream: true,
565
    partial_images: 2 // Request 2 partial images before final
566
  });
567

568
  let partialCount = 0;
569
  let finalImage: string | undefined;
570

571
  for await (const event of stream) {
572
    if (event.type === 'image_generation.partial_image') {
573
      partialCount++;
574
      console.log(`Received partial image ${event.partial_image_index + 1}/${partialCount}`);
575
      console.log(`  Size: ${event.size}`);
576
      console.log(`  Quality: ${event.quality}`);
577
      console.log(`  Format: ${event.output_format}`);
578
      // In a real app, you might render this progressively
579
    } else if (event.type === 'image_generation.completed') {
580
      console.log('Image generation completed!');
581
      console.log(`  Final size: ${event.size}`);
582
      console.log(`  Token usage: ${event.usage.total_tokens} total`);
583
      finalImage = event.b64_json;
584

585
      // Save final image
586
      if (finalImage) {
587
        const buffer = Buffer.from(finalImage, 'base64');
588
        fs.writeFileSync('streamed_image.png', buffer);
589
        console.log('Final image saved as streamed_image.png');
590
      }
591
    }
592
  }
593
}
594

595
streamImageGeneration().catch(console.error);
596
```
597

598
### Image Editing with Masks
599

600
#### Basic Image Editing
601

602
Edit an image by providing a prompt and source image.
603

604
```typescript
605
import OpenAI from 'openai';
606
import fs from 'fs';
607

608
const client = new OpenAI();
609

610
async function editImage() {
611
  // Read source image
612
  const imageData = fs.readFileSync('original_image.png');
613

614
  const response = await client.images.edit({
615
    image: imageData,
616
    prompt: 'Replace the background with a vibrant sunset over mountains',
617
    model: 'gpt-image-1',
618
    n: 1,
619
    size: '1024x1024',
620
    quality: 'high',
621
    response_format: 'b64_json'
622
  });
623

624
  if (response.data[0].b64_json) {
625
    const buffer = Buffer.from(response.data[0].b64_json, 'base64');
626
    fs.writeFileSync('edited_image.png', buffer);
627
    console.log('Edited image saved');
628
  }
629
}
630

631
editImage().catch(console.error);
632
```
633

634
#### Image Editing with Mask
635

636
Use a mask to specify exactly which regions should be edited.
637

638
```typescript
639
import OpenAI from 'openai';
640
import fs from 'fs';
641

642
const client = new OpenAI();
643

644
async function editImageWithMask() {
645
  // Read source image and mask
646
  const imageData = fs.readFileSync('photo.png');
647
  const maskData = fs.readFileSync('mask.png');
648

649
  const response = await client.images.edit({
650
    image: imageData,
651
    mask: maskData, // Transparent areas indicate where to edit
652
    prompt: 'Add a realistic bird flying in the edited region with wings spread',
653
    model: 'gpt-image-1',
654
    n: 1,
655
    size: '1024x1024',
656
    quality: 'high',
657
    input_fidelity: 'high', // Preserve more of the original image
658
    response_format: 'b64_json'
659
  });
660

661
  if (response.data[0].b64_json) {
662
    const buffer = Buffer.from(response.data[0].b64_json, 'base64');
663
    fs.writeFileSync('masked_edited_image.png', buffer);
664
    console.log('Masked edit completed');
665
  }
666
}
667

668
editImageWithMask().catch(console.error);
669
```
670

671
#### Multiple Image Editing
672

673
Edit multiple images at once (gpt-image-1 supports up to 16 images).
674

675
```typescript
676
import OpenAI from 'openai';
677
import fs from 'fs';
678

679
const client = new OpenAI();
680

681
async function editMultipleImages() {
682
  // Read multiple source images
683
  const images = [
684
    fs.readFileSync('photo1.png'),
685
    fs.readFileSync('photo2.png'),
686
    fs.readFileSync('photo3.png')
687
  ];
688

689
  const response = await client.images.edit({
690
    image: images,
691
    prompt: 'Enhance the colors and add vibrant lighting, increase contrast and saturation',
692
    model: 'gpt-image-1',
693
    n: 3, // One edit per image
694
    size: '1024x1024',
695
    quality: 'medium',
696
    output_format: 'png',
697
    response_format: 'b64_json'
698
  });
699

700
  response.data.forEach((image, index) => {
701
    if (image.b64_json) {
702
      const buffer = Buffer.from(image.b64_json, 'base64');
703
      fs.writeFileSync(`enhanced_${index + 1}.png`, buffer);
704
    }
705
  });
706

707
  console.log(`Edited ${response.data.length} images`);
708
}
709

710
editMultipleImages().catch(console.error);
711
```
712

713
#### Streaming Image Editing
714

715
Stream edited images with partial previews.
716

717
```typescript
718
import OpenAI from 'openai';
719
import fs from 'fs';
720

721
const client = new OpenAI();
722

723
async function streamImageEdit() {
724
  const imageData = fs.readFileSync('original.png');
725

726
  console.log('Starting image edit stream...');
727

728
  const stream = await client.images.edit({
729
    image: imageData,
730
    prompt: 'Transform the scene to show the same location during a magical winter night with snow and glowing aurora borealis',
731
    model: 'gpt-image-1',
732
    n: 1,
733
    size: '1024x1024',
734
    quality: 'high',
735
    stream: true,
736
    partial_images: 3,
737
    response_format: 'b64_json'
738
  });
739

740
  let eventCount = 0;
741

742
  for await (const event of stream) {
743
    if (event.type === 'image_edit.partial_image') {
744
      eventCount++;
745
      console.log(`Partial edit ${event.partial_image_index + 1} received`);
746
      console.log(`  Background: ${event.background}`);
747
      // Could render progressive preview here
748
    } else if (event.type === 'image_edit.completed') {
749
      console.log('Edit completed!');
750
      console.log(`  Quality applied: ${event.quality}`);
751
      console.log(`  Format: ${event.output_format}`);
752

753
      if (event.b64_json) {
754
        const buffer = Buffer.from(event.b64_json, 'base64');
755
        fs.writeFileSync('winter_edit.png', buffer);
756
        console.log('Final edited image saved');
757
      }
758
    }
759
  }
760

761
  console.log(`Total events received: ${eventCount}`);
762
}
763

764
streamImageEdit().catch(console.error);
765
```
766

767
### Creating Image Variations
768

769
#### Basic Variation Creation
770

771
Create variations of an existing image (dall-e-2 only).
772

773
```typescript
774
import OpenAI from 'openai';
775
import fs from 'fs';
776

777
const client = new OpenAI();
778

779
async function createVariations() {
780
  // Read the source image (must be square PNG < 4MB)
781
  const imageData = fs.readFileSync('reference_image.png');
782

783
  const response = await client.images.createVariation({
784
    image: imageData,
785
    model: 'dall-e-2',
786
    n: 4,
787
    size: '1024x1024',
788
    response_format: 'b64_json'
789
  });
790

791
  response.data.forEach((image, index) => {
792
    if (image.b64_json) {
793
      const buffer = Buffer.from(image.b64_json, 'base64');
794
      fs.writeFileSync(`variation_${index + 1}.png`, buffer);
795
    }
796
  });
797

798
  console.log(`Created ${response.data.length} variations`);
799
  console.log('Created at:', new Date(response.created * 1000).toISOString());
800
}
801

802
createVariations().catch(console.error);
803
```
804

805
#### Different Sizes for Variations
806

807
Create variations of different sizes.
808

809
```typescript
810
import OpenAI from 'openai';
811
import fs from 'fs';
812

813
const client = new OpenAI();
814

815
async function createVariationsMultipleSizes() {
816
  const imageData = fs.readFileSync('portrait.png');
817

818
  // Create thumbnails
819
  const smallVariations = await client.images.createVariation({
820
    image: imageData,
821
    size: '256x256',
822
    n: 2,
823
    response_format: 'url'
824
  });
825

826
  // Create medium variations
827
  const mediumVariations = await client.images.createVariation({
828
    image: imageData,
829
    size: '512x512',
830
    n: 2,
831
    response_format: 'url'
832
  });
833

834
  // Create large variations
835
  const largeVariations = await client.images.createVariation({
836
    image: imageData,
837
    size: '1024x1024',
838
    n: 2,
839
    response_format: 'url'
840
  });
841

842
  console.log('Small (256x256):', smallVariations.data.map(img => img.url));
843
  console.log('Medium (512x512):', mediumVariations.data.map(img => img.url));
844
  console.log('Large (1024x1024):', largeVariations.data.map(img => img.url));
845

846
  // Remember: URLs expire after 60 minutes - download immediately if needed
847
}
848

849
createVariationsMultipleSizes().catch(console.error);
850
```
851

852
---
853

854
## Image Parameters Reference
855

856
### Size Parameter
857

858
Image dimensions determine level of detail and computational cost.
859

860
| Size | Models | Use Case |
861
|------|--------|----------|
862
| `256x256` | dall-e-2 | Thumbnails, quick previews |
863
| `512x512` | dall-e-2 | Small images, mobile-friendly |
864
| `1024x1024` | dall-e-2, dall-e-3, gpt-image-1 | Standard size, balanced quality |
865
| `1536x1024` | gpt-image-1 | Landscape, wider content |
866
| `1024x1536` | gpt-image-1 | Portrait, taller content |
867
| `1792x1024` | dall-e-3 | Wide landscape (dall-e-3 only) |
868
| `1024x1792` | dall-e-3 | Tall portrait (dall-e-3 only) |
869
| `auto` | gpt-image-1 | Let model determine optimal size |
870
871
### Quality Parameter
872

873
Controls detail level and processing time.
874

875
| Quality | Models | Notes |
876
|---------|--------|-------|
877
| `auto` | gpt-image-1 | Automatically selects best quality |
878
| `low` | gpt-image-1 | Faster generation, lower detail |
879
| `medium` | gpt-image-1 | Balanced generation and quality |
880
| `high` | gpt-image-1 | Higher detail, longer processing |
881
| `standard` | dall-e-2, dall-e-3 | Default for DALL-E models |
882
| `hd` | dall-e-3 | Enhanced detail (DALL-E 3 only) |
883
884
### Style Parameter
885

886
Artistic direction (dall-e-3 only).
887

888
| Style | Description |
889
|-------|-------------|
890
| `vivid` | Hyper-real, dramatic, saturated colors |
891
| `natural` | Natural, less stylized appearance |
892
893
### Response Format Parameter
894

895
How images are returned.
896

897
| Format | Return Type | Expiration | Notes |
898
|--------|------------|-----------|-------|
899
| `url` | HTTP URL | 60 minutes | Default for DALL-E, easier to distribute |
900
| `b64_json` | Base64 string | No expiration | Better for long-term storage, slightly larger payload |
901
902
### Background Parameter
903

904
Background handling (gpt-image-1 only).
905

906
| Background | Description |
907
|-----------|-------------|
908
| `auto` | Model determines best background (default) |
909
| `transparent` | Transparent background (requires png/webp format) |
910
| `opaque` | Solid opaque background |
911
912
### Model Selection Guide
913

914
| Model | Best For | Strengths | Limitations |
915
|-------|----------|-----------|-------------|
916
| `dall-e-2` | Classic image generation | Established, reliable | Limited size options |
917
| `dall-e-3` | High-quality artistic images | Detailed prompts, vivid style | Only n=1 supported |
918
| `gpt-image-1` | Multi-image, streaming, editing | Streaming, masks, multiple images | Newer, still being optimized |
919
| `gpt-image-1-mini` | Fast, lightweight generation | Low latency | Reduced quality, fewer features |
920
921
---
922

923
## Best Practices
924

925
### Prompt Engineering
926

927
- **Be specific**: More detailed prompts produce better results
928
- **Specify style**: Include artistic direction (e.g., "photorealistic", "oil painting", "watercolor")
929
- **Set context**: Describe lighting, composition, and mood
930
- **Avoid ambiguity**: Use specific colors, objects, and relationships
931

932
Example:
933
```typescript
934
// Good prompt
935
prompt: 'A cozy cabin in snowy forest at twilight, warm golden light from windows, detailed architectural style, photorealistic, film noir lighting'
936

937
// Poor prompt
938
prompt: 'A house in snow'
939
```
940

941
### Error Handling
942

943
```typescript
944
import OpenAI from 'openai';
945

946
const client = new OpenAI();
947

948
async function safeImageGeneration() {
949
  try {
950
    const response = await client.images.generate({
951
      model: 'gpt-image-1',
952
      prompt: 'Your creative prompt here',
953
      n: 1,
954
      size: '1024x1024'
955
    });
956
    return response;
957
  } catch (error) {
958
    if (error instanceof OpenAI.APIError) {
959
      console.error('API Error:', error.message);
960
      console.error('Status:', error.status);
961

962
      if (error.status === 400) {
963
        console.error('Invalid parameters provided');
964
      } else if (error.status === 429) {
965
        console.error('Rate limited - too many requests');
966
      } else if (error.status === 500) {
967
        console.error('Server error - please retry');
968
      }
969
    }
970
    throw error;
971
  }
972
}
973
```
974

975
### URL Management
976

977
```typescript
978
import OpenAI from 'openai';
979

980
const client = new OpenAI();
981

982
async function manageImageUrls() {
983
  const response = await client.images.generate({
984
    model: 'dall-e-2',
985
    prompt: 'A beautiful landscape',
986
    response_format: 'url'
987
  });
988

989
  // URLs expire after 60 minutes - download immediately
990
  for (const image of response.data) {
991
    if (image.url) {
992
      // Download and save immediately or store permanently
993
      const response = await fetch(image.url);
994
      const buffer = await response.arrayBuffer();
995
      // Save buffer to disk or convert to base64
996
    }
997
  }
998
}
999
```
1000

1001
### Streaming Best Practices
1002

1003
```typescript
1004
import OpenAI from 'openai';
1005
import fs from 'fs';
1006

1007
const client = new OpenAI();
1008

1009
async function efficientStreaming() {
1010
  const stream = await client.images.generate({
1011
    model: 'gpt-image-1',
1012
    prompt: 'Your image prompt',
1013
    stream: true,
1014
    partial_images: 2 // Balance preview updates and final quality
1015
  });
1016

1017
  const progressUpdates: string[] = [];
1018

1019
  for await (const event of stream) {
1020
    if (event.type === 'image_generation.partial_image') {
1021
      // Update UI with partial image
1022
      progressUpdates.push(`Partial ${event.partial_image_index + 1}`);
1023
    } else if (event.type === 'image_generation.completed') {
1024
      // Process final image
1025
      if (event.b64_json) {
1026
        const buffer = Buffer.from(event.b64_json, 'base64');
1027
        fs.writeFileSync('final_image.png', buffer);
1028
      }
1029
      console.log('Generation complete with updates:', progressUpdates);
1030
    }
1031
  }
1032
}
1033

1034
efficientStreaming().catch(console.error);
1035
```
1036

1037
### Cost Optimization
1038

1039
```typescript
1040
import OpenAI from 'openai';
1041

1042
const client = new OpenAI();
1043

1044
// Use gpt-image-1-mini for fast, low-cost generation
1045
async function costOptimized() {
1046
  return client.images.generate({
1047
    model: 'gpt-image-1-mini', // Smaller model, lower cost
1048
    prompt: 'Your prompt',
1049
    n: 1,
1050
    size: '1024x1024',
1051
    quality: 'low' // Lower quality = lower cost
1052
  });
1053
}
1054

1055
// Use batch processing for multiple images
1056
async function batchGeneration() {
1057
  const prompts = [
1058
    'A peaceful garden',
1059
    'A mountain landscape',
1060
    'An urban skyline'
1061
  ];
1062

1063
  const results = await Promise.all(
1064
    prompts.map(prompt =>
1065
      client.images.generate({
1066
        model: 'gpt-image-1-mini',
1067
        prompt,
1068
        n: 1,
1069
        size: '512x512' // Smaller size = lower cost
1070
      })
1071
    )
1072
  );
1073

1074
  return results;
1075
}
1076
```
1077

1078
---
1079

1080
## Related Resources
1081

1082
- [Chat Completions](./chat-completions.md) - For multi-modal image analysis
1083
- [API Reference - Images](../index.md) - OpenAI Images API details
1084