CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-google--genai

Google Gen AI JavaScript SDK for building applications powered by Gemini with content generation, image/video generation, function calling, caching, and real-time live sessions

Overview
Eval results
Files

image-generation.mddocs/

Image Generation

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

Capabilities

generateImages

Generate images from text prompts using Imagen models.

/**
 * Generate images from text prompts
 * @param params - Image generation parameters
 * @returns Promise resolving to generated images
 */
function generateImages(
  params: GenerateImagesParameters
): Promise<GenerateImagesResponse>;

interface GenerateImagesParameters {
  /** Model name (e.g., 'imagen-3.0-generate-002') */
  model: string;
  /** Text prompt describing the image */
  prompt: string;
  /** Image generation configuration */
  config?: GenerateImagesConfig;
}

interface GenerateImagesResponse {
  /** Generated images */
  generatedImages?: GeneratedImage[];
  /** RAI (Responsible AI) information */
  raiFilteredReason?: string;
}

interface GeneratedImage {
  /** Image data */
  image?: ImageBlob;
  /** RAI information for this image */
  rai?: Rai;
}

interface ImageBlob {
  /** Base64-encoded image data */
  data?: string;
  /** MIME type (e.g., 'image/png') */
  mimeType?: string;
}

Usage Examples:

import { GoogleGenAI } from '@google/genai';

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

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

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

// With configuration
const configuredResponse = await client.models.generateImages({
  model: 'imagen-3.0-generate-002',
  prompt: 'A futuristic city with flying cars',
  config: {
    numberOfImages: 4,
    aspectRatio: '16:9',
    safetyFilterLevel: SafetyFilterLevel.BLOCK_ONLY_HIGH,
    personGeneration: PersonGeneration.ALLOW_ADULT
  }
});

editImage

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

/**
 * Edit images with reference images and prompts
 * @param params - Image editing parameters
 * @returns Promise resolving to edited images
 */
function editImage(
  params: EditImageParameters
): Promise<EditImageResponse>;

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

interface EditImageResponse {
  /** Generated edited images */
  generatedImages?: GeneratedImage[];
  /** RAI filtered reason */
  raiFilteredReason?: string;
}

Usage Examples:

import {
  RawReferenceImage,
  MaskReferenceImage,
  MaskMode,
  EditMode
} from '@google/genai';

// Remove object from image (inpainting removal)
const rawImage = new RawReferenceImage({
  referenceId: 1,
  referenceImage: {
    data: base64ImageData,
    mimeType: 'image/png'
  }
});

const maskImage = new MaskReferenceImage({
  referenceId: 1,
  mode: MaskMode.USER_PROVIDED,
  mask: {
    referenceImage: {
      data: base64MaskData,
      mimeType: 'image/png'
    }
  }
});

const editResponse = await client.models.editImage({
  model: 'imagen-3.0-capability-001',
  prompt: 'Remove the object',
  referenceImages: [rawImage, maskImage],
  config: {
    editMode: EditMode.INPAINT_REMOVAL,
    numberOfImages: 1
  }
});

// Insert object into image (inpainting insertion)
const insertResponse = await client.models.editImage({
  model: 'imagen-3.0-capability-001',
  prompt: 'Add a red sports car',
  referenceImages: [rawImage, maskImage],
  config: {
    editMode: EditMode.INPAINT_INSERTION,
    numberOfImages: 2
  }
});

upscaleImage

Upscale images to higher resolution (Vertex AI only).

/**
 * Upscale images to higher resolution
 * @param params - Image upscaling parameters
 * @returns Promise resolving to upscaled images
 */
function upscaleImage(
  params: UpscaleImageParameters
): Promise<UpscaleImageResponse>;

interface UpscaleImageParameters {
  /** Model name */
  model: string;
  /** Image to upscale */
  image: BlobImageUnion;
  /** Upscale configuration */
  config?: UpscaleImageConfig;
}

interface UpscaleImageResponse {
  /** Upscaled images */
  generatedImages?: GeneratedImage[];
}

Usage Examples:

// Upscale image (Vertex AI)
const vertexClient = new GoogleGenAI({
  vertexai: true,
  project: 'my-project',
  location: 'us-central1'
});

const upscaleResponse = await vertexClient.models.upscaleImage({
  model: 'imagegeneration@006',
  image: {
    data: base64ImageData,
    mimeType: 'image/png'
  },
  config: {
    upscaleFactor: 'x2'
  }
});

segmentImage

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

/**
 * Image segmentation and masking
 * @param params - Segmentation parameters
 * @returns Promise resolving to segmented images
 */
function segmentImage(
  params: SegmentImageParameters
): Promise<SegmentImageResponse>;

interface SegmentImageParameters {
  /** Model name */
  model: string;
  /** Image to segment */
  image: BlobImageUnion;
  /** Segmentation configuration */
  config: SegmentImageConfig;
}

interface SegmentImageResponse {
  /** Segmented images/masks */
  generatedImages?: GeneratedImage[];
}

Usage Examples:

import { SegmentMode } from '@google/genai';

// Segment foreground
const foregroundResponse = await client.models.segmentImage({
  model: 'imagen-3.0-capability-001',
  image: {
    data: base64ImageData,
    mimeType: 'image/jpeg'
  },
  config: {
    mode: SegmentMode.FOREGROUND
  }
});

// Segment with prompt
const promptSegmentResponse = await client.models.segmentImage({
  model: 'imagen-3.0-capability-001',
  image: {
    data: base64ImageData,
    mimeType: 'image/jpeg'
  },
  config: {
    mode: SegmentMode.PROMPT,
    prompt: 'the dog in the image'
  }
});

recontextImage

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

/**
 * Recontextualize images (product recontext, virtual try-on)
 * @param params - Recontextualization parameters
 * @returns Promise resolving to recontextualized images
 */
function recontextImage(
  params: RecontextImageParameters
): Promise<RecontextImageResponse>;

interface RecontextImageParameters {
  /** Model name */
  model: string;
  /** Configuration for recontextualization */
  config: RecontextImageConfig;
}

interface RecontextImageResponse {
  /** Recontextualized images */
  generatedImages?: GeneratedImage[];
}

Types

GenerateImagesConfig

Configuration for image generation.

interface GenerateImagesConfig {
  /** Number of images to generate (1-8) */
  numberOfImages?: number;
  /** Aspect ratio (e.g., '1:1', '16:9', '9:16', '4:3', '3:4') */
  aspectRatio?: string;
  /** Negative prompt (things to avoid) */
  negativePrompt?: string;
  /** Safety filter level */
  safetyFilterLevel?: SafetyFilterLevel;
  /** Person generation control */
  personGeneration?: PersonGeneration;
  /** Include RAI information in response */
  includeRaiReason?: boolean;
  /** Output MIME type (e.g., 'image/png', 'image/jpeg') */
  outputMimeType?: string;
  /** Compression quality (1-100) */
  compressionQuality?: number;
  /** Language for prompt */
  language?: string;
}

EditImageConfig

Configuration for image editing.

interface EditImageConfig {
  /** Edit mode (INPAINT_REMOVAL, INPAINT_INSERTION, OUTPAINT, etc.) */
  editMode?: EditMode;
  /** Number of edited images to generate */
  numberOfImages?: number;
  /** Negative prompt */
  negativePrompt?: string;
  /** Safety filter level */
  safetyFilterLevel?: SafetyFilterLevel;
  /** Person generation control */
  personGeneration?: PersonGeneration;
  /** Guidance scale */
  guidanceScale?: number;
  /** Include RAI information */
  includeRaiReason?: boolean;
  /** Output MIME type */
  outputMimeType?: string;
  /** Compression quality (1-100) */
  compressionQuality?: number;
}

UpscaleImageConfig

Configuration for image upscaling.

interface UpscaleImageConfig {
  /** Upscale factor ('x2' or 'x4') */
  upscaleFactor?: string;
  /** Output MIME type */
  outputMimeType?: string;
  /** Compression quality (1-100) */
  compressionQuality?: number;
}

SegmentImageConfig

Configuration for image segmentation.

interface SegmentImageConfig {
  /** Segmentation mode */
  mode: SegmentMode;
  /** Prompt for PROMPT mode */
  prompt?: string;
}

Reference Image Classes

Classes for different types of reference images used in editing.

/**
 * Raw reference image (base64 encoded)
 */
class RawReferenceImage {
  constructor(params: {
    referenceId?: number;
    referenceImage: {
      data: string;
      mimeType: string;
    };
  });

  toReferenceImageAPI(): ReferenceImageAPIInternal;
}

/**
 * Mask reference image for inpainting
 */
class MaskReferenceImage {
  constructor(params: {
    referenceId?: number;
    mode?: MaskMode;
    mask?: {
      referenceImage?: {
        data: string;
        mimeType: string;
      };
    };
  });

  toReferenceImageAPI(): ReferenceImageAPIInternal;
}

/**
 * Control reference image (for style/structure control)
 */
class ControlReferenceImage {
  constructor(params: {
    referenceId?: number;
    controlType?: ControlType;
    referenceImage?: {
      data: string;
      mimeType: string;
    };
  });

  toReferenceImageAPI(): ReferenceImageAPIInternal;
}

/**
 * Style reference image
 */
class StyleReferenceImage {
  constructor(params: {
    referenceId?: number;
    styleDescription?: string;
    weight?: number;
    referenceImage?: {
      data: string;
      mimeType: string;
    };
  });

  toReferenceImageAPI(): ReferenceImageAPIInternal;
}

/**
 * Subject reference image (person, animal, product)
 */
class SubjectReferenceImage {
  constructor(params: {
    referenceId?: number;
    subjectType?: SubjectType;
    referenceImage?: {
      data: string;
      mimeType: string;
    };
  });

  toReferenceImageAPI(): ReferenceImageAPIInternal;
}

/**
 * Content reference image
 */
class ContentReferenceImage {
  constructor(params: {
    referenceImage?: {
      data: string;
      mimeType: string;
    };
  });

  toReferenceImageAPI(): ReferenceImageAPIInternal;
}

Enumerations

enum SafetyFilterLevel {
  BLOCK_LOW_AND_ABOVE = 'BLOCK_LOW_AND_ABOVE',
  BLOCK_MEDIUM_AND_ABOVE = 'BLOCK_MEDIUM_AND_ABOVE',
  BLOCK_ONLY_HIGH = 'BLOCK_ONLY_HIGH',
  BLOCK_NONE = 'BLOCK_NONE'
}

enum PersonGeneration {
  DONT_ALLOW = 'DONT_ALLOW',
  ALLOW_ADULT = 'ALLOW_ADULT',
  ALLOW_ALL = 'ALLOW_ALL'
}

enum EditMode {
  EDIT_MODE_UNSPECIFIED = 'EDIT_MODE_UNSPECIFIED',
  INPAINT_REMOVAL = 'INPAINT_REMOVAL',
  INPAINT_INSERTION = 'INPAINT_INSERTION',
  OUTPAINT = 'OUTPAINT',
  PRODUCT_IMAGE_UPSCALE = 'PRODUCT_IMAGE_UPSCALE'
}

enum SegmentMode {
  SEGMENT_MODE_UNSPECIFIED = 'SEGMENT_MODE_UNSPECIFIED',
  FOREGROUND = 'FOREGROUND',
  BACKGROUND = 'BACKGROUND',
  PROMPT = 'PROMPT'
}

enum MaskMode {
  USER_PROVIDED = 'USER_PROVIDED',
  BACKGROUND = 'BACKGROUND',
  FOREGROUND = 'FOREGROUND',
  SEMANTIC = 'SEMANTIC'
}

enum ControlType {
  CANNY = 'CANNY',
  SCRIBBLE = 'SCRIBBLE',
  FACE_MESH = 'FACE_MESH'
}

enum SubjectType {
  PERSON = 'PERSON',
  ANIMAL = 'ANIMAL',
  PRODUCT = 'PRODUCT'
}

RAI (Responsible AI) Types

interface Rai {
  /** Whether content was blocked */
  blocked?: boolean;
  /** Reason for blocking */
  blockReason?: string;
  /** Safety scores */
  scores?: number[];
}

Complete Examples

Generate Multiple Images

import { GoogleGenAI, SafetyFilterLevel, PersonGeneration } from '@google/genai';

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

const response = await client.models.generateImages({
  model: 'imagen-3.0-generate-002',
  prompt: 'A cozy coffee shop interior with warm lighting',
  config: {
    numberOfImages: 4,
    aspectRatio: '16:9',
    negativePrompt: 'people, crowded, messy',
    safetyFilterLevel: SafetyFilterLevel.BLOCK_MEDIUM_AND_ABOVE,
    personGeneration: PersonGeneration.DONT_ALLOW,
    outputMimeType: 'image/png'
  }
});

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

Style Transfer with Reference Images

import {
  RawReferenceImage,
  StyleReferenceImage
} from '@google/genai';

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

const contentRef = new RawReferenceImage({
  referenceId: 1,
  referenceImage: {
    data: contentImageData,
    mimeType: 'image/jpeg'
  }
});

const styleRef = new StyleReferenceImage({
  referenceId: 2,
  styleDescription: 'impressionist painting style',
  weight: 0.8,
  referenceImage: {
    data: styleImageData,
    mimeType: 'image/jpeg'
  }
});

const response = await client.models.editImage({
  model: 'imagen-3.0-capability-001',
  prompt: 'Apply artistic style to the image',
  referenceImages: [contentRef, styleRef],
  config: {
    numberOfImages: 2,
    guidanceScale: 7.5
  }
});

Advanced Inpainting

import {
  RawReferenceImage,
  MaskReferenceImage,
  MaskMode,
  EditMode
} from '@google/genai';

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

const rawRef = new RawReferenceImage({
  referenceId: 1,
  referenceImage: {
    data: originalImage,
    mimeType: 'image/jpeg'
  }
});

const maskRef = new MaskReferenceImage({
  referenceId: 1,
  mode: MaskMode.USER_PROVIDED,
  mask: {
    referenceImage: {
      data: maskImage,
      mimeType: 'image/png'
    }
  }
});

// Insert new furniture into room
const response = await client.models.editImage({
  model: 'imagen-3.0-capability-001',
  prompt: 'modern blue sofa with cushions',
  referenceImages: [rawRef, maskRef],
  config: {
    editMode: EditMode.INPAINT_INSERTION,
    numberOfImages: 3,
    negativePrompt: 'old, damaged, dirty',
    guidanceScale: 8.0
  }
});

// Save results
response.generatedImages?.forEach((img, i) => {
  if (img.image?.data) {
    const buffer = Buffer.from(img.image.data, 'base64');
    require('fs').writeFileSync(`result_${i}.png`, buffer);
  }
});

Outpainting (Extend Image Borders)

import {
  RawReferenceImage,
  MaskReferenceImage,
  EditMode
} from '@google/genai';

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

const rawRef = new RawReferenceImage({
  referenceId: 1,
  referenceImage: {
    data: imageData,
    mimeType: 'image/jpeg'
  }
});

// Extend image beyond its borders
const response = await client.models.editImage({
  model: 'imagen-3.0-capability-001',
  prompt: 'continue the landscape naturally',
  referenceImages: [rawRef],
  config: {
    editMode: EditMode.OUTPAINT,
    numberOfImages: 2,
    aspectRatio: '16:9'
  }
});

Subject-Consistent Generation

import { SubjectReferenceImage, SubjectType } from '@google/genai';

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

const subjectRef = new SubjectReferenceImage({
  referenceId: 1,
  subjectType: SubjectType.PRODUCT,
  referenceImage: {
    data: productImageData,
    mimeType: 'image/jpeg'
  }
});

// Generate product in different contexts
const response = await client.models.editImage({
  model: 'imagen-3.0-capability-001',
  prompt: 'show the product on a wooden table with natural lighting',
  referenceImages: [subjectRef],
  config: {
    numberOfImages: 4
  }
});

Semantic Segmentation

import { SegmentMode } from '@google/genai';

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

// Extract specific object
const response = await client.models.segmentImage({
  model: 'imagen-3.0-capability-001',
  image: {
    data: imageData,
    mimeType: 'image/jpeg'
  },
  config: {
    mode: SegmentMode.PROMPT,
    prompt: 'the car'
  }
});

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

Control-Guided Generation

import { ControlReferenceImage, ControlType } from '@google/genai';

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

const controlRef = new ControlReferenceImage({
  referenceId: 1,
  controlType: ControlType.CANNY,
  referenceImage: {
    data: cannyEdgeData,
    mimeType: 'image/png'
  }
});

// Generate image following edge structure
const response = await client.models.editImage({
  model: 'imagen-3.0-capability-001',
  prompt: 'a beautiful house with garden',
  referenceImages: [controlRef],
  config: {
    numberOfImages: 2,
    guidanceScale: 9.0
  }
});

RAI Filtering and Error Handling

import { SafetyFilterLevel } from '@google/genai';

try {
  const response = await client.models.generateImages({
    model: 'imagen-3.0-generate-002',
    prompt: 'a peaceful scene',
    config: {
      numberOfImages: 4,
      safetyFilterLevel: SafetyFilterLevel.BLOCK_MEDIUM_AND_ABOVE,
      includeRaiReason: true
    }
  });

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

  // Check individual images
  response.generatedImages?.forEach((img, index) => {
    if (img.rai?.blocked) {
      console.log(`Image ${index} blocked: ${img.rai.blockReason}`);
    } else if (img.image?.data) {
      console.log(`Image ${index} generated successfully`);
    }
  });
} catch (error) {
  console.error('Generation failed:', error);
}

Install with Tessl CLI

npx tessl i tessl/npm-google--genai

docs

auth-tokens.md

batch.md

caching.md

chat.md

client.md

content-generation.md

embeddings.md

file-search-stores.md

files.md

function-calling.md

image-generation.md

index.md

live.md

mcp.md

models.md

operations.md

tuning.md

video-generation.md

tile.json