### Run GenAI SDK TypeScript Web Sample

Source: https://github.com/googleapis/js-genai/blob/main/sdk-samples/web/README.md

Use these commands to install dependencies and start the development server for the sample web application.

```bash
npm install
npm run dev
```

--------------------------------

### Build SDK and samples

Source: https://github.com/googleapis/js-genai/blob/main/sdk-samples/README.md

Build the `@google/genai/node` SDK and its samples by installing dependencies and running the build scripts.

```sh
# Build the SDK
npm install
npm run build

# Build the samples
cd sdk-samples
npm install
npm run build
```

--------------------------------

### Install GoogleGenAI SDK with npm

Source: https://github.com/googleapis/js-genai/blob/main/README.md

Run this command to install the GoogleGenAI SDK package into your Node.js project.

```shell
npm install @google/genai
```

--------------------------------

### Interface: LiveMusicServerSetupComplete

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai.api.md

Indicates that the live music server setup process is complete.

```APIDOC
## Interface: LiveMusicServerSetupComplete

### Description
Indicates that the live music server setup process is complete.

### Properties
(No properties explicitly documented in source)
```

--------------------------------

### Quickstart: Generate Content using GoogleGenAI SDK and API Key

Source: https://github.com/googleapis/js-genai/blob/main/README.md

Initialize the GoogleGenAI SDK with an API key and make a content generation request to a Gemini model.

```typescript
import {GoogleGenAI} from '@google/genai';
const GEMINI_API_KEY = process.env.GEMINI_API_KEY;

const ai = new GoogleGenAI({apiKey: GEMINI_API_KEY});

async function main() {
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'Why is the sky blue?',
  });
  console.log(response.text);
}

main();
```

--------------------------------

### Generate Content with Gemini API Key (Quickstart)

Source: https://github.com/googleapis/js-genai/blob/main/docs/index.html

Initializes the SDK with an API key and demonstrates generating text content using a Gemini model.

```typescript
import {GoogleGenAI} from '@google/genai';const GEMINI_API_KEY = process.env.GEMINI_API_KEY;const ai = new GoogleGenAI({apiKey: GEMINI_API_KEY});async function main() {  const response = await ai.models.generateContent({    model: 'gemini-2.0-flash-001',    contents: 'Why is the sky blue?',  });  console.log(response.text);}main();
```

--------------------------------

### List All Project Files (JavaScript)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/files.Files.html

Lists all files associated with the current project, paginating results with a page size of 10. The example iterates and prints each file's name.

```JavaScript
const listResponse = await ai.files.list({config: {'pageSize': 10}});for await (const file of listResponse) {  console.log(file.name);}
```

--------------------------------

### Run samples directly in development using tsx

Source: https://github.com/googleapis/js-genai/blob/main/sdk-samples/README.md

Install dependencies and execute samples directly against the source code using `tsx` with a development configuration.

```sh
# Install dependencies
npm install --registry=https://registry.npmjs.org
cd sdk-samples
npm install --registry=https://registry.npmjs.org

# Run any sample directly using tsx and the dev config
npx tsx --tsconfig tsconfig.dev.json <sample_name>.ts
```

--------------------------------

### Interface: LiveServerSetupComplete

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai.api.md

Indicates that the live server setup is complete, often including a session ID.

```APIDOC
## Interface: LiveServerSetupComplete

### Description
Indicates that the live server setup is complete, often including a session ID.

### Properties
- **sessionId** (string) - Optional - The ID of the session.
```

--------------------------------

### Get Model Information (JavaScript)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/models.Models.html

Fetches information for a specific model by its name. This example retrieves details for 'gemini-2.0-flash'.

```javascript
const modelInfo = await ai.models.get({model: 'gemini-2.0-flash'});
```

--------------------------------

### Set System Instructions for Content Generation in JavaScript

Source: https://github.com/googleapis/js-genai/blob/main/codegen_instructions.md

Guides the model's behavior by providing a `systemInstruction` within the configuration, influencing the style or persona of the generated response.

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

const ai = new GoogleGenAI({});

async function run() {
    const response = await ai.models.generateContent({
        model: 'gemini-3-flash-preview',
        contents: "Explain quantum physics.",
        config: {
            systemInstruction: "You are a pirate",
        }
    });
    console.log(response.text);
}
run();
```

--------------------------------

### LiveMusicSession.play()

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-web.api.md

Resumes or starts the live music generation and playback within the session.

```APIDOC
## play()

### Description
Resumes or starts the live music generation and playback within the session.

### Signature
`play(): void`

### Parameters
(None)

### Returns
`void` - This method does not return any value.
```

--------------------------------

### Generate Images with generateImages (TypeScript)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/models.Models.html

This example shows how to generate an image from a text prompt using the 'imagen-3.0-generate-002' model and retrieve the image bytes.

```typescript
const response = await client.models.generateImages({ model: 'imagen-3.0-generate-002', prompt: 'Robot holding a red skateboard', config: {   numberOfImages: 1,   includeRaiReason: true, },});console.log(response?.generatedImages?.[0]?.image?.imageBytes);
```

--------------------------------

### Example JSON Output for Cookie Recipes

Source: https://github.com/googleapis/js-genai/blob/main/codegen_instructions.md

Illustrates the expected JSON structure returned by the model when using the structured output configuration for cookie recipes.

```json
[
  {
    "recipeName": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
    ]
  },
  ...
]
```

--------------------------------

### Integrate Model Context Protocol (MCP) Tools with GoogleGenAI

Source: https://github.com/googleapis/js-genai/blob/main/README.md

This experimental feature allows passing a local MCP server as a tool. The example demonstrates connecting to an MCP server using StdioClientTransport and Client, then using mcpToTool to include it in the generateContent request.

```javascript
import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai';
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create server parameters for stdio connection
const serverParams = new StdioClientTransport({
  command: "npx", // Executable
  args: ["-y", "@philschmid/weather-mcp"] // MCP Server
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

// Configure the client
const ai = new GoogleGenAI({});

// Initialize the connection between client and server
await client.connect(serverParams);

// Send request to the model with MCP tools
const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`,
  config: {
    tools: [mcpToTool(client)],  // uses the session, will automatically call the tool using automatic function calling
  },
});
console.log(response.text);

// Close the connection
await client.close();
```

--------------------------------

### Implement Function Calling with GoogleGenAI

Source: https://github.com/googleapis/js-genai/blob/main/README.md

Enable Gemini to interact with external systems by providing functionDeclaration objects as tools. This example shows how to define a function, configure generateContent with toolConfig, and inspect the functionCalls in the response.

```typescript
import {GoogleGenAI, FunctionCallingConfigMode, FunctionDeclaration, Type} from '@google/genai';
const GEMINI_API_KEY = process.env.GEMINI_API_KEY;

async function main() {
  const controlLightDeclaration: FunctionDeclaration = {
    name: 'controlLight',
    parametersJsonSchema: {
      type: 'object',
      properties:{
        brightness: {
          type:'number',
        },
        colorTemperature: {
          type:'string',
        },
      },
      required: ['brightness', 'colorTemperature'],
    },
  };

  const ai = new GoogleGenAI({apiKey: GEMINI_API_KEY});
  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'Dim the lights so the room feels cozy and warm.',
    config: {
      toolConfig: {
        functionCallingConfig: {
          // Force it to call any function
          mode: FunctionCallingConfigMode.ANY,
          allowedFunctionNames: ['controlLight'],
        }
      },
      tools: [{functionDeclarations: [controlLightDeclaration]}]
    }
  });

  console.log(response.functionCalls);
}

main();
```

--------------------------------

### Iterating Through Paginated Results with Pager

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/pagers.Pager.html

This example demonstrates how to fetch and process all pages of items using the `Pager` class. It continuously fetches the next page until `hasNextPage()` returns false.

```javascript
const pager = await ai.files.list({config: {pageSize: 10}});let page = pager.page;while (true) {  for (const file of page) {    console.log(file.name);  }  if (!pager.hasNextPage()) {    break;  }  page = await pager.nextPage();}
```

--------------------------------

### get(params: GetCachedContentParameters): Promise<CachedContent>

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/caches.Caches.html

Gets cached content configurations.

```APIDOC
## Method: get(params: GetCachedContentParameters): Promise<CachedContent>

### Description
Gets cached content configurations.

### Parameters
- **params** ([GetCachedContentParameters](../interfaces/types.GetCachedContentParameters.html)) - The parameters for the get request.

### Returns
Promise<[CachedContent](../interfaces/types.CachedContent.html)> - The cached content.

### Example
```typescript
await ai.caches.get({name: '...'}); // The server-generated resource name.
```
```

--------------------------------

### get(params: types.GetFileParameters)

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-web.api.md

Retrieves information about a specific file.

```APIDOC
## get(params: types.GetFileParameters)

### Description
Retrieves information about a specific file.

### Signature
```typescript
get(params: types.GetFileParameters): Promise<types.File>;
```

### Parameters
- **params** (types.GetFileParameters) - Required - Parameters for getting file information.

### Returns
- **Promise<types.File>** - A promise that resolves to the file object.
```

--------------------------------

### new Live(apiClient: ApiClient, auth: Auth, webSocketFactory: WebSocketFactory)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/live.Live.html

Initializes a new instance of the Live class with API client, authentication, and a WebSocket factory.

```APIDOC
## constructor

### Description
Initializes a new instance of the Live class with API client, authentication, and a WebSocket factory.

### Parameters
- **apiClient** (ApiClient) - Required - The API client for general API settings.
- **auth** (Auth) - Required - The authentication object.
- **webSocketFactory** (WebSocketFactory) - Required - The factory for creating WebSocket connections.

### Returns
- **Live** - An instance of the Live class.
```

--------------------------------

### Chat.sendMessage

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai.api.md

Sends a message in the chat and gets a single response.

```APIDOC
## Chat.sendMessage

### Description
Sends a message to the chat and awaits a single response.

### Method Signature
`sendMessage(params: types.SendMessageParameters): Promise<types.GenerateContentResponse>;`

### Parameters
- **params** (types.SendMessageParameters) - Required - Parameters for sending the message.

### Returns
`Promise<types.GenerateContentResponse>` - A promise that resolves to the generated content response.
```

--------------------------------

### get(params: GetFileParameters)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/files.Files.html

Retrieves the file information from the service.

```APIDOC
## get

### Description
Retrieves the file information from the service.

### Signature
```typescript
get(params: GetFileParameters): Promise<File>
```

### Parameters
- **params** (GetFileParameters) - The parameters for the get request

### Returns
Promise<File> - The Promise that resolves to the types.File object requested.

### Example
```typescript
const config: GetFileParameters = {  name: fileName,};file = await ai.files.get(config);console.log(file.name);
```
```

--------------------------------

### new ApiClient(opts: ApiClientInitOptions)

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-vertex-internal.api.md

Initializes a new instance of the `ApiClient` for interacting with the GenAI API. This constructor sets up the client with necessary authentication, upload, and download mechanisms.

```APIDOC
## Method: `new ApiClient(opts: ApiClientInitOptions)`

### Description
Initializes a new instance of the `ApiClient` for interacting with the GenAI API. This constructor sets up the client with necessary authentication, upload, and download mechanisms.

### Signature
```typescript
new ApiClient(opts: ApiClientInitOptions)
```

### Parameters
- **opts** (ApiClientInitOptions) - Required - Configuration options for the API client, including API key, authentication, and service settings.

### Returns
- **ApiClient** - A new instance of the `ApiClient`.
```

--------------------------------

### name

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/pagers.Pager.html

Returns the type of paged item (for example, `batch_jobs`).

```APIDOC
## name\n\n### Description\nReturns the type of paged item (for example, `batch_jobs`).\n\n### Method\nget name(): PagedItem\n\n### Returns\nPagedItem
```

--------------------------------

### get functionCalls()

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/types.GenerateContentResponse.html

Returns the function calls from the first candidate in the response.

```APIDOC
## get functionCalls()

### Description
Returns the function calls from the first candidate in the response. If there are multiple candidates in the response, the function calls from the first one will be returned. If there are no function calls in the response, undefined will be returned.

### Returns
- **undefined | FunctionCall[]** - An array of function calls or undefined.

### Example
```javascript
const controlLightFunctionDeclaration: FunctionDeclaration = {  name: 'controlLight',  parameters: {  type: Type.OBJECT,  description: 'Set the brightness and color temperature of a room light.',  properties: {    brightness: {      type: Type.NUMBER,      description:        'Light level from 0 to 100. Zero is off and 100 is full brightness.',    },    colorTemperature: {      type: Type.STRING,      description:        'Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.',    },  },  required: ['brightness', 'colorTemperature'], }; const response = await ai.models.generateContent({    model: 'gemini-2.0-flash',    contents: 'Dim the lights so the room feels cozy and warm.',    config: {      tools: [{functionDeclarations: [controlLightFunctionDeclaration]}],      toolConfig: {        functionCallingConfig: {          mode: FunctionCallingConfigMode.ANY,          allowedFunctionNames: ['controlLight'],        },      },    },  }); console.debug(JSON.stringify(response.functionCalls));
```
```

--------------------------------

### LiveClientSetup Interface Definition

Source: https://github.com/googleapis/js-genai/blob/main/docs/interfaces/types.LiveClientSetup.html

Defines the configuration parameters for a streaming session, used to set up various aspects like generation, audio processing, and model selection.

```APIDOC
## Interface LiveClientSetup

### Description
Message contains configuration that will apply for the duration of the streaming session.

### Properties
- **contextWindowCompression** (ContextWindowCompressionConfig) - Optional - Configures context window compression mechanism. If included, server will compress context window to fit into given length.
- **generationConfig** (GenerationConfig) - Optional - The generation configuration for the session. Note: only a subset of fields are supported.
- **inputAudioTranscription** (AudioTranscriptionConfig) - Optional - The transcription of the input aligns with the input audio language.
- **model** (string) - Optional - The fully qualified name of the publisher model or tuned model endpoint to use.
- **outputAudioTranscription** (AudioTranscriptionConfig) - Optional - The transcription of the output aligns with the language code specified for the output audio.
- **proactivity** (ProactivityConfig) - Optional - Configures the proactivity of the model. This allows the model to respond proactively to the input and to ignore irrelevant input.
- **realtimeInputConfig** (RealtimeInputConfig) - Optional - Configures the realtime input behavior in BidiGenerateContent.
- **sessionResumption** (SessionResumptionConfig) - Optional - Configures session resumption mechanism. If included server will send SessionResumptionUpdate messages.
```

--------------------------------

### Initialize SDK with Gemini API Key (Server-side)

Source: https://github.com/googleapis/js-genai/blob/main/docs/index.html

Initializes the SDK for server-side applications using an API key from Google AI Studio.

```typescript
import { GoogleGenAI } from '@google/genai';const ai = new GoogleGenAI({apiKey: 'GEMINI_API_KEY'});
```

--------------------------------

### get(params: GetModelParameters): Promise<Model>

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/models.Models.html

Fetches information about a model by name.

```APIDOC
## get

### Description
Fetches information about a model by name.

### Method Signature
get(params: GetModelParameters): Promise<Model>

### Parameters
- **params** (GetModelParameters) - Required - Parameters for fetching the model.

### Example
```typescript
const modelInfo = await ai.models.get({model: 'gemini-2.0-flash'});
```

### Returns
Promise<Model> - A promise that resolves to the Model information.
```

--------------------------------

### get text()

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/types.GenerateContentResponse.html

Returns the concatenation of all text parts from the first candidate in the response.

```APIDOC
## get text()

### Description
Returns the concatenation of all text parts from the first candidate in the response. If there are multiple candidates in the response, the text from the first one will be returned. If there are non-text parts in the response, the concatenation of all text parts will be returned, and a warning will be logged. If there are thought parts in the response, the concatenation of all text parts excluding the thought parts will be returned.

### Returns
- **undefined | string** - The concatenated text or undefined.

### Example
```javascript
const response = await ai.models.generateContent({  model: 'gemini-2.0-flash',  contents:    'Why is the sky blue?',});console.debug(response.text);
```
```

--------------------------------

### Live.connect(params: types.LiveConnectParameters)

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-node.api.md

Establishes a live session with the GenAI service, enabling real-time communication and interaction. This method returns a Promise that resolves to a `Session` object upon successful connection.

```APIDOC
## Live.connect(params: types.LiveConnectParameters)

### Description
Establishes a live session with the GenAI service, enabling real-time communication and interaction. This method returns a Promise that resolves to a `Session` object upon successful connection.

### Method
SDK Method

### Endpoint
Live.connect

### Parameters
#### Request Body
- **params** (types.LiveConnectParameters) - Required - Parameters for establishing the live connection.
    - **callbacks** (LiveCallbacks) - Required - Callbacks for handling connection events.
        - **onclose** ((e: CloseEvent) => void) - Optional - Callback for when the connection closes.
        - **onerror** ((e: ErrorEvent) => void) - Optional - Callback for connection errors.
        - **onmessage** ((e: LiveServerMessage) => void) - Required - Callback for incoming messages from the server.
        - **onopen** (() => void) - Optional - Callback for when the connection opens.
    - **config** (LiveConnectConfig) - Optional - Configuration settings for the live session.
        - **abortSignal** (AbortSignal) - Optional - An AbortSignal to cancel the connection attempt.
        - **avatarConfig** (AvatarConfig) - Optional - Configuration for avatar behavior.
        - **contextWindowCompression** (ContextWindowCompressionConfig) - Optional - Configuration for context window compression.
        - **enableAffectiveDialog** (boolean) - Optional - Whether to enable affective dialog.
        - **explicitVadSignal** (boolean) - Optional - Whether to use explicit Voice Activity Detection (VAD) signals.
        - **generationConfig** (GenerationConfig) - Optional - Configuration for content generation.
        - **httpOptions** (HttpOptions) - Optional - HTTP options for the connection.
        - **inputAudioTranscription** (AudioTranscriptionConfig) - Optional - Configuration for input audio transcription.
        - **maxOutputTokens** (number) - Optional - Maximum number of output tokens.
        - **mediaResolution** (MediaResolution) - Optional - Resolution settings for media.
        - **outputAudioTranscription** (AudioTranscriptionConfig) - Optional - Configuration for output audio transcription.
        - **proactivity** (ProactivityConfig) - Optional - Configuration for proactivity.
        - **realtimeInputConfig** (RealtimeInputConfig) - Optional - Configuration for real-time input.
        - **responseModalities** (Modality[]) - Optional - Desired response modalities.
        - **safetySettings** (SafetySetting[]) - Optional - Safety settings for content generation.
        - **seed** (number) - Optional - Seed for reproducible generation.
        - **sessionResumption** (SessionResumptionConfig) - Optional - Configuration for session resumption.
        - **speechConfig** (SpeechConfig) - Optional - Configuration for speech synthesis.
        - **systemInstruction** (ContentUnion) - Optional - System instructions for the model.
        - **temperature** (number) - Optional - Controls the randomness of the output.
        - **thinkingConfig** (ThinkingConfig) - Optional - Configuration for thinking behavior.
        - **tools** (ToolListUnion) - Optional - List of tools available to the model.
        - **topK** (number) - Optional - Top-k sampling parameter.
        - **topP** (number) - Optional - Top-p sampling parameter.
        - **translationConfig** (TranslationConfig) - Optional - Configuration for translation.
    - **model** (string) - Required - The model identifier to use for the live session.

### Response
#### Success Response (Promise<Session>)
A Promise that resolves to a `Session` object upon successful connection.
```

--------------------------------

### Set environment variables for samples

Source: https://github.com/googleapis/js-genai/blob/main/sdk-samples/README.md

Configure necessary environment variables like API key, Google Cloud project, and location before running samples.

```sh
export GEMINI_API_KEY=<GEMINI_KEY>
export GOOGLE_CLOUD_PROJECT=<GOOGLE_CLOUD_PROJECT>
export GOOGLE_CLOUD_LOCATION=<GCP_REGION>
```

--------------------------------

### get executableCode()

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/types.GenerateContentResponse.html

Returns the first executable code from the first candidate in the response.

```APIDOC
## get executableCode()

### Description
Returns the first executable code from the first candidate in the response. If there are multiple candidates in the response, the executable code from the first one will be returned. If there are no executable code in the response, undefined will be returned.

### Returns
- **undefined | string** - The executable code or undefined.

### Example
```javascript
const response = await ai.models.generateContent({  model: 'gemini-2.0-flash',  contents:    'What is the sum of the first 50 prime numbers? Generate and run code for the calculation, and make sure you get all 50.'  config: {    tools: [{codeExecution: {}}],  },});console.debug(response.executableCode);
```
```

--------------------------------

### get(params: types.GetBatchJobParameters)

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-node.api.md

Retrieves the details of a specific batch job by its identifier.

```APIDOC
## get(params: types.GetBatchJobParameters)

### Description
Retrieves the details of a specific batch job by its identifier.

### Method Signature
`get(params: types.GetBatchJobParameters): Promise<types.BatchJob>`

### Parameters
#### `params` (types.GetBatchJobParameters) - Required - Parameters for getting a batch job.
```

--------------------------------

### Run a compiled sample

Source: https://github.com/googleapis/js-genai/blob/main/sdk-samples/README.md

Execute a specific compiled sample using Node.js after building the project and setting environment variables.

```sh
node build/generate_content_with_text.js
```

--------------------------------

### new Session()

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-web.api.md

Initializes a new Session instance, establishing a connection for real-time interactions with the GenAI service.

```APIDOC
## new Session()

### Description
Initializes a new Session instance, establishing a connection for real-time interactions with the GenAI service.

### Method Signature
```typescript
constructor(conn: WebSocket_2, apiClient: ApiClient);
```

### Parameters
- **conn** (WebSocket_2) - The WebSocket connection to use for the session.
- **apiClient** (ApiClient) - The API client for making requests.

### Example Usage
```typescript
// Assuming 'myWebSocket' and 'myApiClient' are pre-configured instances
const session = new Session(myWebSocket, myApiClient);
```
```

--------------------------------

### Initialize SDK for Vertex AI

Source: https://github.com/googleapis/js-genai/blob/main/docs/index.html

Initializes the SDK for Vertex AI, requiring project ID and location configuration.

```typescript
import { GoogleGenAI } from '@google/genai';const ai = new GoogleGenAI({    vertexai: true,    project: 'your_project',    location: 'your_location',});
```

--------------------------------

### Initialize GoogleGenAI Client (Node.js)

Source: https://github.com/googleapis/js-genai/blob/main/docs/index.html

Imports and initializes the `GoogleGenAI` client without specific API version or Vertex AI configuration.

```JavaScript
import {GoogleGenAI} from '@google/genai';const ai = new GoogleGenAI();
```

--------------------------------

### Get Cached Content (TypeScript)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/caches.Caches.html

Retrieve a specific cached content configuration by providing its server-generated resource name.

```typescript
await ai.caches.get({name: '...'}); // The server-generated resource name.
```

--------------------------------

### Retrieve File Information (JavaScript)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/files.Files.html

Retrieves metadata for a specific file from the service. The example logs the name of the retrieved file.

```JavaScript
const config: GetFileParameters = {  name: fileName,};file = await ai.files.get(config);console.log(file.name);
```

--------------------------------

### Initialize GoogleGenAI with API Key (JavaScript)

Source: https://github.com/googleapis/js-genai/blob/main/codegen_instructions.md

Create an instance of `GoogleGenAI` to interact with the Gemini API. It automatically uses the `GEMINI_API_KEY` environment variable in Node.js, or an explicit key can be provided.

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

// Best practice: implicitly use GEMINI_API_KEY env variable
const ai = new GoogleGenAI({});

// Alternative: explicit key (avoid hardcoding in production)
// const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
```

--------------------------------

### connect(params: LiveConnectParameters)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/live.Live.html

Establishes a connection to the specified model with the given configuration and returns a Session object representing that connection. Built-in MCP support is an experimental feature, may change in future versions.

```APIDOC
## connect

### Description
Establishes a connection to the specified model with the given configuration and returns a Session object representing that connection. Built-in MCP support is an experimental feature, may change in future versions.

### Method Signature
connect(params: LiveConnectParameters): Promise<Session>

### Parameters
- **params** (LiveConnectParameters) - Required - The parameters for establishing a connection to the model.

### Returns
- **Promise<Session>** - A live session.

### Request Example
```typescript
let model: string;
if (GOOGLE_GENAI_USE_VERTEXAI) {
  model = 'gemini-2.0-flash-live-preview-04-09';
} else {
  model = 'gemini-live-2.5-flash-preview';
}
const session = await ai.live.connect({
  model: model,
  config: {
    responseModalities: [Modality.AUDIO],
  },
  callbacks: {
    onopen: () => {
      console.log('Connected to the socket.');
    },
    onmessage: (e: MessageEvent) => {
      console.log('Received message from the server: %s\n', debug(e.data));
    },
    onerror: (e: ErrorEvent) => {
      console.log('Error occurred: %s\n', debug(e.error));
    },
    onclose: (e: CloseEvent) => {
      console.log('Connection closed.');
    },
  },
});
```
```

--------------------------------

### Delete a File (JavaScript)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/files.Files.html

Deletes a remotely stored file using its name. This example deletes a file named "files/mehozpxf877d".

```JavaScript
await ai.files.delete({name: file.name});
```

--------------------------------

### Live.connect

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-web.api.md

Establishes a live session connection, allowing real-time interaction with the generative AI model.

```APIDOC
## Live.connect

### Description
Establishes a live session connection, allowing real-time interaction with the generative AI model.

### Method Signature
`connect(params: LiveConnectParameters): Promise<Session>`

### Parameters
- **params** (LiveConnectParameters) - Required - Configuration for the live session connection.
  - **callbacks** (LiveCallbacks) - Required - Callbacks for handling connection events.
    - **onclose** ((e: CloseEvent) => void | null) - Optional - Callback for when the connection closes.
    - **onerror** ((e: ErrorEvent) => void | null) - Optional - Callback for when an error occurs.
    - **onmessage** ((e: LiveServerMessage) => void) - Required - Callback for incoming messages from the server.
    - **onopen** (() => void | null) - Optional - Callback for when the connection opens.
  - **config** (LiveConnectConfig) - Optional - Advanced configuration options for the live session.
    - **abortSignal** (AbortSignal) - Optional - Signal to abort the connection.
    - **avatarConfig** (AvatarConfig) - Optional - Configuration for avatar behavior.
    - **contextWindowCompression** (ContextWindowCompressionConfig) - Optional - Configuration for context window compression.
    - **enableAffectiveDialog** (boolean) - Optional - Enables affective dialog features.
    - **explicitVadSignal** (boolean) - Optional - Enables explicit Voice Activity Detection signaling.
    - **generationConfig** (GenerationConfig) - Optional - Configuration for text generation.
    - **httpOptions** (HttpOptions) - Optional - HTTP options for the connection.
    - **inputAudioTranscription** (AudioTranscriptionConfig) - Optional - Configuration for input audio transcription.
    - **maxOutputTokens** (number) - Optional - Maximum number of output tokens.
    - **mediaResolution** (MediaResolution) - Optional - Resolution settings for media.
    - **outputAudioTranscription** (AudioTranscriptionConfig) - Optional - Configuration for output audio transcription.
    - **proactivity** (ProactivityConfig) - Optional - Configuration for proactivity.
    - **realtimeInputConfig** (RealtimeInputConfig) - Optional - Configuration for real-time input.
    - **responseModalities** (Modality[]) - Optional - Desired response modalities.
    - **safetySettings** (SafetySetting[]) - Optional - Safety settings for content generation.
    - **seed** (number) - Optional - Seed for reproducible generation.
    - **sessionResumption** (SessionResumptionConfig) - Optional - Configuration for session resumption.
    - **speechConfig** (SpeechConfig) - Optional - Configuration for speech synthesis.
    - **systemInstruction** (ContentUnion) - Optional - System-level instructions for the model.
    - **temperature** (number) - Optional - Controls the randomness of the output.
    - **thinkingConfig** (ThinkingConfig) - Optional - Configuration for thinking process.
    - **tools** (ToolListUnion) - Optional - List of tools available to the model.
    - **topK** (number) - Optional - Controls diversity by limiting the number of highest probability tokens.
    - **topP** (number) - Optional - Controls diversity by sampling from the smallest set of tokens whose cumulative probability exceeds topP.
    - **translationConfig** (TranslationConfig) - Optional - Configuration for translation.
  - **model** (string) - Required - The name of the model to connect to.

### Returns
`Promise<Session>` - A promise that resolves to a Session object upon successful connection.

### Example
```typescript
const live = new Live(apiClient, auth, webSocketFactory);
const session = await live.connect({
  model: "models/gemini-pro",
  callbacks: {
    onmessage: (message) => console.log("Received message:", message),
    onopen: () => console.log("Connection opened"),
    onclose: (event) => console.log("Connection closed:", event),
    onerror: (event) => console.error("Connection error:", event),
  },
  config: {
    temperature: 0.7,
    maxOutputTokens: 100,
  },
});
```
```

--------------------------------

### Run all compiled samples

Source: https://github.com/googleapis/js-genai/blob/main/sdk-samples/README.md

Execute all compiled samples sequentially using the provided `run_samples.sh` script.

```sh
cd sdk-samples
bash run_samples.sh
```

--------------------------------

### Use Deep Research Agent for Complex Tasks in TypeScript

Source: https://github.com/googleapis/js-genai/blob/main/README.md

Start a `deep-research-pro-preview-12-2025` agent for complex research tasks and poll its status until completion or failure.

```typescript
function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// 1. Start the Deep Research Agent
const initialInteraction = await ai.interactions.create({
  input:
      'Research the history of the Google TPUs with a focus on 2025 and 2026.',
  agent: 'deep-research-pro-preview-12-2025',
  background: true,
});

console.log(`Research started. Interaction ID: ${initialInteraction.id}`);

// 2. Poll for results
while (true) {
  const interaction = await ai.interactions.get(initialInteraction.id);
  console.log(`Status: ${interaction.status}`);

  if (interaction.status === 'completed') {
    console.debug('\nFinal Report:\n', interaction.outputs);
    break;
  } else if (['failed', 'cancelled'].includes(interaction.status)) {
    console.log(`Failed with status: ${interaction.status}`);
    break;
  }

  await sleep(10000);  // Sleep for 10 seconds
}
```

--------------------------------

### Implement Function Calling with GoogleGenAI

Source: https://github.com/googleapis/js-genai/blob/main/codegen_instructions.md

Demonstrates how to declare a function (`controlLight`) with parameters and provide it to the model as a tool, allowing the model to request its execution.

```javascript
import {GoogleGenAI, FunctionDeclaration, Type} from '@google/genai';
const ai = new GoogleGenAI({});

async function run() {
    const controlLightDeclaration = {
        name: 'controlLight',
        parameters: {
          type: Type.OBJECT,
          description: 'Set brightness and color temperature of a light.',
          properties: {
            brightness: { type: Type.NUMBER, description: 'Light level from 0 to 100.' },
            colorTemperature: { type: Type.STRING, description: '`daylight`, `cool`, or `warm`.'},
          },
          required: ['brightness', 'colorTemperature'],
        },
    };

    const response = await ai.models.generateContent({
        model: 'gemini-3-flash-preview',
        contents: 'Dim the lights so the room feels cozy and warm.',
        config: {
            tools: [{ functionDeclarations: [controlLightDeclaration] }]
        }
    });

    if (response.functionCalls) {
        console.log('Function calls requested by the model:');
        console.log(response.functionCalls);
        // In a real app, you would execute the function and send the result back.
    } else {
        console.log(response.text);
    }
}
run();
```

--------------------------------

### Live.connect

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai.api.md

Establishes a connection to a live session, enabling real-time interaction with a generative AI model. It takes configuration and callback parameters to manage the session lifecycle and message handling.

```APIDOC
## Method: Live.connect

### Description
Establishes a connection to a live session, enabling real-time interaction with a generative AI model. It takes configuration and callback parameters to manage the session lifecycle and message handling.

### Method Signature
`connect(params: types.LiveConnectParameters): Promise<Session>`

### Parameters
#### `params` (types.LiveConnectParameters) - Required - Configuration for the live session connection.
- **callbacks** (LiveCallbacks) - Required - Defines callback functions for handling session events like messages, open, close, and errors.
- **config** (LiveConnectConfig) - Optional - Advanced configuration options for the live session, including avatar, generation, and safety settings.
- **model** (string) - Required - The model to use for the live session.

### Response
#### Success Response (Promise<Session>)
- Returns a Promise that resolves to a `Session` object upon successful connection.
```

--------------------------------

### new GoogleGenAI(options)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/client.GoogleGenAI.html

Initializes a new instance of the GoogleGenAI SDK, configuring it for either the Gemini API or Vertex AI API based on the provided options.

```APIDOC
## Constructor: new GoogleGenAI(options)

### Description
Initializes a new instance of the GoogleGenAI SDK. This constructor allows you to configure the SDK to use either the Gemini API or the Vertex AI API by providing the appropriate `GoogleGenAIOptions`.

### Method
Constructor

### Parameters
#### Parameters
- **options** (GoogleGenAIOptions) - Required - Configuration options for the Google GenAI SDK, determining the API service to use (Gemini or Vertex AI) and necessary credentials.

### Request Example
```typescript
import {GoogleGenAI} from '@google/genai';
const ai = new GoogleGenAI({apiKey: 'GEMINI_API_KEY'});
// OR
const ai = new GoogleGenAI({
  vertexai: true,
  project: 'PROJECT_ID',
  location: 'PROJECT_LOCATION'
});
```

### Response
#### Success Response (GoogleGenAI)
- Returns a new instance of the `GoogleGenAI` class, configured to interact with the specified GenAI API.
```

--------------------------------

### LiveMusic.connect

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-web.api.md

Establishes a live music session connection, allowing real-time interaction for music generation.

```APIDOC
## LiveMusic.connect

### Description
Establishes a live music session connection, allowing real-time interaction for music generation.

### Method Signature
`connect(params: LiveMusicConnectParameters): Promise<Session>`

### Parameters
- **params** (LiveMusicConnectParameters) - Required - Configuration for the live music session connection.
  - **callbacks** (LiveMusicCallbacks) - Required - Callbacks for handling music connection events.
    - **onclose** ((e: CloseEvent) => void | null) - Optional - Callback for when the music connection closes.
    - **onerror** ((e: ErrorEvent) => void | null) - Optional - Callback for when a music connection error occurs.
    - **onmessage** ((e: LiveMusicServerMessage) => void) - Required - Callback for incoming messages from the music server.
  - **model** (string) - Required - The name of the music model to connect to.

### Returns
`Promise<Session>` - A promise that resolves to a Session object upon successful connection.

### Example
```typescript
// Assuming 'live' is an instance of the Live class
const musicSession = await live.music.connect({
  model: "models/music-gen-pro",
  callbacks: {
    onmessage: (message) => console.log("Received music message:", message),
    onclose: (event) => console.log("Music connection closed:", event),
    onerror: (event) => console.error("Music connection error:", event),
  },
});
```
```

--------------------------------

### new Session(conn, apiClient)

Source: https://github.com/googleapis/js-genai/blob/main/api-report/genai-node.api.md

Creates a new Session instance, establishing a connection to the GenAI service.

```APIDOC
## new Session(conn, apiClient)

### Description
Creates a new Session instance, establishing a connection to the GenAI service.

### Method Signature
constructor(conn: WebSocket_2, apiClient: ApiClient)

### Parameters
- **conn** (WebSocket_2) - The WebSocket connection to use for the session.
- **apiClient** (ApiClient) - The API client instance.
```

--------------------------------

### Implement Google GenAI Live Sample with NodeJS SDK (JavaScript)

Source: https://github.com/googleapis/js-genai/blob/main/sdk-samples/index.html

This comprehensive client-side JavaScript snippet demonstrates a live GenAI application. It handles text input for audio generation and real-time audio streaming using WebSockets, Web Audio API, and AudioWorklets for processing and playback.

```javascript
const socket = io();
const messageQueue = [];
let queueProcessing = false;
let isRecording = false;
let source;
let mediaStream;
let audioCtx;
let nextStartTime = 0;
const form = document.querySelector("form");
const input = document.getElementById("input");
form.addEventListener("submit", function (event) {
  // Prevent the default form submission behavior.
  event.preventDefault();
  if (input.value.trim() !== "") {
    socket.emit("contentUpdateText", input.value);
  }
  form.reset();
});
function base64ToFloat32AudioData(base64String) {
  const byteCharacters = atob(base64String);
  const byteArray = [];
  for (let i = 0; i < byteCharacters.length; i++) {
    byteArray.push(byteCharacters.charCodeAt(i));
  }
  const audioChunks = new Uint8Array(byteArray);
  // Convert Uint8Array (which contains 16-bit PCM) to Float32Array
  const length = audioChunks.length / 2; // 16-bit audio, so 2 bytes per sample
  const float32AudioData = new Float32Array(length);
  for (let i = 0; i < length; i++) {
    // Combine two bytes into one 16-bit signed integer (little-endian)
    let sample = audioChunks[i * 2] | (audioChunks[i * 2 + 1] << 8);
    // Convert from 16-bit PCM to Float32 (range -1 to 1)
    if (sample >= 32768) sample -= 65536;
    float32AudioData[i] = sample / 32768;
  }
  return float32AudioData;
}
socket.on("audioStream", async function (msg) {
  messageQueue.push(base64ToFloat32AudioData(msg));
  if (!queueProcessing) {
    playAudioData();
  }
});
async function playAudioData() {
  queueProcessing = true;
  if (!audioCtx || audioCtx.state === "closed") {
    audioCtx = new AudioContext();
    nextStartTime = audioCtx.currentTime;
  }
  while (messageQueue.length > 0) {
    const audioChunks = messageQueue.shift();
    // Create an AudioBuffer (Assuming 1 channel and 24k sample rate)
    const audioBuffer = audioCtx.createBuffer(1, audioChunks.length, 24000);
    audioBuffer.copyToChannel(audioChunks, 0);
    // Create an AudioBufferSourceNode
    const source = audioCtx.createBufferSource();
    source.buffer = audioBuffer;
    // Connect the source to the destination (speakers)
    source.connect(audioCtx.destination);
    // Schedule the audio to play
    if (nextStartTime < audioCtx.currentTime) {
      nextStartTime = audioCtx.currentTime;
    }
    source.start(nextStartTime);
    // Advance the next start time by the duration of the current buffer
    nextStartTime += audioBuffer.duration;
  }
  queueProcessing = false;
}
document.getElementById("record").onclick = async function (evt) {
  if (isRecording) {
    recordStop();
  } else {
    await recordStart();
  }
};
function recordStop() {
  source?.disconnect();
  mediaStream?.getTracks().forEach((track) => track.stop());
  isRecording = false;
  document.getElementById("record").textContent = "Start Realtime";
}
async function recordStart() {
  await recordAudio();
  isRecording = true;
  document.getElementById("record").textContent = "Stop Realtime";
}
// Recording audio logic reference:
// https://github.com/google-gemini/multimodal-live-api-web-console/blob/main/src/lib/audio-recorder.ts
function arrayBufferToBase64(buffer) {
  let binary = "";
  const bytes = new Uint8Array(buffer);
  const len = bytes.byteLength;
  for (let i = 0; i < len; i++) {
    binary += String.fromCharCode(bytes[i]);
  }
  return window.btoa(binary);
}
async function recordAudio() {
  navigator.mediaDevices.getUserMedia({ audio: true }).then(async (stream) => {
    mediaStream = stream;
    const audioContext = new AudioContext({ sampleRate: 16000 });
    source = audioContext.createMediaStreamSource(stream);
    const workletName = "audio-recorder-worklet";
    const AudioRecordingWorklet = `
 class AudioProcessingWorklet extends AudioWorkletProcessor {
  // send and clear buffer every 2048 samples,
  // which at 16khz is about 8 times a second
  buffer = new Int16Array(2048);
  // current write index
  bufferWriteIndex = 0;
  constructor() {
    super();
    this.hasAudio = false;
  }
  /**
   * @param inputs Float32Array[][] [input#][channel#][sample#] so to access first inputs 1st channel inputs[0][0]
   * @param outputs Float32Array[][]
   */
  process(inputs) {
    if (inputs[0].length) {
      const channel0 = inputs[0][0];
      this.processChunk(channel0);
    }
    return true;
  }
  sendAndClearBuffer(){
    this.port.postMessage({
      event: "chunk",
      data: {
        int16arrayBuffer: this.buffer.slice(0, this.bufferWriteIndex).buffer,
      },
    });
    this.bufferWriteIndex = 0;
  }
  processChunk(float32Array) {
    const l = float32Array.length;
    for (let i = 0; i < l; i++) {
      // convert float32 -1 to 1 to int16 -32768 to 32767
      const int16Value = float32Array[i] * 32768;
      this.buffer[this.bufferWriteIndex++] = int16Value;
      if(this.bufferWriteIndex >= this.buffer.length) {
        this.sendAndClearBuffer();
      }
    }
    if(this.bufferWriteIndex >= this.buffer.length) {
      this.sendAndClearBuffer();
    }
  }
 }`;
    const script = new Blob(
      [`registerProcessor("${workletName}", ${
```

--------------------------------

### Extracting Concatenated Text from GenerateContentResponse (TypeScript)

Source: https://github.com/googleapis/js-genai/blob/main/docs/classes/types.GenerateContentResponse.html

Use this accessor to get a single string containing all text parts from the first candidate in the response. Non-text parts are ignored, and a warning may be logged.

```typescript
const response = await ai.models.generateContent({  model: 'gemini-2.0-flash',  contents:    'Why is the sky blue?',});console.debug(response.text);
```