0
# Image Generation
1

2
The Models module provides comprehensive image generation capabilities including text-to-image generation, image editing, upscaling, segmentation, and recontextualization using Imagen models.
3

4
## Capabilities
5

6
### generateImages
7

8
Generate images from text prompts using Imagen models.
9

10
```typescript { .api }
11
/**
12
 * Generate images from text prompts
13
 * @param params - Image generation parameters
14
 * @returns Promise resolving to generated images
15
 */
16
function generateImages(
17
  params: GenerateImagesParameters
18
): Promise<GenerateImagesResponse>;
19

20
interface GenerateImagesParameters {
21
  /** Model name (e.g., 'imagen-3.0-generate-002') */
22
  model: string;
23
  /** Text prompt describing the image */
24
  prompt: string;
25
  /** Image generation configuration */
26
  config?: GenerateImagesConfig;
27
}
28

29
interface GenerateImagesResponse {
30
  /** Generated images */
31
  generatedImages?: GeneratedImage[];
32
  /** RAI (Responsible AI) information */
33
  raiFilteredReason?: string;
34
}
35

36
interface GeneratedImage {
37
  /** Image data */
38
  image?: ImageBlob;
39
  /** RAI information for this image */
40
  rai?: Rai;
41
}
42

43
interface ImageBlob {
44
  /** Base64-encoded image data */
45
  data?: string;
46
  /** MIME type (e.g., 'image/png') */
47
  mimeType?: string;
48
}
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import { GoogleGenAI } from '@google/genai';
55

56
const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });
57

58
// Basic image generation
59
const response = await client.models.generateImages({
60
  model: 'imagen-3.0-generate-002',
61
  prompt: 'A serene lake surrounded by mountains at sunset'
62
});
63

64
// Access generated image
65
const imageData = response.generatedImages?.[0]?.image?.data;
66
if (imageData) {
67
  // imageData is base64-encoded
68
  console.log('Image generated successfully');
69
}
70

71
// With configuration
72
const configuredResponse = await client.models.generateImages({
73
  model: 'imagen-3.0-generate-002',
74
  prompt: 'A futuristic city with flying cars',
75
  config: {
76
    numberOfImages: 4,
77
    aspectRatio: '16:9',
78
    safetyFilterLevel: SafetyFilterLevel.BLOCK_ONLY_HIGH,
79
    personGeneration: PersonGeneration.ALLOW_ADULT
80
  }
81
});
82
```
83

84
### editImage
85

86
Edit images with masks and prompts for inpainting, insertion, or outpainting.
87

88
```typescript { .api }
89
/**
90
 * Edit images with reference images and prompts
91
 * @param params - Image editing parameters
92
 * @returns Promise resolving to edited images
93
 */
94
function editImage(
95
  params: EditImageParameters
96
): Promise<EditImageResponse>;
97

98
interface EditImageParameters {
99
  /** Model name (e.g., 'imagen-3.0-capability-001') */
100
  model: string;
101
  /** Text prompt describing the edit */
102
  prompt: string;
103
  /** Reference images (raw image, mask, control, style, subject) */
104
  referenceImages: ReferenceImageUnion[];
105
  /** Edit configuration */
106
  config?: EditImageConfig;
107
}
108

109
interface EditImageResponse {
110
  /** Generated edited images */
111
  generatedImages?: GeneratedImage[];
112
  /** RAI filtered reason */
113
  raiFilteredReason?: string;
114
}
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
import {
121
  RawReferenceImage,
122
  MaskReferenceImage,
123
  MaskMode,
124
  EditMode
125
} from '@google/genai';
126

127
// Remove object from image (inpainting removal)
128
const rawImage = new RawReferenceImage({
129
  referenceId: 1,
130
  referenceImage: {
131
    data: base64ImageData,
132
    mimeType: 'image/png'
133
  }
134
});
135

136
const maskImage = new MaskReferenceImage({
137
  referenceId: 1,
138
  mode: MaskMode.USER_PROVIDED,
139
  mask: {
140
    referenceImage: {
141
      data: base64MaskData,
142
      mimeType: 'image/png'
143
    }
144
  }
145
});
146

147
const editResponse = await client.models.editImage({
148
  model: 'imagen-3.0-capability-001',
149
  prompt: 'Remove the object',
150
  referenceImages: [rawImage, maskImage],
151
  config: {
152
    editMode: EditMode.INPAINT_REMOVAL,
153
    numberOfImages: 1
154
  }
155
});
156

157
// Insert object into image (inpainting insertion)
158
const insertResponse = await client.models.editImage({
159
  model: 'imagen-3.0-capability-001',
160
  prompt: 'Add a red sports car',
161
  referenceImages: [rawImage, maskImage],
162
  config: {
163
    editMode: EditMode.INPAINT_INSERTION,
164
    numberOfImages: 2
165
  }
166
});
167
```
168

169
### upscaleImage
170

171
Upscale images to higher resolution (Vertex AI only).
172

173
```typescript { .api }
174
/**
175
 * Upscale images to higher resolution
176
 * @param params - Image upscaling parameters
177
 * @returns Promise resolving to upscaled images
178
 */
179
function upscaleImage(
180
  params: UpscaleImageParameters
181
): Promise<UpscaleImageResponse>;
182

183
interface UpscaleImageParameters {
184
  /** Model name */
185
  model: string;
186
  /** Image to upscale */
187
  image: BlobImageUnion;
188
  /** Upscale configuration */
189
  config?: UpscaleImageConfig;
190
}
191

192
interface UpscaleImageResponse {
193
  /** Upscaled images */
194
  generatedImages?: GeneratedImage[];
195
}
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
// Upscale image (Vertex AI)
202
const vertexClient = new GoogleGenAI({
203
  vertexai: true,
204
  project: 'my-project',
205
  location: 'us-central1'
206
});
207

208
const upscaleResponse = await vertexClient.models.upscaleImage({
209
  model: 'imagegeneration@006',
210
  image: {
211
    data: base64ImageData,
212
    mimeType: 'image/png'
213
  },
214
  config: {
215
    upscaleFactor: 'x2'
216
  }
217
});
218
```
219

220
### segmentImage
221

222
Segment and extract parts of images (foreground, background, or prompt-based).
223

224
```typescript { .api }
225
/**
226
 * Image segmentation and masking
227
 * @param params - Segmentation parameters
228
 * @returns Promise resolving to segmented images
229
 */
230
function segmentImage(
231
  params: SegmentImageParameters
232
): Promise<SegmentImageResponse>;
233

234
interface SegmentImageParameters {
235
  /** Model name */
236
  model: string;
237
  /** Image to segment */
238
  image: BlobImageUnion;
239
  /** Segmentation configuration */
240
  config: SegmentImageConfig;
241
}
242

243
interface SegmentImageResponse {
244
  /** Segmented images/masks */
245
  generatedImages?: GeneratedImage[];
246
}
247
```
248

249
**Usage Examples:**
250

251
```typescript
252
import { SegmentMode } from '@google/genai';
253

254
// Segment foreground
255
const foregroundResponse = await client.models.segmentImage({
256
  model: 'imagen-3.0-capability-001',
257
  image: {
258
    data: base64ImageData,
259
    mimeType: 'image/jpeg'
260
  },
261
  config: {
262
    mode: SegmentMode.FOREGROUND
263
  }
264
});
265

266
// Segment with prompt
267
const promptSegmentResponse = await client.models.segmentImage({
268
  model: 'imagen-3.0-capability-001',
269
  image: {
270
    data: base64ImageData,
271
    mimeType: 'image/jpeg'
272
  },
273
  config: {
274
    mode: SegmentMode.PROMPT,
275
    prompt: 'the dog in the image'
276
  }
277
});
278
```
279

280
### recontextImage
281

282
Recontextualize product images for virtual try-on and product placement.
283

284
```typescript { .api }
285
/**
286
 * Recontextualize images (product recontext, virtual try-on)
287
 * @param params - Recontextualization parameters
288
 * @returns Promise resolving to recontextualized images
289
 */
290
function recontextImage(
291
  params: RecontextImageParameters
292
): Promise<RecontextImageResponse>;
293

294
interface RecontextImageParameters {
295
  /** Model name */
296
  model: string;
297
  /** Configuration for recontextualization */
298
  config: RecontextImageConfig;
299
}
300

301
interface RecontextImageResponse {
302
  /** Recontextualized images */
303
  generatedImages?: GeneratedImage[];
304
}
305
```
306

307
## Types
308

309
### GenerateImagesConfig
310

311
Configuration for image generation.
312

313
```typescript { .api }
314
interface GenerateImagesConfig {
315
  /** Number of images to generate (1-8) */
316
  numberOfImages?: number;
317
  /** Aspect ratio (e.g., '1:1', '16:9', '9:16', '4:3', '3:4') */
318
  aspectRatio?: string;
319
  /** Negative prompt (things to avoid) */
320
  negativePrompt?: string;
321
  /** Safety filter level */
322
  safetyFilterLevel?: SafetyFilterLevel;
323
  /** Person generation control */
324
  personGeneration?: PersonGeneration;
325
  /** Include RAI information in response */
326
  includeRaiReason?: boolean;
327
  /** Output MIME type (e.g., 'image/png', 'image/jpeg') */
328
  outputMimeType?: string;
329
  /** Compression quality (1-100) */
330
  compressionQuality?: number;
331
  /** Language for prompt */
332
  language?: string;
333
}
334
```
335

336
### EditImageConfig
337

338
Configuration for image editing.
339

340
```typescript { .api }
341
interface EditImageConfig {
342
  /** Edit mode (INPAINT_REMOVAL, INPAINT_INSERTION, OUTPAINT, etc.) */
343
  editMode?: EditMode;
344
  /** Number of edited images to generate */
345
  numberOfImages?: number;
346
  /** Negative prompt */
347
  negativePrompt?: string;
348
  /** Safety filter level */
349
  safetyFilterLevel?: SafetyFilterLevel;
350
  /** Person generation control */
351
  personGeneration?: PersonGeneration;
352
  /** Guidance scale */
353
  guidanceScale?: number;
354
  /** Include RAI information */
355
  includeRaiReason?: boolean;
356
  /** Output MIME type */
357
  outputMimeType?: string;
358
  /** Compression quality (1-100) */
359
  compressionQuality?: number;
360
}
361
```
362

363
### UpscaleImageConfig
364

365
Configuration for image upscaling.
366

367
```typescript { .api }
368
interface UpscaleImageConfig {
369
  /** Upscale factor ('x2' or 'x4') */
370
  upscaleFactor?: string;
371
  /** Output MIME type */
372
  outputMimeType?: string;
373
  /** Compression quality (1-100) */
374
  compressionQuality?: number;
375
}
376
```
377

378
### SegmentImageConfig
379

380
Configuration for image segmentation.
381

382
```typescript { .api }
383
interface SegmentImageConfig {
384
  /** Segmentation mode */
385
  mode: SegmentMode;
386
  /** Prompt for PROMPT mode */
387
  prompt?: string;
388
}
389
```
390

391
### Reference Image Classes
392

393
Classes for different types of reference images used in editing.
394

395
```typescript { .api }
396
/**
397
 * Raw reference image (base64 encoded)
398
 */
399
class RawReferenceImage {
400
  constructor(params: {
401
    referenceId?: number;
402
    referenceImage: {
403
      data: string;
404
      mimeType: string;
405
    };
406
  });
407

408
  toReferenceImageAPI(): ReferenceImageAPIInternal;
409
}
410

411
/**
412
 * Mask reference image for inpainting
413
 */
414
class MaskReferenceImage {
415
  constructor(params: {
416
    referenceId?: number;
417
    mode?: MaskMode;
418
    mask?: {
419
      referenceImage?: {
420
        data: string;
421
        mimeType: string;
422
      };
423
    };
424
  });
425

426
  toReferenceImageAPI(): ReferenceImageAPIInternal;
427
}
428

429
/**
430
 * Control reference image (for style/structure control)
431
 */
432
class ControlReferenceImage {
433
  constructor(params: {
434
    referenceId?: number;
435
    controlType?: ControlType;
436
    referenceImage?: {
437
      data: string;
438
      mimeType: string;
439
    };
440
  });
441

442
  toReferenceImageAPI(): ReferenceImageAPIInternal;
443
}
444

445
/**
446
 * Style reference image
447
 */
448
class StyleReferenceImage {
449
  constructor(params: {
450
    referenceId?: number;
451
    styleDescription?: string;
452
    weight?: number;
453
    referenceImage?: {
454
      data: string;
455
      mimeType: string;
456
    };
457
  });
458

459
  toReferenceImageAPI(): ReferenceImageAPIInternal;
460
}
461

462
/**
463
 * Subject reference image (person, animal, product)
464
 */
465
class SubjectReferenceImage {
466
  constructor(params: {
467
    referenceId?: number;
468
    subjectType?: SubjectType;
469
    referenceImage?: {
470
      data: string;
471
      mimeType: string;
472
    };
473
  });
474

475
  toReferenceImageAPI(): ReferenceImageAPIInternal;
476
}
477

478
/**
479
 * Content reference image
480
 */
481
class ContentReferenceImage {
482
  constructor(params: {
483
    referenceImage?: {
484
      data: string;
485
      mimeType: string;
486
    };
487
  });
488

489
  toReferenceImageAPI(): ReferenceImageAPIInternal;
490
}
491
```
492

493
### Enumerations
494

495
```typescript { .api }
496
enum SafetyFilterLevel {
497
  BLOCK_LOW_AND_ABOVE = 'BLOCK_LOW_AND_ABOVE',
498
  BLOCK_MEDIUM_AND_ABOVE = 'BLOCK_MEDIUM_AND_ABOVE',
499
  BLOCK_ONLY_HIGH = 'BLOCK_ONLY_HIGH',
500
  BLOCK_NONE = 'BLOCK_NONE'
501
}
502

503
enum PersonGeneration {
504
  DONT_ALLOW = 'DONT_ALLOW',
505
  ALLOW_ADULT = 'ALLOW_ADULT',
506
  ALLOW_ALL = 'ALLOW_ALL'
507
}
508

509
enum EditMode {
510
  EDIT_MODE_UNSPECIFIED = 'EDIT_MODE_UNSPECIFIED',
511
  INPAINT_REMOVAL = 'INPAINT_REMOVAL',
512
  INPAINT_INSERTION = 'INPAINT_INSERTION',
513
  OUTPAINT = 'OUTPAINT',
514
  PRODUCT_IMAGE_UPSCALE = 'PRODUCT_IMAGE_UPSCALE'
515
}
516

517
enum SegmentMode {
518
  SEGMENT_MODE_UNSPECIFIED = 'SEGMENT_MODE_UNSPECIFIED',
519
  FOREGROUND = 'FOREGROUND',
520
  BACKGROUND = 'BACKGROUND',
521
  PROMPT = 'PROMPT'
522
}
523

524
enum MaskMode {
525
  USER_PROVIDED = 'USER_PROVIDED',
526
  BACKGROUND = 'BACKGROUND',
527
  FOREGROUND = 'FOREGROUND',
528
  SEMANTIC = 'SEMANTIC'
529
}
530

531
enum ControlType {
532
  CANNY = 'CANNY',
533
  SCRIBBLE = 'SCRIBBLE',
534
  FACE_MESH = 'FACE_MESH'
535
}
536

537
enum SubjectType {
538
  PERSON = 'PERSON',
539
  ANIMAL = 'ANIMAL',
540
  PRODUCT = 'PRODUCT'
541
}
542
```
543

544
### RAI (Responsible AI) Types
545

546
```typescript { .api }
547
interface Rai {
548
  /** Whether content was blocked */
549
  blocked?: boolean;
550
  /** Reason for blocking */
551
  blockReason?: string;
552
  /** Safety scores */
553
  scores?: number[];
554
}
555
```
556

557
## Complete Examples
558

559
### Generate Multiple Images
560

561
```typescript
562
import { GoogleGenAI, SafetyFilterLevel, PersonGeneration } from '@google/genai';
563

564
const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });
565

566
const response = await client.models.generateImages({
567
  model: 'imagen-3.0-generate-002',
568
  prompt: 'A cozy coffee shop interior with warm lighting',
569
  config: {
570
    numberOfImages: 4,
571
    aspectRatio: '16:9',
572
    negativePrompt: 'people, crowded, messy',
573
    safetyFilterLevel: SafetyFilterLevel.BLOCK_MEDIUM_AND_ABOVE,
574
    personGeneration: PersonGeneration.DONT_ALLOW,
575
    outputMimeType: 'image/png'
576
  }
577
});
578

579
// Save all generated images
580
response.generatedImages?.forEach((img, index) => {
581
  if (img.image?.data) {
582
    const buffer = Buffer.from(img.image.data, 'base64');
583
    require('fs').writeFileSync(`output_${index}.png`, buffer);
584
  }
585
});
586
```
587

588
### Style Transfer with Reference Images
589

590
```typescript
591
import {
592
  RawReferenceImage,
593
  StyleReferenceImage
594
} from '@google/genai';
595

596
// Read images as base64
597
const contentImageData = require('fs').readFileSync('./photo.jpg', 'base64');
598
const styleImageData = require('fs').readFileSync('./painting.jpg', 'base64');
599

600
const contentRef = new RawReferenceImage({
601
  referenceId: 1,
602
  referenceImage: {
603
    data: contentImageData,
604
    mimeType: 'image/jpeg'
605
  }
606
});
607

608
const styleRef = new StyleReferenceImage({
609
  referenceId: 2,
610
  styleDescription: 'impressionist painting style',
611
  weight: 0.8,
612
  referenceImage: {
613
    data: styleImageData,
614
    mimeType: 'image/jpeg'
615
  }
616
});
617

618
const response = await client.models.editImage({
619
  model: 'imagen-3.0-capability-001',
620
  prompt: 'Apply artistic style to the image',
621
  referenceImages: [contentRef, styleRef],
622
  config: {
623
    numberOfImages: 2,
624
    guidanceScale: 7.5
625
  }
626
});
627
```
628

629
### Advanced Inpainting
630

631
```typescript
632
import {
633
  RawReferenceImage,
634
  MaskReferenceImage,
635
  MaskMode,
636
  EditMode
637
} from '@google/genai';
638

639
const originalImage = require('fs').readFileSync('./room.jpg', 'base64');
640
const maskImage = require('fs').readFileSync('./mask.png', 'base64');
641

642
const rawRef = new RawReferenceImage({
643
  referenceId: 1,
644
  referenceImage: {
645
    data: originalImage,
646
    mimeType: 'image/jpeg'
647
  }
648
});
649

650
const maskRef = new MaskReferenceImage({
651
  referenceId: 1,
652
  mode: MaskMode.USER_PROVIDED,
653
  mask: {
654
    referenceImage: {
655
      data: maskImage,
656
      mimeType: 'image/png'
657
    }
658
  }
659
});
660

661
// Insert new furniture into room
662
const response = await client.models.editImage({
663
  model: 'imagen-3.0-capability-001',
664
  prompt: 'modern blue sofa with cushions',
665
  referenceImages: [rawRef, maskRef],
666
  config: {
667
    editMode: EditMode.INPAINT_INSERTION,
668
    numberOfImages: 3,
669
    negativePrompt: 'old, damaged, dirty',
670
    guidanceScale: 8.0
671
  }
672
});
673

674
// Save results
675
response.generatedImages?.forEach((img, i) => {
676
  if (img.image?.data) {
677
    const buffer = Buffer.from(img.image.data, 'base64');
678
    require('fs').writeFileSync(`result_${i}.png`, buffer);
679
  }
680
});
681
```
682

683
### Outpainting (Extend Image Borders)
684

685
```typescript
686
import {
687
  RawReferenceImage,
688
  MaskReferenceImage,
689
  EditMode
690
} from '@google/genai';
691

692
const imageData = require('fs').readFileSync('./landscape.jpg', 'base64');
693

694
const rawRef = new RawReferenceImage({
695
  referenceId: 1,
696
  referenceImage: {
697
    data: imageData,
698
    mimeType: 'image/jpeg'
699
  }
700
});
701

702
// Extend image beyond its borders
703
const response = await client.models.editImage({
704
  model: 'imagen-3.0-capability-001',
705
  prompt: 'continue the landscape naturally',
706
  referenceImages: [rawRef],
707
  config: {
708
    editMode: EditMode.OUTPAINT,
709
    numberOfImages: 2,
710
    aspectRatio: '16:9'
711
  }
712
});
713
```
714

715
### Subject-Consistent Generation
716

717
```typescript
718
import { SubjectReferenceImage, SubjectType } from '@google/genai';
719

720
const productImageData = require('fs').readFileSync('./product.jpg', 'base64');
721

722
const subjectRef = new SubjectReferenceImage({
723
  referenceId: 1,
724
  subjectType: SubjectType.PRODUCT,
725
  referenceImage: {
726
    data: productImageData,
727
    mimeType: 'image/jpeg'
728
  }
729
});
730

731
// Generate product in different contexts
732
const response = await client.models.editImage({
733
  model: 'imagen-3.0-capability-001',
734
  prompt: 'show the product on a wooden table with natural lighting',
735
  referenceImages: [subjectRef],
736
  config: {
737
    numberOfImages: 4
738
  }
739
});
740
```
741

742
### Semantic Segmentation
743

744
```typescript
745
import { SegmentMode } from '@google/genai';
746

747
const imageData = require('fs').readFileSync('./photo.jpg', 'base64');
748

749
// Extract specific object
750
const response = await client.models.segmentImage({
751
  model: 'imagen-3.0-capability-001',
752
  image: {
753
    data: imageData,
754
    mimeType: 'image/jpeg'
755
  },
756
  config: {
757
    mode: SegmentMode.PROMPT,
758
    prompt: 'the car'
759
  }
760
});
761

762
// The response contains a mask of the segmented object
763
const maskData = response.generatedImages?.[0]?.image?.data;
764
if (maskData) {
765
  const buffer = Buffer.from(maskData, 'base64');
766
  require('fs').writeFileSync('car_mask.png', buffer);
767
}
768
```
769

770
### Control-Guided Generation
771

772
```typescript
773
import { ControlReferenceImage, ControlType } from '@google/genai';
774

775
const cannyEdgeData = require('fs').readFileSync('./edges.png', 'base64');
776

777
const controlRef = new ControlReferenceImage({
778
  referenceId: 1,
779
  controlType: ControlType.CANNY,
780
  referenceImage: {
781
    data: cannyEdgeData,
782
    mimeType: 'image/png'
783
  }
784
});
785

786
// Generate image following edge structure
787
const response = await client.models.editImage({
788
  model: 'imagen-3.0-capability-001',
789
  prompt: 'a beautiful house with garden',
790
  referenceImages: [controlRef],
791
  config: {
792
    numberOfImages: 2,
793
    guidanceScale: 9.0
794
  }
795
});
796
```
797

798
### RAI Filtering and Error Handling
799

800
```typescript
801
import { SafetyFilterLevel } from '@google/genai';
802

803
try {
804
  const response = await client.models.generateImages({
805
    model: 'imagen-3.0-generate-002',
806
    prompt: 'a peaceful scene',
807
    config: {
808
      numberOfImages: 4,
809
      safetyFilterLevel: SafetyFilterLevel.BLOCK_MEDIUM_AND_ABOVE,
810
      includeRaiReason: true
811
    }
812
  });
813

814
  // Check if any images were filtered
815
  if (response.raiFilteredReason) {
816
    console.log('Some images filtered:', response.raiFilteredReason);
817
  }
818

819
  // Check individual images
820
  response.generatedImages?.forEach((img, index) => {
821
    if (img.rai?.blocked) {
822
      console.log(`Image ${index} blocked: ${img.rai.blockReason}`);
823
    } else if (img.image?.data) {
824
      console.log(`Image ${index} generated successfully`);
825
    }
826
  });
827
} catch (error) {
828
  console.error('Generation failed:', error);
829
}
830
```
831