@google/genai 0.2.0 → 0.4.0

package/dist/node/node.d.ts

@@ -99,7 +99,7 @@ declare interface ApiClientInitOptions {
 
 /**
  * @license
- * Copyright 2024 Google LLC
+ * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 /**
@@ -114,11 +114,6 @@ declare interface Auth {
     addAuthHeaders(headers: Headers): Promise<void>;
 }
 
-/**
- * @license
- * Copyright 2024 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
 declare class BaseModule {
 }
 
@@ -182,7 +177,7 @@ export declare class Caches extends BaseModule {
      *
      * @example
      * ```ts
-     * const cachedContents = await client.caches.list({config: {'pageSize': 2}});
+     * const cachedContents = await ai.caches.list({config: {'pageSize': 2}});
      * for (const cachedContent of cachedContents) {
      *   console.log(cachedContent);
      * }
@@ -198,7 +193,7 @@ export declare class Caches extends BaseModule {
      * @example
      * ```ts
      * const contents = ...; // Initialize the content to cache.
-     * const response = await client.caches.create({
+     * const response = await ai.caches.create({
      *   model: 'gemini-2.0-flash',
      *   config: {
      *    'contents': contents,
@@ -218,7 +213,7 @@ export declare class Caches extends BaseModule {
      *
      * @example
      * ```ts
-     * await client.caches.get({name: 'gemini-1.5-flash'});
+     * await ai.caches.get({name: 'gemini-1.5-flash'});
      * ```
      */
     get(params: types.GetCachedContentParameters): Promise<types.CachedContent>;
@@ -230,7 +225,7 @@ export declare class Caches extends BaseModule {
      *
      * @example
      * ```ts
-     * await client.caches.delete({name: 'gemini-1.5-flash'});
+     * await ai.caches.delete({name: 'gemini-1.5-flash'});
      * ```
      */
     delete(params: types.DeleteCachedContentParameters): Promise<types.DeleteCachedContentResponse>;
@@ -242,7 +237,7 @@ export declare class Caches extends BaseModule {
      *
      * @example
      * ```ts
-     * const response = await client.caches.update({
+     * const response = await ai.caches.update({
      *   name: 'gemini-1.5-flash',
      *   config: {'ttl': '7600s'}
      * });
@@ -281,8 +276,11 @@ export declare interface Candidate {
 }
 
 /**
- * Chat session that enables sending messages and stores the chat history so
- * far.
+ * Chat session that enables sending messages to the model with previous
+ * conversation context.
+ *
+ * @remarks
+ * The session maintains all the turns between user and model.
  */
 export declare class Chat {
     private readonly apiClient;
@@ -302,6 +300,15 @@ export declare class Chat {
      * @see {@link Chat#sendMessageStream} for streaming method.
      * @param params - parameters for sending messages within a chat session.
      * @returns The model's response.
+     *
+     * @example
+     * ```ts
+     * const chat = ai.chats.create({model: 'gemini-2.0-flash'});
+     * const response = await chat.sendMessage({
+     *   message: 'Why is the sky blue?'
+     * });
+     * console.log(response.text);
+     * ```
      */
     sendMessage(params: types.SendMessageParameters): Promise<types.GenerateContentResponse>;
     /**
@@ -314,6 +321,17 @@ export declare class Chat {
      * @see {@link Chat#sendMessage} for non-streaming method.
      * @param params - parameters for sending the message.
      * @return The model's response.
+     *
+     * @example
+     * ```ts
+     * const chat = ai.chats.create({model: 'gemini-2.0-flash'});
+     * const response = await chat.sendMessageStream({
+     *   message: 'Why is the sky blue?'
+     * });
+     * for await (const chunk of response) {
+     *   console.log(chunk.text);
+     * }
+     * ```
      */
     sendMessageStream(params: types.SendMessageParameters): Promise<AsyncGenerator<types.GenerateContentResponse>>;
     /**
@@ -354,8 +372,24 @@ export declare class Chats {
     /**
      * Creates a new chat session.
      *
+     * @remarks
+     * The config in the params will be used for all requests within the chat
+     * session unless overridden by a per-request `config` in
+     * {@link ./types.SendMessageParameters}.
+     *
      * @param params - Parameters for creating a chat session.
      * @returns A new chat session.
+     *
+     * @example
+     * ```ts
+     * const chat = ai.chats.create({
+     *   model: 'gemini-2.0-flash'
+     *   config: {
+     *     temperature: 0.5,
+     *     maxOutputTokens: 1024,
+     *   }
+     * });
+     * ```
      */
     create(params: types.CreateChatParameters): Chat;
 }
@@ -393,6 +427,16 @@ export declare interface CodeExecutionResult {
     output?: string;
 }
 
+declare namespace common {
+    export {
+        formatMap,
+        setValueByPath,
+        getValueByPath,
+        BaseModule,
+        UploadFileParameters
+    }
+}
+
 /** Optional parameters for computing tokens. */
 export declare interface ComputeTokensConfig {
     /** Used to override HTTP request options. */
@@ -660,11 +704,6 @@ export declare function createPartFromText(text: string): Part;
  */
 export declare function createPartFromUri(uri: string, mimeType: string): Part;
 
-/**
- * Creates a `Part` object from the `startOffset` and `endOffset` of a `VideoMetadata` object.
- */
-export declare function createPartFromVideoMetadata(startOffset: string, endOffset: string): Part;
-
 /**
  * Creates a `Content` object with a user role from a `PartListUnion` object or `string`.
  */
@@ -830,7 +869,7 @@ declare class Files extends BaseModule {
      * size of each page is 10.
      *
      * ```ts
-     * const listResponse = await client.files.list({config: {'pageSize': 10}});
+     * const listResponse = await ai.files.list({config: {'pageSize': 10}});
      * for await (const file of listResponse) {
      *   console.log(file.name);
      * }
@@ -860,26 +899,26 @@ declare class Files extends BaseModule {
      *
      * This section can contain multiple paragraphs and code examples.
      *
-     * @param file The string path to the file to be uploaded or a Blob object.
-     * @param config Optional parameters specified in the `types.UploadFileConfig`
-     *     interface. Optional @see {@link types.UploadFileConfig}
+     * @param params - Optional parameters specified in the
+     *        `common.UploadFileParameters` interface.
+     *        Optional @see {@link common.UploadFileParameters}
      * @return A promise that resolves to a `types.File` object.
      * @throws An error if called on a Vertex AI client.
      * @throws An error if the `mimeType` is not provided and can not be inferred,
-     * the `mimeType` can be provided in the `config` parameter.
+     * the `mimeType` can be provided in the `params.config` parameter.
      * @throws An error occurs if a suitable upload location cannot be established.
      *
      * @example
      * The following code uploads a file to Gemini API.
      *
      * ```ts
-     * const file = await client.files.upload('file.txt', {
+     * const file = await ai.files.upload({file: 'file.txt', config: {
      *   mimeType: 'text/plain',
-     * });
+     * }});
      * console.log(file.name);
      * ```
      */
-    upload(file: string | Blob, config?: types.UploadFileConfig): Promise<types.File>;
+    upload(params: common.UploadFileParameters): Promise<types.File>;
     private listInternal;
     private createInternal;
     /**
@@ -893,7 +932,7 @@ declare class Files extends BaseModule {
      * const config: GetFileParameters = {
      *   name: fileName,
      * };
-     * file = await client.files.get(config);
+     * file = await ai.files.get(config);
      * console.log(file.name);
      * ```
      */
@@ -953,6 +992,8 @@ export declare enum FinishReason {
     MALFORMED_FUNCTION_CALL = "MALFORMED_FUNCTION_CALL"
 }
 
+declare function formatMap(templateString: string, valueMap: Record<string, unknown>): string;
+
 /** A function call. */
 export declare interface FunctionCall {
     /** The unique id of the function call. If populated, the client to execute the
@@ -1295,6 +1336,10 @@ export declare interface GeneratedImage {
      response.
      */
     raiFilteredReason?: string;
+    /** Safety attributes of the image. Lists of RAI categories and their
+     scores of each content.
+     */
+    safetyAttributes?: SafetyAttributes;
     /** The rewritten prompt used for the image generation if the prompt
      enhancer is enabled.
      */
@@ -1461,6 +1506,8 @@ export declare interface GetFileParameters {
     config?: GetFileConfig;
 }
 
+declare function getValueByPath(data: unknown, keys: string[]): unknown;
+
 /**
  * The Google GenAI SDK.
  *
@@ -1470,23 +1517,21 @@ export declare interface GetFileParameters {
  *
  * The {@link GoogleGenAIOptions.vertexai} value determines which of the API services to use.
  *
- * When using the Gemini API, a {@link GoogleGenAIOptions.apiKey} must be set,
- * when using Vertex AI {@link GoogleGenAIOptions.project}
- * and {@link GoogleGenAIOptions.location} must be set,
- * and the {@link GoogleGenAIOptions.vertexai} must be set to `true`.
+ * When using the Gemini API, a {@link GoogleGenAIOptions.apiKey} must also be set,
+ * when using Vertex AI {@link GoogleGenAIOptions.project} and {@link GoogleGenAIOptions.location} must also be set.
  *
  * @example
  * Initializing the SDK for using the Gemini API:
  * ```ts
  * import {GoogleGenAI} from '@google/genai';
- * const ai = genai.GoogleGenAI({apiKey: 'GEMINI_API_KEY'});
+ * const ai = new GoogleGenAI({apiKey: 'GEMINI_API_KEY'});
  * ```
  *
  * @example
  * Initializing the SDK for using the Vertex AI API:
  * ```ts
  * import {GoogleGenAI} from '@google/genai';
- * const ai = genai.GoogleGenAI({
+ * const ai = new GoogleGenAI({
  *   vertexai: true,
  *   project: 'PROJECT_ID',
  *   location: 'PROJECT_LOCATION'
@@ -1569,13 +1614,6 @@ export declare interface GoogleGenAIOptions {
      * Optional. A set of customizable configuration for HTTP requests.
      */
     httpOptions?: HttpOptions;
-    /**
-     * The object used for adding authentication headers to API requests.
-     *
-     * @remarks
-     * Only used for internal testing, will be removed in the future.
-     */
-    auth?: Auth;
 }
 
 /** Tool to support Google Search in Model. Powered by Google. */
@@ -1846,20 +1884,14 @@ export declare class Live {
      Establishes a connection to the specified model with the given
      configuration and returns a Session object representing that connection.
 
-     > [!CAUTION] This SDK does not yet support the live API for **Google Vertex AI**.
-
      @experimental
 
-     @param model - Model to use for the Live session.
-     @param config - Configuration parameters for the Live session.
-     @param callbacks - Optional callbacks for websocket events. If not
-     provided, default no-op callbacks will be used. Generally, prefer to
-     provide explicit callbacks to allow for proper handling of websocket
-     events (e.g. connection errors).
+     @param params - The parameters for establishing a connection to the model.
+     @return A live session.
 
      @example
      ```ts
-     const session = await client.live.connect({
+     const session = await ai.live.connect({
      model: 'gemini-2.0-flash-exp',
      config: {
      responseModalities: [Modality.AUDIO],
@@ -1886,10 +1918,10 @@ export declare class Live {
 
 /** Callbacks for the live API. */
 export declare interface LiveCallbacks {
-    onopen: (() => void) | null;
+    onopen?: (() => void) | null;
     onmessage: (e: LiveServerMessage) => void;
-    onerror: ((e: ErrorEvent) => void) | null;
-    onclose: ((e: CloseEvent) => void) | null;
+    onerror?: ((e: ErrorEvent) => void) | null;
+    onclose?: ((e: CloseEvent) => void) | null;
 }
 
 /** Incremental update of the current conversation delivered from the client.
@@ -2184,14 +2216,12 @@ export declare class Models extends BaseModule {
      *
      * Some models support multimodal input and output.
      *
-     * @param model - The model to use for generating content.
-     * @param contents - The input contents to use for generating content.
-     * @param [config] - The configuration for generating content.
+     * @param params - The parameters for generating content.
      * @return The response from generating content.
      *
      * @example
      * ```ts
-     * const response = await client.models.generateContent({
+     * const response = await ai.models.generateContent({
      *   model: 'gemini-2.0-flash',
      *   contents: 'why is the sky blue?',
      *   config: {
@@ -2226,14 +2256,12 @@ export declare class Models extends BaseModule {
      *
      * Some models support multimodal input and output.
      *
-     * @param model - The model to use for generating content.
-     * @param contents - The input contents to use for generating content.
-     * @param [config] - The configuration for generating content.
+     * @param params - The parameters for generating content with streaming response.
      * @return The response from generating content.
      *
      * @example
      * ```ts
-     * const response = await client.models.generateContentStream({
+     * const response = await ai.models.generateContentStream({
      *   model: 'gemini-2.0-flash',
      *   contents: 'why is the sky blue?',
      *   config: {
@@ -2251,14 +2279,12 @@ export declare class Models extends BaseModule {
     /**
      * Calculates embeddings for the given contents. Only text is supported.
      *
-     * @param model - The model to use.
-     * @param contents - The contents to embed.
-     * @param [config] - The config for embedding contents.
+     * @param params - The parameters for embedding contents.
      * @return The response from the API.
      *
      * @example
      * ```ts
-     * const response = await client.models.embedContent({
+     * const response = await ai.models.embedContent({
      *  model: 'text-embedding-004',
      *  contents: [
      *    'What is your name?',
@@ -2275,14 +2301,12 @@ export declare class Models extends BaseModule {
     /**
      * Generates an image based on a text description and configuration.
      *
-     * @param model - The model to use.
-     * @param prompt - A text description of the image to generate.
-     * @param [config] - The config for image generation.
+     * @param params - The parameters for generating images.
      * @return The response from the API.
      *
      * @example
      * ```ts
-     * const response = await client.models.generateImages({
+     * const response = await ai.models.generateImages({
      *  model: 'imagen-3.0-generate-002',
      *  prompt: 'Robot holding a red skateboard',
      *  config: {
@@ -2298,14 +2322,12 @@ export declare class Models extends BaseModule {
      * Counts the number of tokens in the given contents. Multimodal input is
      * supported for Gemini models.
      *
-     * @param model - The model to use for counting tokens.
-     * @param contents - The contents to count tokens for.
-     * @param [config] - The config for counting tokens.
+     * @param params - The parameters for counting tokens.
      * @return The response from the API.
      *
      * @example
      * ```ts
-     * const response = await client.models.countTokens({
+     * const response = await ai.models.countTokens({
      *  model: 'gemini-2.0-flash',
      *  contents: 'The quick brown fox jumps over the lazy dog.'
      * });
@@ -2319,14 +2341,12 @@ export declare class Models extends BaseModule {
      *
      * This method is not supported by the Gemini Developer API.
      *
-     * @param model - The model to use.
-     * @param contents - The content to compute tokens for.
-     * @param [config] - The config for computing tokens.
+     * @param params - The parameters for computing tokens.
      * @return The response from the API.
      *
      * @example
      * ```ts
-     * const response = await client.models.computeTokens({
+     * const response = await ai.models.computeTokens({
      *  model: 'gemini-2.0-flash',
      *  contents: 'What is your name?'
      * });
@@ -2338,7 +2358,7 @@ export declare class Models extends BaseModule {
 
 /**
  * @license
- * Copyright 2024 Google LLC
+ * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 export declare enum Outcome {
@@ -2350,7 +2370,7 @@ export declare enum Outcome {
 
 /**
  * @license
- * Copyright 2024 Google LLC
+ * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
 /**
@@ -2364,6 +2384,22 @@ declare enum PagedItem {
     PAGED_ITEM_CACHED_CONTENTS = "cachedContents"
 }
 
+declare interface PagedItemConfig {
+    config?: {
+        pageToken?: string;
+        pageSize?: number;
+    };
+}
+
+declare interface PagedItemResponse<T> {
+    nextPageToken?: string;
+    batchJobs?: T[];
+    models?: T[];
+    tuningJobs?: T[];
+    files?: T[];
+    cachedContents?: T[];
+}
+
 /**
  * Pager class for iterating through paginated results.
  */
@@ -2372,9 +2408,9 @@ declare class Pager<T> implements AsyncIterable<T> {
     private pageInternal;
     private paramsInternal;
     private pageInternalSize;
-    protected requestInternal: (params: any) => any;
+    protected requestInternal: (params: PagedItemConfig) => Promise<PagedItemResponse<T>>;
     protected idxInternal: number;
-    constructor(name: PagedItem, request: (params: any) => any, response: any, params: any);
+    constructor(name: PagedItem, request: (params: PagedItemConfig) => Promise<PagedItemResponse<T>>, response: PagedItemResponse<T>, params: PagedItemConfig);
     private init;
     private initNextPage;
     /**
@@ -2404,7 +2440,7 @@ declare class Pager<T> implements AsyncIterable<T> {
      * used to customize the API request. For example, the `pageToken` parameter
      * contains the token to request the next page.
      */
-    get params(): any;
+    get params(): PagedItemConfig;
     /**
      * Returns the total number of items in the current page.
      */
@@ -2562,6 +2598,16 @@ export declare interface RetrievalMetadata {
     googleSearchDynamicRetrievalScore?: number;
 }
 
+/** Safety attributes of a GeneratedImage or the user-provided prompt. */
+export declare interface SafetyAttributes {
+    /** List of RAI categories.
+     */
+    categories?: string[];
+    /** List of scores of each categories.
+     */
+    scores?: number[];
+}
+
 export declare enum SafetyFilterLevel {
     BLOCK_LOW_AND_ABOVE = "BLOCK_LOW_AND_ABOVE",
     BLOCK_MEDIUM_AND_ABOVE = "BLOCK_MEDIUM_AND_ABOVE",
@@ -2605,12 +2651,8 @@ export declare interface Schema {
     example?: unknown;
     /** Optional. Pattern of the Type.STRING to restrict a string to a regular expression. */
     pattern?: string;
-    /** Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER */
-    minimum?: number;
     /** Optional. Default value of the data. */
     default?: unknown;
-    /** Optional. The value should be validated against any (one or more) of the subschemas in the list. */
-    anyOf?: Schema[];
     /** Optional. Maximum length of the Type.STRING */
     maxLength?: string;
     /** Optional. The title of the Schema. */
@@ -2619,10 +2661,10 @@ export declare interface Schema {
     minLength?: string;
     /** Optional. Minimum number of the properties for Type.OBJECT. */
     minProperties?: string;
-    /** Optional. Maximum value of the Type.INTEGER and Type.NUMBER */
-    maximum?: number;
     /** Optional. Maximum number of the properties for Type.OBJECT. */
     maxProperties?: string;
+    /** Optional. The value should be validated against any (one or more) of the subschemas in the list. */
+    anyOf?: Schema[];
     /** Optional. The description of the data. */
     description?: string;
     /** Optional. Possible values of the element of primitive type with enum format. Examples: 1. We can define direction as : {type:STRING, format:enum, enum:["EAST", NORTH", "SOUTH", "WEST"]} 2. We can define apartment number as : {type:INTEGER, format:enum, enum:["101", "201", "301"]} */
@@ -2633,8 +2675,12 @@ export declare interface Schema {
     items?: Schema;
     /** Optional. Maximum number of the elements for Type.ARRAY. */
     maxItems?: string;
+    /** Optional. Maximum value of the Type.INTEGER and Type.NUMBER */
+    maximum?: number;
     /** Optional. Minimum number of the elements for Type.ARRAY. */
     minItems?: string;
+    /** Optional. SCHEMA FIELDS FOR TYPE INTEGER and NUMBER Minimum value of the Type.INTEGER and Type.NUMBER */
+    minimum?: number;
     /** Optional. Indicates if the value may be null. */
     nullable?: boolean;
     /** Optional. SCHEMA FIELDS FOR TYPE OBJECT Properties of Type.OBJECT. */
@@ -2796,7 +2842,7 @@ export declare class Session {
 
      @example
      ```ts
-     const session = await client.live.connect({
+     const session = await ai.live.connect({
      model: 'gemini-2.0-flash-exp',
      config: {
      responseModalities: [Modality.AUDIO],
@@ -2831,6 +2877,8 @@ export declare class SessionSendToolResponseParameters {
     functionResponses: FunctionResponse | FunctionResponse[];
 }
 
+declare function setValueByPath(data: Record<string, unknown>, keys: string[], value: unknown): void;
+
 /** The speech generation configuration. */
 export declare interface SpeechConfig {
     /** The configuration for the speaker to use.
@@ -2999,7 +3047,6 @@ declare namespace types {
         createPartFromFunctionCall,
         createPartFromFunctionResponse,
         createPartFromBase64,
-        createPartFromVideoMetadata,
         createPartFromCodeExecutionResult,
         createPartFromExecutableCode,
         createUserContent,
@@ -3089,6 +3136,7 @@ declare namespace types {
         GenerateImagesConfig,
         GenerateImagesParameters,
         Image_2 as Image,
+        SafetyAttributes,
         GeneratedImage,
         GenerateImagesResponse,
         GenerationConfig,
@@ -3225,6 +3273,14 @@ export declare interface UploadFileConfig {
     displayName?: string;
 }
 
+/** Parameters for the upload file method. */
+declare interface UploadFileParameters {
+    /** The string path to the file to be uploaded or a Blob object. */
+    file: string | Blob;
+    /** Configuration that contains optional parameters. */
+    config?: UploadFileConfig;
+}
+
 /** Configuration for upscaling an image.
 
  For more information on this configuration, refer to