or run

npx @tessl/cli init

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

Workspace: tessl
Visibility: Public
Created: 30 days ago
Last updated: 30 days ago
Describes: pkg:npm/@google/genai@1.30.x

To install, run

npx @tessl/cli install tessl/npm-google--genai@1.30.0

Google Gen AI SDK

The Google Gen AI JavaScript SDK is a comprehensive TypeScript and JavaScript library for building applications powered by Gemini, Google's generative AI platform. It provides unified access to both the Gemini Developer API and Vertex AI, supporting Gemini 2.0+ features including content generation, image generation, video generation, function calling, caching, file uploads, and real-time live sessions with multimodal input/output.

Package Information

Package Name: @google/genai
Package Type: npm
Language: TypeScript
Installation: npm install @google/genai
Minimum Node.js Version: 20.0.0

Core Imports

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

For CommonJS:

const { GoogleGenAI } = require('@google/genai');

Platform-specific imports:

// Browser-specific
import { GoogleGenAI } from '@google/genai/web';

// Node.js-specific
import { GoogleGenAI } from '@google/genai/node';

Basic Usage

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

// Initialize with Gemini API (requires API key)
const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// Generate text content
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Explain quantum computing in simple terms'
});

console.log(response.text);

// Generate with streaming
const stream = await client.models.generateContentStream({
  model: 'gemini-2.0-flash',
  contents: 'Write a short story about AI'
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text || '');
}

Architecture

The SDK is built around several key components:

Main Client: GoogleGenAI class provides unified access to all API capabilities
Module System: Specialized modules for different operations (Models, Chats, Files, Caches, Batches, etc.)
Dual API Support: Single interface for both Gemini Developer API and Vertex AI
Platform Abstraction: Cross-platform support for Node.js and browser environments
Type Safety: Full TypeScript integration with 374+ exported types
Streaming Support: AsyncGenerator-based streaming for real-time responses
Automatic Function Calling: Built-in AFC support with configurable iteration limits

Capabilities

Client Initialization

Main entry point for all SDK operations supporting both Gemini Developer API and Vertex AI.

class GoogleGenAI {
  constructor(options?: GoogleGenAIOptions);

  readonly models: Models;
  readonly chats: Chats;
  readonly live: Live;
  readonly batches: Batches;
  readonly caches: Caches;
  readonly files: Files;
  readonly operations: Operations;
  readonly authTokens: Tokens;
  readonly tunings: Tunings;
  readonly fileSearchStores: FileSearchStores;
  readonly vertexai: boolean;
}

interface GoogleGenAIOptions {
  vertexai?: boolean;
  project?: string;
  location?: string;
  apiKey?: string;
  apiVersion?: string;
  googleAuthOptions?: GoogleAuthOptions;
  httpOptions?: HttpOptions;
}

Client Initialization

Content Generation

Core text and multimodal generation capabilities with support for streaming, function calling, and various configuration options.

// Generate content
function generateContent(params: GenerateContentParameters): Promise<GenerateContentResponse>;

// Stream content generation
function generateContentStream(params: GenerateContentParameters): Promise<AsyncGenerator<GenerateContentResponse>>;

interface GenerateContentParameters {
  model: string;
  contents: ContentListUnion;
  config?: GenerateContentConfig;
}

interface GenerateContentResponse {
  candidates?: Candidate[];
  text?: string;
  functionCalls?: FunctionCall[];
  usageMetadata?: UsageMetadata;
  promptFeedback?: PromptFeedback;
  modelVersion?: string;
  automaticFunctionCallingHistory?: Content[];
  sdkHttpResponse?: HttpResponse;
}

Content Generation

Chat Sessions

Multi-turn conversation management with history tracking and streaming support.

function create(params: CreateChatParameters): Chat;

interface CreateChatParameters {
  model: string;
  config?: GenerateContentConfig;
  history?: Content[];
}

class Chat {
  sendMessage(params: SendMessageParameters): Promise<GenerateContentResponse>;
  sendMessageStream(params: SendMessageParameters): Promise<AsyncGenerator<GenerateContentResponse>>;
  getHistory(curated?: boolean): Content[];
}

Chat Sessions

Image Generation

Generate, edit, upscale, and segment images using Imagen models.

// Generate images from text
function generateImages(params: GenerateImagesParameters): Promise<GenerateImagesResponse>;

// Edit images with masks and prompts
function editImage(params: EditImageParameters): Promise<EditImageResponse>;

// Upscale images
function upscaleImage(params: UpscaleImageParameters): Promise<UpscaleImageResponse>;

// Segment images
function segmentImage(params: SegmentImageParameters): Promise<SegmentImageResponse>;

Image Generation

Video Generation

Generate videos from text or image prompts using Veo models (long-running operations).

function generateVideos(params: GenerateVideosParameters): Promise<GenerateVideosOperation>;

interface GenerateVideosOperation {
  name?: string;
  done?: boolean;
  response?: GenerateVideosResponse;
  error?: Status;
  metadata?: GenerateVideosMetadata;
}

Video Generation

Function Calling

Define and use custom functions and tools for extended model capabilities.

interface Tool {
  functionDeclarations?: FunctionDeclaration[];
  codeExecution?: ToolCodeExecution;
  googleSearch?: GoogleSearch;
  retrieval?: Retrieval;
  fileSearch?: FileSearch;
  computerUse?: ComputerUse;
}

interface CallableTool {
  tool(): Promise<Tool>;
  callTool(functionCalls: FunctionCall[]): Promise<Part[]>;
}

interface FunctionDeclaration {
  name?: string;
  description?: string;
  parameters?: Schema;
  parametersJsonSchema?: unknown;
  response?: Schema;
  responseJsonSchema?: unknown;
  behavior?: Behavior;
}

Function Calling

Context Caching

Cache content for improved efficiency and reduced costs on repeated requests.

function create(params: CreateCachedContentParameters): Promise<CachedContent>;
function list(params?: ListCachedContentsParameters): Promise<Pager<CachedContent>>;
function get(params: GetCachedContentParameters): Promise<CachedContent>;
function update(params: UpdateCachedContentParameters): Promise<CachedContent>;
function delete(params: DeleteCachedContentParameters): Promise<DeleteCachedContentResponse>;

interface CachedContent {
  name?: string;
  model?: string;
  createTime?: string;
  updateTime?: string;
  expireTime?: string;
  ttl?: string;
  contents?: Content[];
  tools?: Tool[];
  systemInstruction?: Content;
}

Context Caching

Batch Processing

Process multiple requests efficiently using batch jobs with GCS or BigQuery integration.

function create(params: CreateBatchJobParameters): Promise<BatchJob>;
function createEmbeddings(params: CreateEmbeddingsBatchJobParameters): Promise<BatchJob>;
function list(params?: ListBatchJobsParameters): Promise<Pager<BatchJob>>;
function get(params: GetBatchJobParameters): Promise<BatchJob>;
function cancel(params: CancelBatchJobParameters): Promise<void>;

interface BatchJob {
  name?: string;
  displayName?: string;
  model?: string;
  state?: JobState;
  createTime?: string;
  startTime?: string;
  endTime?: string;
  src?: BatchJobSource;
  config?: BatchJobConfig;
}

Batch Processing

File Management

Upload and manage files for use in generation requests (Gemini API only).

function upload(params: UploadFileParameters): Promise<File>;
function list(params?: ListFilesParameters): Promise<Pager<File>>;
function download(params: DownloadFileParameters): Promise<void>;

interface File {
  name?: string;
  displayName?: string;
  mimeType?: string;
  sizeBytes?: string;
  createTime?: string;
  updateTime?: string;
  expirationTime?: string;
  sha256Hash?: string;
  uri?: string;
  state?: FileState;
  videoMetadata?: VideoMetadata;
}

File Management

Live API (Experimental)

Real-time bidirectional communication with models via WebSocket for multimodal streaming.

function connect(params: LiveConnectParameters): Promise<Session>;

class Session {
  send(message: LiveClientMessage): void;
  sendRealtimeInput(params: LiveSendRealtimeInputParameters): void;
  sendToolResponse(params: LiveSendToolResponseParameters): void;
  close(): void;
}

interface LiveConnectParameters {
  model: string;
  config?: LiveConnectConfig;
  callbacks?: LiveCallbacks;
}

Live API

Embeddings

Generate text embeddings for semantic search and similarity comparison.

function embedContent(params: EmbedContentParameters): Promise<EmbedContentResponse>;

interface EmbedContentParameters {
  model: string;
  contents: ContentListUnion;
  config?: EmbedContentConfig;
}

interface EmbedContentResponse {
  embeddings?: ContentEmbedding[];
}

Embeddings

Model Management

List, retrieve, update, and delete models (especially tuned models).

function list(params?: ListModelsParameters): Promise<Pager<Model>>;
function get(params: GetModelParameters): Promise<Model>;
function update(params: UpdateModelParameters): Promise<Model>;
function delete(params: DeleteModelParameters): Promise<DeleteModelResponse>;

interface Model {
  name?: string;
  baseModelId?: string;
  version?: string;
  displayName?: string;
  description?: string;
  inputTokenLimit?: number;
  outputTokenLimit?: number;
  supportedGenerationMethods?: string[];
}

Model Management

Model Tuning (Experimental)

Fine-tune models with custom training data.

function tune(params: CreateTuningJobParameters): Promise<TuningJob>;
function list(params?: ListTuningJobsParameters): Promise<Pager<TuningJob>>;
function get(params: GetTuningJobParameters): Promise<TuningJob>;

interface TuningJob {
  name?: string;
  tunedModelDisplayName?: string;
  baseModel?: string;
  state?: JobState;
  createTime?: string;
  startTime?: string;
  endTime?: string;
  trainingDataset?: TuningDataset;
  validationDataset?: TuningDataset;
  tunedModel?: string;
}

Model Tuning

File Search Stores

Manage file search stores and documents for enhanced search capabilities during generation (Gemini API only).

function create(params: CreateFileSearchStoreParameters): Promise<FileSearchStore>;
function list(params?: ListFileSearchStoresParameters): Promise<Pager<FileSearchStore>>;
function get(params: GetFileSearchStoreParameters): Promise<FileSearchStore>;
function delete(params: DeleteFileSearchStoreParameters): Promise<void>;
function uploadToFileSearchStore(params: UploadToFileSearchStoreParameters): Promise<UploadToFileSearchStoreOperation>;
function importFile(params: ImportFileParameters): Promise<ImportFileOperation>;

interface FileSearchStores {
  readonly documents: Documents;
}

interface FileSearchStore {
  name?: string;
  displayName?: string;
  createTime?: string;
  updateTime?: string;
}

File Search Stores

Operations

Manage and monitor long-running operations such as video generation and file imports.

function get<T, U extends Operation<T>>(
  parameters: OperationGetParameters<T, U>
): Promise<Operation<T>>;

function getVideosOperation(
  parameters: OperationGetParameters<GenerateVideosResponse, GenerateVideosOperation>
): Promise<GenerateVideosOperation>;

interface Operation<T> {
  name?: string;
  done?: boolean;
  response?: T;
  error?: Status;
  metadata?: Record<string, unknown>;
}

Operations

Authentication Tokens (Experimental)

Create ephemeral authentication tokens for constrained Live API access.

function create(params: CreateAuthTokenParameters): Promise<AuthToken>;

interface AuthToken {
  name?: string;
  uses?: number;
  expireTime?: string;
  usesRemaining?: number;
  createTime?: string;
}

Authentication Tokens

MCP Integration (Experimental)

Model Context Protocol support for extended tool capabilities.

function mcpToTool(
  mcpClientOrTools: McpClient | McpTool[],
  config?: CallableToolConfig
): Promise<CallableTool>;

MCP Integration

Core Types

// Content structure
interface Part {
  text?: string;
  inlineData?: Blob;
  fileData?: FileData;
  functionCall?: FunctionCall;
  functionResponse?: FunctionResponse;
  videoMetadata?: VideoMetadata;
  executableCode?: ExecutableCode;
  codeExecutionResult?: CodeExecutionResult;
  thought?: boolean;
  mediaResolution?: PartMediaResolution;
}

interface Content {
  parts?: Part[];
  role?: string;
}

// Blob and file references
interface Blob {
  mimeType?: string;
  data?: string;
}

interface FileData {
  fileUri?: string;
  mimeType?: string;
}

// Union types for flexible inputs
type PartUnion = Part | string;
type PartListUnion = PartUnion[] | PartUnion;
type ContentUnion = Content | PartUnion[] | PartUnion;
type ContentListUnion = Content | Content[] | PartUnion | PartUnion[];

// Generation configuration
interface GenerateContentConfig {
  temperature?: number;
  topP?: number;
  topK?: number;
  candidateCount?: number;
  maxOutputTokens?: number;
  stopSequences?: string[];
  presencePenalty?: number;
  frequencyPenalty?: number;
  responseModalities?: Modality[];
  systemInstruction?: Content | string;
  tools?: ToolListUnion;
  toolConfig?: ToolConfig;
  safetySettings?: SafetySetting[];
  cachedContent?: string;
  automaticFunctionCalling?: AutomaticFunctionCallingConfig;
  thinkingConfig?: ThinkingConfig;
  responseSchema?: Schema;
  responseJsonSchema?: unknown;
  responseMimeType?: string;
  httpOptions?: HttpOptions;
  abortSignal?: AbortSignal;
}

// Safety configuration
interface SafetySetting {
  category?: HarmCategory;
  threshold?: HarmBlockThreshold;
  method?: HarmBlockMethod;
}

interface SafetyRating {
  category?: HarmCategory;
  probability?: HarmProbability;
  blocked?: boolean;
  probabilityScore?: number;
  severity?: HarmSeverity;
  severityScore?: number;
}

// Usage metadata
interface UsageMetadata {
  promptTokenCount?: number;
  candidatesTokenCount?: number;
  totalTokenCount?: number;
  cachedContentTokenCount?: number;
}

// HTTP configuration
interface HttpOptions {
  baseUrl?: string;
  apiVersion?: string;
  headers?: Record<string, string>;
  timeout?: number;
  extraBody?: Record<string, unknown>;
}

interface HttpResponse {
  headers?: Record<string, string>;
  status?: number;
}

// Schema for structured outputs
interface Schema {
  type?: Type;
  format?: string;
  description?: string;
  nullable?: boolean;
  enum?: string[];
  items?: Schema;
  properties?: Record<string, Schema>;
  required?: string[];
  maxItems?: string;
  minItems?: string;
  propertyOrdering?: string[];
}

Enumerations

// Content modalities
enum Modality {
  TEXT = 'TEXT',
  IMAGE = 'IMAGE',
  AUDIO = 'AUDIO'
}

// Finish reasons
enum FinishReason {
  FINISH_REASON_UNSPECIFIED = 'FINISH_REASON_UNSPECIFIED',
  STOP = 'STOP',
  MAX_TOKENS = 'MAX_TOKENS',
  SAFETY = 'SAFETY',
  RECITATION = 'RECITATION',
  OTHER = 'OTHER',
  BLOCKLIST = 'BLOCKLIST',
  PROHIBITED_CONTENT = 'PROHIBITED_CONTENT',
  SPII = 'SPII',
  MALFORMED_FUNCTION_CALL = 'MALFORMED_FUNCTION_CALL'
}

// Harm categories
enum HarmCategory {
  HARM_CATEGORY_UNSPECIFIED = 'HARM_CATEGORY_UNSPECIFIED',
  HARM_CATEGORY_HATE_SPEECH = 'HARM_CATEGORY_HATE_SPEECH',
  HARM_CATEGORY_SEXUALLY_EXPLICIT = 'HARM_CATEGORY_SEXUALLY_EXPLICIT',
  HARM_CATEGORY_HARASSMENT = 'HARM_CATEGORY_HARASSMENT',
  HARM_CATEGORY_DANGEROUS_CONTENT = 'HARM_CATEGORY_DANGEROUS_CONTENT',
  HARM_CATEGORY_CIVIC_INTEGRITY = 'HARM_CATEGORY_CIVIC_INTEGRITY',
  HARM_CATEGORY_IMAGE_HATE = 'HARM_CATEGORY_IMAGE_HATE',
  HARM_CATEGORY_IMAGE_DANGEROUS_CONTENT = 'HARM_CATEGORY_IMAGE_DANGEROUS_CONTENT',
  HARM_CATEGORY_IMAGE_HARASSMENT = 'HARM_CATEGORY_IMAGE_HARASSMENT',
  HARM_CATEGORY_IMAGE_SEXUALLY_EXPLICIT = 'HARM_CATEGORY_IMAGE_SEXUALLY_EXPLICIT',
  HARM_CATEGORY_JAILBREAK = 'HARM_CATEGORY_JAILBREAK'
}

// Harm block thresholds
enum HarmBlockThreshold {
  HARM_BLOCK_THRESHOLD_UNSPECIFIED = 'HARM_BLOCK_THRESHOLD_UNSPECIFIED',
  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',
  OFF = 'OFF'
}

// Harm probabilities
enum HarmProbability {
  HARM_PROBABILITY_UNSPECIFIED = 'HARM_PROBABILITY_UNSPECIFIED',
  NEGLIGIBLE = 'NEGLIGIBLE',
  LOW = 'LOW',
  MEDIUM = 'MEDIUM',
  HIGH = 'HIGH'
}

// Schema types
enum Type {
  TYPE_UNSPECIFIED = 'TYPE_UNSPECIFIED',
  STRING = 'STRING',
  NUMBER = 'NUMBER',
  INTEGER = 'INTEGER',
  BOOLEAN = 'BOOLEAN',
  ARRAY = 'ARRAY',
  OBJECT = 'OBJECT',
  NULL = 'NULL'
}

// Programming languages
enum Language {
  LANGUAGE_UNSPECIFIED = 'LANGUAGE_UNSPECIFIED',
  PYTHON = 'PYTHON'
}

// Function calling modes
enum FunctionCallingConfigMode {
  MODE_UNSPECIFIED = 'MODE_UNSPECIFIED',
  AUTO = 'AUTO',
  ANY = 'ANY',
  NONE = 'NONE',
  VALIDATED = 'VALIDATED'
}

// Function behavior
enum Behavior {
  BEHAVIOR_UNSPECIFIED = 'BEHAVIOR_UNSPECIFIED',
  BLOCKING = 'BLOCKING',
  NON_BLOCKING = 'NON_BLOCKING'
}

// Job states
enum JobState {
  JOB_STATE_UNSPECIFIED = 'JOB_STATE_UNSPECIFIED',
  JOB_STATE_QUEUED = 'JOB_STATE_QUEUED',
  JOB_STATE_PENDING = 'JOB_STATE_PENDING',
  JOB_STATE_RUNNING = 'JOB_STATE_RUNNING',
  JOB_STATE_SUCCEEDED = 'JOB_STATE_SUCCEEDED',
  JOB_STATE_FAILED = 'JOB_STATE_FAILED',
  JOB_STATE_CANCELLING = 'JOB_STATE_CANCELLING',
  JOB_STATE_CANCELLED = 'JOB_STATE_CANCELLED',
  JOB_STATE_PAUSED = 'JOB_STATE_PAUSED',
  JOB_STATE_EXPIRED = 'JOB_STATE_EXPIRED',
  JOB_STATE_UPDATING = 'JOB_STATE_UPDATING',
  JOB_STATE_PARTIALLY_SUCCEEDED = 'JOB_STATE_PARTIALLY_SUCCEEDED'
}

// File states
enum FileState {
  STATE_UNSPECIFIED = 'STATE_UNSPECIFIED',
  PROCESSING = 'PROCESSING',
  ACTIVE = 'ACTIVE',
  FAILED = 'FAILED'
}

Helper Functions

// Part creation helpers
function createPartFromText(text: string): Part;
function createPartFromUri(
  uri: string,
  mimeType: string,
  mediaResolution?: PartMediaResolutionLevel
): Part;
function createPartFromBase64(
  data: string,
  mimeType: string,
  mediaResolution?: PartMediaResolutionLevel
): Part;
function createPartFromFunctionCall(
  name: string,
  args: Record<string, unknown>
): Part;
function createPartFromFunctionResponse(
  id: string,
  name: string,
  response: Record<string, unknown>,
  parts?: FunctionResponsePart[]
): Part;
function createPartFromCodeExecutionResult(
  outcome: Outcome,
  output: string
): Part;
function createPartFromExecutableCode(
  code: string,
  language: Language
): Part;

// Content creation helpers
function createUserContent(partOrString: PartListUnion | string): Content;
function createModelContent(partOrString: PartListUnion | string): Content;

// FunctionResponsePart creation helpers
function createFunctionResponsePartFromBase64(
  data: string,
  mimeType: string
): FunctionResponsePart;
function createFunctionResponsePartFromUri(
  uri: string,
  mimeType: string
): FunctionResponsePart;

// Base URL configuration
function setDefaultBaseUrls(baseUrlParams: BaseUrlParameters): void;
function getDefaultBaseUrls(): BaseUrlParameters;

interface BaseUrlParameters {
  vertexBaseUrl?: string;
  geminiBaseUrl?: string;
}

Pagination

class Pager<T> implements AsyncIterable<T> {
  readonly page: T[];
  readonly pageSize: number;
  readonly pageLength: number;
  readonly name: PagedItem;
  readonly params: PagedItemConfig;
  readonly sdkHttpResponse?: HttpResponse;

  [Symbol.asyncIterator](): AsyncIterator<T>;
  nextPage(): Promise<T[]>;
  hasNextPage(): boolean;
  getItem(index: number): T;
}

enum PagedItem {
  PAGED_ITEM_BATCH_JOBS = 'PAGED_ITEM_BATCH_JOBS',
  PAGED_ITEM_MODELS = 'PAGED_ITEM_MODELS',
  PAGED_ITEM_TUNING_JOBS = 'PAGED_ITEM_TUNING_JOBS',
  PAGED_ITEM_FILES = 'PAGED_ITEM_FILES',
  PAGED_ITEM_CACHED_CONTENTS = 'PAGED_ITEM_CACHED_CONTENTS',
  PAGED_ITEM_FILE_SEARCH_STORES = 'PAGED_ITEM_FILE_SEARCH_STORES',
  PAGED_ITEM_DOCUMENTS = 'PAGED_ITEM_DOCUMENTS'
}

Error Handling

class ApiError extends Error {
  message: string;
  status: number;
  name: 'ApiError';
}

interface ApiErrorInfo {
  message: string;
  status: number;
}

Constants

const SDK_VERSION: string = '1.30.0';
const GOOGLE_API_CLIENT_HEADER: string = 'x-goog-api-client';

Version

Tile

Files

tessl/npm-google--genai

To install, run

index.mddocs/

Google Gen AI SDK

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Client Initialization

Content Generation

Chat Sessions

Image Generation

Video Generation

Function Calling

Context Caching

Batch Processing

File Management

Live API (Experimental)

Embeddings

Model Management

Model Tuning (Experimental)

File Search Stores

Operations

Authentication Tokens (Experimental)

MCP Integration (Experimental)

Core Types

Enumerations

Helper Functions

Pagination

Error Handling

Constants

Version

Tile

Files

tessl/npm-google--genai

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Google Gen AI SDK

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Client Initialization

Content Generation

Chat Sessions

Image Generation

Video Generation

Function Calling

Context Caching

Batch Processing

File Management

Live API (Experimental)

Embeddings

Model Management

Model Tuning (Experimental)

File Search Stores

Operations

Authentication Tokens (Experimental)

MCP Integration (Experimental)

Core Types

Enumerations

Helper Functions

Pagination

Error Handling

Constants

index.mddocs/