@google/genai 1.2.0 → 1.4.0

package/README.md

@@ -21,7 +21,21 @@ The Google Gen AI SDK is designed to work with Gemini 2.0 features.
 
 ## Prerequisites
 
-* Node.js version 18 or later
+1. Node.js version 20 or later
+
+### The following are required for Vertex AI users (excluding Vertex AI Studio)
+1.  [Select](https://console.cloud.google.com/project) or [create](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project) a Google Cloud project.
+1.  [Enable billing for your project](https://cloud.google.com/billing/docs/how-to/modify-project).
+1.  [Enable the Vertex AI API](https://console.cloud.google.com/flows/enableapi?apiid=aiplatform.googleapis.com).
+1.  [Configure authentication](https://cloud.google.com/docs/authentication) for your project.
+    *   [Install the gcloud CLI](https://cloud.google.com/sdk/docs/install).
+    *   [Initialize the gcloud CLI](https://cloud.google.com/sdk/docs/initializing).
+    *   Create local authentication credentials for your user account:
+
+    ```sh
+    gcloud auth application-default login
+    ```
+A list of accepted authentication options are listed in [GoogleAuthOptions](https://github.com/googleapis/google-auth-library-nodejs/blob/3ae120d0a45c95e36c59c9ac8286483938781f30/src/auth/googleauth.ts#L87) interface of google-auth-library-node.js GitHub repo.
 
 ## Installation
 
@@ -98,6 +112,33 @@ const ai = new GoogleGenAI({
 });
 ```
 
+### (Optional) (NodeJS only) Using environment variables:
+
+For NodeJS environments, you can create a client by configuring the necessary
+environment variables. Configuration setup instructions depends on whether
+you're using the Gemini Developer API or the Gemini API in Vertex AI.
+
+**Gemini Developer API:** Set `GOOGLE_API_KEY` as shown below:
+
+```bash
+export GOOGLE_API_KEY='your-api-key'
+```
+
+**Gemini API on Vertex AI:** Set `GOOGLE_GENAI_USE_VERTEXAI`,
+`GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`, as shown below:
+
+```bash
+export GOOGLE_GENAI_USE_VERTEXAI=true
+export GOOGLE_CLOUD_PROJECT='your-project-id'
+export GOOGLE_CLOUD_LOCATION='us-central1'
+```
+
+```typescript
+import {GoogleGenAI} from '@google/genai';
+
+const ai = new GoogleGenAI();
+```
+
 ## API Selection
 
 By default, the SDK uses the beta API endpoints provided by Google to support

package/dist/genai.d.ts

@@ -1,4 +1,4 @@
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { GoogleAuthOptions } from 'google-auth-library';
 
 /** Marks the end of user activity.
@@ -272,6 +272,12 @@ export declare interface AuthConfigOidcConfig {
     serviceAccount?: string;
 }
 
+/** Config for auth_tokens.create parameters. */
+export declare interface AuthToken {
+    /** The name of the auth token. */
+    name?: string;
+}
+
 /** Type of auth scheme. */
 export declare enum AuthType {
     AUTH_TYPE_UNSPECIFIED = "AUTH_TYPE_UNSPECIFIED",
@@ -855,7 +861,7 @@ export declare class ControlReferenceImage {
     /** Configuration for the control reference image. */
     config?: ControlReferenceConfig;
     /** Internal method to convert to ReferenceImageAPIInternal. */
-    toReferenceImageAPI(): any;
+    toReferenceImageAPI(): ReferenceImageAPIInternal;
 }
 
 /** Enum representing the control type of a control reference image. */
@@ -938,11 +944,17 @@ export declare interface CreateAuthTokenConfig {
      not count as a use. */
     uses?: number;
     /** Configuration specific to Live API connections created using this token. */
-    liveEphemeralParameters?: LiveEphemeralParameters;
+    liveConnectConstraints?: LiveConnectConstraints;
     /** Additional fields to lock in the effective LiveConnectParameters. */
     lockAdditionalFields?: string[];
 }
 
+/** Config for auth_tokens.create parameters. */
+export declare interface CreateAuthTokenParameters {
+    /** Optional parameters for the request. */
+    config?: CreateAuthTokenConfig;
+}
+
 /** Optional configuration for cached content creation. */
 export declare interface CreateCachedContentConfig {
     /** Used to override HTTP request options. */
@@ -1837,7 +1849,11 @@ export declare enum FinishReason {
     /**
      * Token generation stopped because generated images have safety violations.
      */
-    IMAGE_SAFETY = "IMAGE_SAFETY"
+    IMAGE_SAFETY = "IMAGE_SAFETY",
+    /**
+     * The tool call generated by the model is invalid.
+     */
+    UNEXPECTED_TOOL_CALL = "UNEXPECTED_TOOL_CALL"
 }
 
 /** A function call. */
@@ -2667,6 +2683,7 @@ export declare class GoogleGenAI {
     readonly caches: Caches;
     readonly files: Files;
     readonly operations: Operations;
+    readonly authTokens: Tokens;
     readonly tunings: Tunings;
     constructor(options: GoogleGenAIOptions);
 }
@@ -3544,6 +3561,16 @@ export declare interface LiveConnectConfig {
     proactivity?: ProactivityConfig;
 }
 
+/** Config for LiveConnectConstraints for Auth Token creation. */
+export declare interface LiveConnectConstraints {
+    /** ID of the model to configure in the ephemeral token for Live API.
+     For a list of models, see `Gemini models
+     <https://ai.google.dev/gemini-api/docs/models>`. */
+    model?: string;
+    /** Configuration specific to Live API connections created using this token. */
+    config?: LiveConnectConfig;
+}
+
 /** Parameters for connecting to the live API. */
 export declare interface LiveConnectParameters {
     /** ID of the model to use. For a list of models, see `Google models
@@ -3556,16 +3583,6 @@ export declare interface LiveConnectParameters {
     config?: LiveConnectConfig;
 }
 
-/** Config for LiveEphemeralParameters for Auth Token creation. */
-export declare interface LiveEphemeralParameters {
-    /** ID of the model to configure in the ephemeral token for Live API.
-     For a list of models, see `Gemini models
-     <https://ai.google.dev/gemini-api/docs/models>`. */
-    model?: string;
-    /** Configuration specific to Live API connections created using this token. */
-    config?: LiveConnectConfig;
-}
-
 /**
  LiveMusic class encapsulates the configuration for live music
  generation via Lyria Live models.
@@ -4059,7 +4076,7 @@ export declare class MaskReferenceImage {
     /** Configuration for the mask reference image. */
     config?: MaskReferenceConfig;
     /** Internal method to convert to ReferenceImageAPIInternal. */
-    toReferenceImageAPI(): any;
+    toReferenceImageAPI(): ReferenceImageAPIInternal;
 }
 
 /** Enum representing the mask mode of a mask reference image. */
@@ -4554,11 +4571,6 @@ export declare class Operations extends BaseModule {
     private fetchPredictVideosOperationInternal;
 }
 
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
 /** Required. Outcome of the code execution. */
 export declare enum Outcome {
     /**
@@ -4721,6 +4733,8 @@ export declare interface Part {
     inlineData?: Blob_2;
     /** Optional. URI based data. */
     fileData?: FileData;
+    /** An opaque signature for the thought so it can be reused in subsequent requests. */
+    thoughtSignature?: string;
     /** Optional. Result of executing the [ExecutableCode]. */
     codeExecutionResult?: CodeExecutionResult;
     /** Optional. Code generated by the model that is meant to be executed. */
@@ -4846,7 +4860,7 @@ export declare class RawReferenceImage {
     /** The type of the reference image. Only set by the SDK. */
     referenceType?: string;
     /** Internal method to convert to ReferenceImageAPIInternal. */
-    toReferenceImageAPI(): any;
+    toReferenceImageAPI(): ReferenceImageAPIInternal;
 }
 
 /** Marks the end of user activity.
@@ -4865,6 +4879,24 @@ export declare interface RealtimeInputConfig {
 
 export declare type ReferenceImage = RawReferenceImage | MaskReferenceImage | ControlReferenceImage | StyleReferenceImage | SubjectReferenceImage;
 
+/** Private class that represents a Reference image that is sent to API. */
+declare interface ReferenceImageAPIInternal {
+    /** The reference image for the editing operation. */
+    referenceImage?: types.Image;
+    /** The id of the reference image. */
+    referenceId?: number;
+    /** The type of the reference image. Only set by the SDK. */
+    referenceType?: string;
+    /** Configuration for the mask reference image. */
+    maskImageConfig?: types.MaskReferenceConfig;
+    /** Configuration for the control reference image. */
+    controlImageConfig?: types.ControlReferenceConfig;
+    /** Configuration for the style reference image. */
+    styleImageConfig?: types.StyleReferenceConfig;
+    /** Configuration for the subject reference image. */
+    subjectImageConfig?: types.SubjectReferenceConfig;
+}
+
 /** Represents a recorded session. */
 export declare interface ReplayFile {
     replayId?: string;
@@ -5357,7 +5389,7 @@ export declare class StyleReferenceImage {
     /** Configuration for the style reference image. */
     config?: StyleReferenceConfig;
     /** Internal method to convert to ReferenceImageAPIInternal. */
-    toReferenceImageAPI(): any;
+    toReferenceImageAPI(): ReferenceImageAPIInternal;
 }
 
 /** Configuration for a Subject reference image. */
@@ -5385,7 +5417,7 @@ export declare class SubjectReferenceImage {
     referenceType?: string;
     /** Configuration for the subject reference image. */
     config?: SubjectReferenceConfig;
-    toReferenceImageAPI(): any;
+    toReferenceImageAPI(): ReferenceImageAPIInternal;
 }
 
 /** Enum representing the subject type of a subject reference image. */
@@ -5514,6 +5546,89 @@ export declare interface ThinkingConfig {
     thinkingBudget?: number;
 }
 
+export declare class Tokens extends BaseModule {
+    private readonly apiClient;
+    constructor(apiClient: ApiClient);
+    /**
+     * Creates an ephemeral auth token resource.
+     *
+     * @experimental
+     *
+     * @remarks
+     * Ephermeral auth tokens is only supported in the Gemini Developer API.
+     * It can be used for the session connection to the Live constrained API.
+     *
+     * @param params - The parameters for the create request.
+     * @return The created auth token.
+     *
+     * @example
+     * ```ts
+     * // Case 1: If LiveEphemeralParameters is unset, unlock LiveConnectConfig
+     * // when using the token in Live API sessions. Each session connection can
+     * // use a different configuration.
+     * const config: CreateAuthTokenConfig = {
+     *     uses: 3,
+     *     expireTime: '2025-05-01T00:00:00Z',
+     * }
+     * const token = await ai.tokens.create(config);
+     *
+     * // Case 2: If LiveEphemeralParameters is set, lock all fields in
+     * // LiveConnectConfig when using the token in Live API sessions. For
+     * // example, changing `outputAudioTranscription` in the Live API
+     * // connection will be ignored by the API.
+     * const config: CreateAuthTokenConfig =
+     *     uses: 3,
+     *     expireTime: '2025-05-01T00:00:00Z',
+     *     LiveEphemeralParameters: {
+     *        model: 'gemini-2.0-flash-001',
+     *        config: {
+     *           'responseModalities': ['AUDIO'],
+     *           'systemInstruction': 'Always answer in English.',
+     *        }
+     *     }
+     * }
+     * const token = await ai.tokens.create(config);
+     *
+     * // Case 3: If LiveEphemeralParameters is set and lockAdditionalFields is
+     * // set, lock LiveConnectConfig with set and additional fields (e.g.
+     * // responseModalities, systemInstruction, temperature in this example) when
+     * // using the token in Live API sessions.
+     * const config: CreateAuthTokenConfig =
+     *     uses: 3,
+     *     expireTime: '2025-05-01T00:00:00Z',
+     *     LiveEphemeralParameters: {
+     *        model: 'gemini-2.0-flash-001',
+     *        config: {
+     *           'responseModalities': ['AUDIO'],
+     *           'systemInstruction': 'Always answer in English.',
+     *        }
+     *     },
+     *     lockAdditionalFields: ['temperature'],
+     * }
+     * const token = await ai.tokens.create(config);
+     *
+     * // Case 4: If LiveEphemeralParameters is set and lockAdditionalFields is
+     * // empty array, lock LiveConnectConfig with set fields (e.g.
+     * // responseModalities, systemInstruction in this example) when using the
+     * // token in Live API sessions.
+     * const config: CreateAuthTokenConfig =
+     *     uses: 3,
+     *     expireTime: '2025-05-01T00:00:00Z',
+     *     LiveEphemeralParameters: {
+     *        model: 'gemini-2.0-flash-001',
+     *        config: {
+     *           'responseModalities': ['AUDIO'],
+     *           'systemInstruction': 'Always answer in English.',
+     *        }
+     *     },
+     *     lockAdditionalFields: [],
+     * }
+     * const token = await ai.tokens.create(config);
+     * ```
+     */
+    create(params: types.CreateAuthTokenParameters): Promise<types.AuthToken>;
+}
+
 /** Tokens info with a list of tokens and the corresponding list of token ids. */
 export declare interface TokensInfo {
     /** Optional. Optional fields for the role from the corresponding Content. */
@@ -6098,8 +6213,10 @@ declare namespace types {
         LiveMusicConnectParameters,
         LiveMusicSetConfigParameters,
         LiveMusicSetWeightedPromptsParameters,
-        LiveEphemeralParameters,
+        AuthToken,
+        LiveConnectConstraints,
         CreateAuthTokenConfig,
+        CreateAuthTokenParameters,
         OperationGetParameters,
         BlobImageUnion,
         PartUnion,