@google/genai 1.5.1 → 1.7.0

package/dist/genai.d.ts

@@ -1,3 +1,4 @@
+// @ts-ignore
 import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { GoogleAuthOptions } from 'google-auth-library';
 
@@ -191,6 +192,30 @@ declare interface ApiClientInitOptions {
     userAgentExtra?: string;
 }
 
+/**
+ * API errors raised by the GenAI API.
+ */
+export declare class ApiError extends Error {
+    /** HTTP status code */
+    status: number;
+    constructor(options: ApiErrorInfo);
+}
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Details for errors from calling the API.
+ */
+export declare interface ApiErrorInfo {
+    /** The error message. */
+    message: string;
+    /** The HTTP status code. */
+    status: number;
+}
+
 /** Config for authentication with API key. */
 export declare interface ApiKeyConfig {
     /** The API key to be used in the request directly. */
@@ -359,6 +384,162 @@ export declare interface BaseUrlParameters {
     vertexUrl?: string;
 }
 
+export declare class Batches extends BaseModule {
+    private readonly apiClient;
+    constructor(apiClient: ApiClient);
+    /**
+     * Create batch job.
+     *
+     * @param params - The parameters for create batch job request.
+     * @return The created batch job.
+     *
+     * @example
+     * ```ts
+     * const response = await ai.batches.create({
+     *   model: 'gemini-2.0-flash',
+     *   src: {gcsUri: 'gs://bucket/path/to/file.jsonl', format: 'jsonl'},
+     *   config: {
+     *     dest: {gcsUri: 'gs://bucket/path/output/directory', format: 'jsonl'},
+     *   }
+     * });
+     * console.log(response);
+     * ```
+     */
+    create: (params: types.CreateBatchJobParameters) => Promise<types.BatchJob>;
+    /**
+     * Lists batch job configurations.
+     *
+     * @param params - The parameters for the list request.
+     * @return The paginated results of the list of batch jobs.
+     *
+     * @example
+     * ```ts
+     * const batchJobs = await ai.batches.list({config: {'pageSize': 2}});
+     * for await (const batchJob of batchJobs) {
+     *   console.log(batchJob);
+     * }
+     * ```
+     */
+    list: (params?: types.ListBatchJobsParameters) => Promise<Pager<types.BatchJob>>;
+    /**
+     * Internal method to create batch job.
+     *
+     * @param params - The parameters for create batch job request.
+     * @return The created batch job.
+     *
+     */
+    private createInternal;
+    /**
+     * Gets batch job configurations.
+     *
+     * @param params - The parameters for the get request.
+     * @return The batch job.
+     *
+     * @example
+     * ```ts
+     * await ai.batches.get({name: '...'}); // The server-generated resource name.
+     * ```
+     */
+    get(params: types.GetBatchJobParameters): Promise<types.BatchJob>;
+    /**
+     * Cancels a batch job.
+     *
+     * @param params - The parameters for the cancel request.
+     * @return The empty response returned by the API.
+     *
+     * @example
+     * ```ts
+     * await ai.batches.cancel({name: '...'}); // The server-generated resource name.
+     * ```
+     */
+    cancel(params: types.CancelBatchJobParameters): Promise<void>;
+    private listInternal;
+}
+
+/** Config for batches.create return value. */
+export declare interface BatchJob {
+    /** The resource name of the BatchJob. Output only.".
+     */
+    name?: string;
+    /** The display name of the BatchJob.
+     */
+    displayName?: string;
+    /** The state of the BatchJob.
+     */
+    state?: JobState;
+    /** Output only. Only populated when the job's state is JOB_STATE_FAILED or JOB_STATE_CANCELLED. */
+    error?: JobError;
+    /** The time when the BatchJob was created.
+     */
+    createTime?: string;
+    /** Output only. Time when the Job for the first time entered the `JOB_STATE_RUNNING` state. */
+    startTime?: string;
+    /** The time when the BatchJob was completed.
+     */
+    endTime?: string;
+    /** The time when the BatchJob was last updated.
+     */
+    updateTime?: string;
+    /** The name of the model that produces the predictions via the BatchJob.
+     */
+    model?: string;
+    /** Configuration for the input data.
+     */
+    src?: BatchJobSource;
+    /** Configuration for the output data.
+     */
+    dest?: BatchJobDestination;
+}
+
+/** Config for `des` parameter. */
+export declare interface BatchJobDestination {
+    /** Storage format of the output files. Must be one of:
+     'jsonl', 'bigquery'.
+     */
+    format?: string;
+    /** The Google Cloud Storage URI to the output file.
+     */
+    gcsUri?: string;
+    /** The BigQuery URI to the output table.
+     */
+    bigqueryUri?: string;
+    /** The Gemini Developer API's file resource name of the output data
+     (e.g. "files/12345"). The file will be a JSONL file with a single response
+     per line. The responses will be GenerateContentResponse messages formatted
+     as JSON. The responses will be written in the same order as the input
+     requests.
+     */
+    fileName?: string;
+    /** The responses to the requests in the batch. Returned when the batch was
+     built using inlined requests. The responses will be in the same order as
+     the input requests.
+     */
+    inlinedResponses?: InlinedResponse[];
+}
+
+/** Config for `src` parameter. */
+export declare interface BatchJobSource {
+    /** Storage format of the input files. Must be one of:
+     'jsonl', 'bigquery'.
+     */
+    format?: string;
+    /** The Google Cloud Storage URIs to input files.
+     */
+    gcsUri?: string[];
+    /** The BigQuery URI to input table.
+     */
+    bigqueryUri?: string;
+    /** The Gemini Developer API's file resource name of the input data
+     (e.g. "files/12345").
+     */
+    fileName?: string;
+    /** The Gemini Developer API's inlined input data to run batch job.
+     */
+    inlinedRequests?: InlinedRequest[];
+}
+
+export declare type BatchJobSourceUnion = BatchJobSource | InlinedRequest[] | string;
+
 /** Defines the function behavior. Defaults to `BLOCKING`. */
 export declare enum Behavior {
     /**
@@ -562,6 +743,30 @@ export declare interface CallableToolConfig {
     timeout?: number;
 }
 
+/** Optional parameters. */
+export declare interface CancelBatchJobConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+    /** Abort signal which can be used to cancel the request.
+
+     NOTE: AbortSignal is a client-only operation. Using it to cancel an
+     operation will not cancel the request in the service. You will still
+     be charged usage for any applicable operations.
+     */
+    abortSignal?: AbortSignal;
+}
+
+/** Config for batches.cancel parameters. */
+export declare interface CancelBatchJobParameters {
+    /** A fully-qualified BatchJob resource name or ID.
+     Example: "projects/.../locations/.../batchPredictionJobs/456"
+     or "456" when project and location are initialized in the client.
+     */
+    name: string;
+    /** Optional parameters for the request. */
+    config?: CancelBatchJobConfig;
+}
+
 /** A response candidate generated from the model. */
 export declare interface Candidate {
     /** Contains the multi-part content of the response.
@@ -959,6 +1164,40 @@ export declare interface CreateAuthTokenParameters {
     config?: CreateAuthTokenConfig;
 }
 
+/** Config for optional parameters. */
+export declare interface CreateBatchJobConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+    /** Abort signal which can be used to cancel the request.
+
+     NOTE: AbortSignal is a client-only operation. Using it to cancel an
+     operation will not cancel the request in the service. You will still
+     be charged usage for any applicable operations.
+     */
+    abortSignal?: AbortSignal;
+    /** The user-defined name of this BatchJob.
+     */
+    displayName?: string;
+    /** GCS or BigQuery URI prefix for the output predictions. Example:
+     "gs://path/to/output/data" or "bq://projectId.bqDatasetId.bqTableId".
+     */
+    dest?: string;
+}
+
+/** Config for batches.create parameters. */
+export declare interface CreateBatchJobParameters {
+    /** The name of the model to produces the predictions via the BatchJob.
+     */
+    model?: string;
+    /** GCS URI(-s) or BigQuery URI to your input data to run batch job.
+     Example: "gs://path/to/input/data" or "bq://projectId.bqDatasetId.bqTableId".
+     */
+    src: BatchJobSourceUnion;
+    /** Optional parameters for creating a BatchJob.
+     */
+    config?: CreateBatchJobConfig;
+}
+
 /** Optional configuration for cached content creation. */
 export declare interface CreateCachedContentConfig {
     /** Used to override HTTP request options. */
@@ -1390,7 +1629,8 @@ export declare interface EditImageConfig {
     /** Number of images to generate.
      */
     numberOfImages?: number;
-    /** Aspect ratio of the generated images.
+    /** Aspect ratio of the generated images. Supported values are
+     "1:1", "3:4", "4:3", "9:16", and "16:9".
      */
     aspectRatio?: string;
     /** Controls how much the model adheres to the text prompt. Large
@@ -1913,8 +2153,12 @@ export declare interface FunctionDeclaration {
     name?: string;
     /** Optional. Describes the parameters to this function in JSON Schema Object format. Reflects the Open API 3.03 Parameter Object. string Key: the name of the parameter. Parameter names are case sensitive. Schema Value: the Schema defining the type used for the parameter. For function with no parameters, this can be left unset. Parameter names must start with a letter or an underscore and must only contain chars a-z, A-Z, 0-9, or underscores with a maximum length of 64. Example with 1 required and 1 optional parameter: type: OBJECT properties: param1: type: STRING param2: type: INTEGER required: - param1 */
     parameters?: Schema;
+    /** Optional. Describes the parameters to the function in JSON Schema format. The schema must describe an object where the properties are the parameters to the function. For example: ``` { "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } }, "additionalProperties": false, "required": ["name", "age"], "propertyOrdering": ["name", "age"] } ``` This field is mutually exclusive with `parameters`. */
+    parametersJsonSchema?: unknown;
     /** Optional. Describes the output from this function in JSON Schema format. Reflects the Open API 3.03 Response Object. The Schema defines the type used for the response value of the function. */
     response?: Schema;
+    /** Optional. Describes the output from this function in JSON Schema format. The value specified by the schema is the response value of the function. This field is mutually exclusive with `response`. */
+    responseJsonSchema?: unknown;
 }
 
 /** A function response. */
@@ -2039,6 +2283,22 @@ export declare interface GenerateContentConfig {
      Compatible mimetypes: `application/json`: Schema for JSON response.
      */
     responseSchema?: SchemaUnion;
+    /** Optional. Output schema of the generated response.
+     This is an alternative to `response_schema` that accepts [JSON
+     Schema](https://json-schema.org/). If set, `response_schema` must be
+     omitted, but `response_mime_type` is required. While the full JSON Schema
+     may be sent, not all features are supported. Specifically, only the
+     following properties are supported: - `$id` - `$defs` - `$ref` - `$anchor`
+     - `type` - `format` - `title` - `description` - `enum` (for strings and
+     numbers) - `items` - `prefixItems` - `minItems` - `maxItems` - `minimum` -
+     `maximum` - `anyOf` - `oneOf` (interpreted the same as `anyOf`) -
+     `properties` - `additionalProperties` - `required` The non-standard
+     `propertyOrdering` property may also be set. Cyclic references are
+     unrolled to a limited degree and, as such, may only be used within
+     non-required properties. (Nullable properties are not sufficient.) If
+     `$ref` is set on a sub-schema, no other properties, except for than those
+     starting as a `$`, may be set. */
+    responseJsonSchema?: unknown;
     /** Configuration for model router requests.
      */
     routingConfig?: GenerationConfigRoutingConfig;
@@ -2327,7 +2587,8 @@ export declare interface GenerateImagesConfig {
     /** Number of images to generate.
      */
     numberOfImages?: number;
-    /** Aspect ratio of the generated images.
+    /** Aspect ratio of the generated images. Supported values are
+     "1:1", "3:4", "4:3", "9:16", and "16:9".
      */
     aspectRatio?: string;
     /** Controls how much the model adheres to the text prompt. Large
@@ -2432,6 +2693,8 @@ export declare interface GenerateVideosConfig {
     generateAudio?: boolean;
     /** Image to use as the last frame of generated videos. Only supported for image to video use cases. */
     lastFrame?: Image_2;
+    /** Compression quality of the generated videos. */
+    compressionQuality?: VideoCompressionQuality;
 }
 
 /** A video generation operation. */
@@ -2501,6 +2764,8 @@ export declare interface GenerationConfig {
     responseModalities?: Modality[];
     /** Optional. The `Schema` object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. Represents a select subset of an [OpenAPI 3.0 schema object](https://spec.openapis.org/oas/v3.0.3#schema). If set, a compatible response_mime_type must also be set. Compatible mimetypes: `application/json`: Schema for JSON response. */
     responseSchema?: Schema;
+    /** Optional. Output schema of the generated response. This is an alternative to `response_schema` that accepts [JSON Schema](https://json-schema.org/). If set, `response_schema` must be omitted, but `response_mime_type` is required. While the full JSON Schema may be sent, not all features are supported. Specifically, only the following properties are supported: - `$id` - `$defs` - `$ref` - `$anchor` - `type` - `format` - `title` - `description` - `enum` (for strings and numbers) - `items` - `prefixItems` - `minItems` - `maxItems` - `minimum` - `maximum` - `anyOf` - `oneOf` (interpreted the same as `anyOf`) - `properties` - `additionalProperties` - `required` The non-standard `propertyOrdering` property may also be set. Cyclic references are unrolled to a limited degree and, as such, may only be used within non-required properties. (Nullable properties are not sufficient.) If `$ref` is set on a sub-schema, no other properties, except for than those starting as a `$`, may be set. */
+    responseJsonSchema?: unknown;
     /** Optional. Routing configuration. */
     routingConfig?: GenerationConfigRoutingConfig;
     /** Optional. Seed. */
@@ -2547,6 +2812,30 @@ export declare interface GenerationConfigThinkingConfig {
     thinkingBudget?: number;
 }
 
+/** Optional parameters. */
+export declare interface GetBatchJobConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+    /** Abort signal which can be used to cancel the request.
+
+     NOTE: AbortSignal is a client-only operation. Using it to cancel an
+     operation will not cancel the request in the service. You will still
+     be charged usage for any applicable operations.
+     */
+    abortSignal?: AbortSignal;
+}
+
+/** Config for batches.get parameters. */
+export declare interface GetBatchJobParameters {
+    /** A fully-qualified BatchJob resource name or ID.
+     Example: "projects/.../locations/.../batchPredictionJobs/456"
+     or "456" when project and location are initialized in the client.
+     */
+    name: string;
+    /** Optional parameters for the request. */
+    config?: GetBatchJobConfig;
+}
+
 /** Optional parameters for caches.get method. */
 export declare interface GetCachedContentConfig {
     /** Used to override HTTP request options. */
@@ -2688,6 +2977,7 @@ export declare class GoogleGenAI {
     private readonly apiVersion?;
     readonly models: Models;
     readonly live: Live;
+    readonly batches: Batches;
     readonly chats: Chats;
     readonly caches: Caches;
     readonly files: Files;
@@ -2986,6 +3276,8 @@ export declare interface HttpOptions {
     headers?: Record<string, string>;
     /** Timeout for the request in milliseconds. */
     timeout?: number;
+    /** Extra parameters to add to the request body. */
+    extraBody?: Record<string, unknown>;
 }
 
 /**
@@ -3073,6 +3365,29 @@ export declare enum ImagePromptLanguage {
     hi = "hi"
 }
 
+/** Config for inlined request. */
+export declare interface InlinedRequest {
+    /** ID of the model to use. For a list of models, see `Google models
+     <https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models>`_. */
+    model?: string;
+    /** Content of the request.
+     */
+    contents?: ContentListUnion;
+    /** Configuration that contains optional model parameters.
+     */
+    config?: GenerateContentConfig;
+}
+
+/** Config for `inlined_responses` parameter. */
+export declare class InlinedResponse {
+    /** The response to the request.
+     */
+    response?: GenerateContentResponse;
+    /** The error encountered while processing the request.
+     */
+    error?: JobError;
+}
+
 /** Represents a time interval, encoded as a start time (inclusive) and an end time (exclusive).
 
  The start time must be less than or equal to the end time.
@@ -3087,7 +3402,17 @@ export declare interface Interval {
     endTime?: string;
 }
 
-/** Output only. The detailed state of the job. */
+/** Job error. */
+export declare interface JobError {
+    /** A list of messages that carry the error details. There is a common set of message types for APIs to use. */
+    details?: string[];
+    /** The status code. */
+    code?: number;
+    /** A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the `details` field. */
+    message?: string;
+}
+
+/** Job state. */
 export declare enum JobState {
     /**
      * The job state is unspecified.
@@ -3130,7 +3455,7 @@ export declare enum JobState {
      */
     JOB_STATE_EXPIRED = "JOB_STATE_EXPIRED",
     /**
-     * The job is being updated. Only jobs in the `RUNNING` state can be updated. After updating, the job goes back to the `RUNNING` state.
+     * The job is being updated. Only jobs in the `JOB_STATE_RUNNING` state can be updated. After updating, the job goes back to the `JOB_STATE_RUNNING` state.
      */
     JOB_STATE_UPDATING = "JOB_STATE_UPDATING",
     /**
@@ -3165,6 +3490,33 @@ export declare interface LatLng {
     longitude?: number;
 }
 
+/** Config for optional parameters. */
+export declare interface ListBatchJobsConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+    /** Abort signal which can be used to cancel the request.
+
+     NOTE: AbortSignal is a client-only operation. Using it to cancel an
+     operation will not cancel the request in the service. You will still
+     be charged usage for any applicable operations.
+     */
+    abortSignal?: AbortSignal;
+    pageSize?: number;
+    pageToken?: string;
+    filter?: string;
+}
+
+/** Config for batches.list parameters. */
+export declare interface ListBatchJobsParameters {
+    config?: ListBatchJobsConfig;
+}
+
+/** Config for batches.list return value. */
+export declare class ListBatchJobsResponse {
+    nextPageToken?: string;
+    batchJobs?: BatchJob[];
+}
+
 /** Config for caches.list method. */
 export declare interface ListCachedContentsConfig {
     /** Used to override HTTP request options. */
@@ -4772,8 +5124,17 @@ export declare type PartUnion = Part | string;
 
 /** Enum that controls the generation of people. */
 export declare enum PersonGeneration {
+    /**
+     * Block generation of images of people.
+     */
     DONT_ALLOW = "DONT_ALLOW",
+    /**
+     * Generate images of adults, but not children.
+     */
     ALLOW_ADULT = "ALLOW_ADULT",
+    /**
+     * Generate images that include adults and children.
+     */
     ALLOW_ALL = "ALLOW_ALL"
 }
 
@@ -5550,7 +5911,7 @@ export declare interface ThinkingConfig {
     /** Indicates whether to include thoughts in the response. If true, thoughts are returned only if the model supports thought and thoughts are available.
      */
     includeThoughts?: boolean;
-    /** Indicates the thinking budget in tokens.
+    /** Indicates the thinking budget in tokens. 0 is DISABLED. -1 is AUTOMATIC. The default values and allowed ranges are model dependent.
      */
     thinkingBudget?: number;
 }
@@ -5957,6 +6318,7 @@ declare namespace types {
         ControlReferenceType,
         SubjectReferenceType,
         EditMode,
+        VideoCompressionQuality,
         FileState,
         FileSource,
         MediaModality,
@@ -6023,6 +6385,8 @@ declare namespace types {
         GenerationConfigRoutingConfig,
         GenerateContentConfig,
         GenerateContentParameters,
+        HttpResponse,
+        LiveCallbacks,
         GoogleTypeDate,
         Citation,
         CitationMetadata,
@@ -6147,14 +6511,27 @@ declare namespace types {
         ListFilesResponse,
         CreateFileConfig,
         CreateFileParameters,
-        HttpResponse,
-        LiveCallbacks,
         CreateFileResponse,
         GetFileConfig,
         GetFileParameters,
         DeleteFileConfig,
         DeleteFileParameters,
         DeleteFileResponse,
+        InlinedRequest,
+        BatchJobSource,
+        JobError,
+        InlinedResponse,
+        BatchJobDestination,
+        CreateBatchJobConfig,
+        CreateBatchJobParameters,
+        BatchJob,
+        GetBatchJobConfig,
+        GetBatchJobParameters,
+        CancelBatchJobConfig,
+        CancelBatchJobParameters,
+        ListBatchJobsConfig,
+        ListBatchJobsParameters,
+        ListBatchJobsResponse,
         GetOperationConfig,
         GetOperationParameters,
         FetchPredictOperationConfig,
@@ -6237,7 +6614,8 @@ declare namespace types {
         SpeechConfigUnion,
         ToolUnion,
         ToolListUnion,
-        DownloadableFileUnion
+        DownloadableFileUnion,
+        BatchJobSourceUnion
     }
 }
 
@@ -6363,6 +6741,15 @@ export declare interface UpscaleImageConfig {
     /** The level of compression if the ``output_mime_type`` is
      ``image/jpeg``. */
     outputCompressionQuality?: number;
+    /** Whether to add an image enhancing step before upscaling.
+     It is expected to suppress the noise and JPEG compression artifacts
+     from the input image. */
+    enhanceInputImage?: boolean;
+    /** With a higher image preservation factor, the original image
+     pixels are more respected. With a lower image preservation factor, the
+     output image will have be more different from the input image, but
+     with finer details and less noise. */
+    imagePreservationFactor?: number;
 }
 
 /** User-facing config UpscaleImageParameters. */
@@ -6499,6 +6886,20 @@ export declare interface Video {
     mimeType?: string;
 }
 
+/** Enum that controls the compression quality of the generated videos. */
+export declare enum VideoCompressionQuality {
+    /**
+     * Optimized video compression quality. This will produce videos
+     with a compressed, smaller file size.
+     */
+    OPTIMIZED = "OPTIMIZED",
+    /**
+     * Lossless video compression quality. This will produce videos
+     with a larger file size.
+     */
+    LOSSLESS = "LOSSLESS"
+}
+
 /** Describes how the video in the Part should be used by the model. */
 export declare interface VideoMetadata {
     /** The frame rate of the video sent to the model. If not specified, the