@google/genai 0.6.0 → 0.7.0

package/dist/genai.d.ts

@@ -187,6 +187,12 @@ export declare class Caches extends BaseModule {
     /**
      * Creates a cached contents resource.
      *
+     * @remarks
+     * Context caching is only supported for specific models. See [Gemini
+     * Developer API reference] (https://ai.google.dev/gemini-api/docs/caching?lang=node/context-cac)
+     * and [Vertex AI reference] (https://cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-overview#supported_models)
+     * for more information.
+     *
      * @param params - The parameters for the create request.
      * @return The created cached content.
      *
@@ -194,7 +200,7 @@ export declare class Caches extends BaseModule {
      * ```ts
      * const contents = ...; // Initialize the content to cache.
      * const response = await ai.caches.create({
-     *   model: 'gemini-2.0-flash',
+     *   model: 'gemini-1.5-flash',
      *   config: {
      *    'contents': contents,
      *    'displayName': 'test cache',
@@ -578,9 +584,9 @@ export declare class CountTokensResponse {
 export declare interface CreateCachedContentConfig {
     /** Used to override HTTP request options. */
     httpOptions?: HttpOptions;
-    /** The TTL for this resource. The expiration time is computed: now + TTL. */
+    /** The TTL for this resource. The expiration time is computed: now + TTL. It is a duration string, with up to nine fractional digits, terminated by 's'. Example: "3.5s". */
     ttl?: string;
-    /** Timestamp of when this resource is considered expired. */
+    /** Timestamp of when this resource is considered expired. Uses RFC 3339 format, Example: 2014-10-02T15:01:23Z. */
     expireTime?: string;
     /** The user-generated meaningful display name of the cached content.
      */
@@ -725,6 +731,24 @@ export declare interface DeleteCachedContentParameters {
 export declare class DeleteCachedContentResponse {
 }
 
+/** Used to override the default configuration. */
+export declare interface DeleteFileConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+}
+
+/** Generates the parameters for the get method. */
+export declare interface DeleteFileParameters {
+    /** The name identifier for the file to be deleted. */
+    name: string;
+    /** Used to override the default configuration. */
+    config?: DeleteFileConfig;
+}
+
+/** Response for the delete file method. */
+export declare class DeleteFileResponse {
+}
+
 /** Used to override the default configuration. */
 export declare interface DownloadFileConfig {
     /** Used to override HTTP request options. */
@@ -810,6 +834,20 @@ export declare interface ExecutableCode {
     language?: Language;
 }
 
+export declare interface FetchPredictOperationConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+}
+
+/** Parameters for the fetchPredictOperation method. */
+export declare interface FetchPredictOperationParameters {
+    /** The server-assigned name for the operation. */
+    operationName: string;
+    resourceName: string;
+    /** Used to override the default configuration. */
+    config?: FetchPredictOperationConfig;
+}
+
 /** A file uploaded to the API. */
 declare interface File_2 {
     /** The `File` resource name. The ID (name excluding the "files/" prefix) can contain up to 40 characters that are lowercase alphanumeric or dashes (-). The ID cannot start or end with a dash. If the name is empty on create, a unique name will be generated. Example: `files/123-456` */
@@ -819,7 +857,7 @@ declare interface File_2 {
     /** Output only. MIME type of the file. */
     mimeType?: string;
     /** Output only. Size of the file in bytes. */
-    sizeBytes?: number;
+    sizeBytes?: string;
     /** Output only. The timestamp of when the `File` was created. */
     createTime?: string;
     /** Output only. The timestamp of when the `File` will be deleted. Only set if the `File` is scheduled to expire. */
@@ -851,7 +889,7 @@ export declare interface FileData {
     mimeType?: string;
 }
 
-declare class Files extends BaseModule {
+export declare class Files extends BaseModule {
     private readonly apiClient;
     constructor(apiClient: ApiClient);
     /**
@@ -897,7 +935,6 @@ declare class Files extends BaseModule {
      *
      * @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,
@@ -933,6 +970,20 @@ declare class Files extends BaseModule {
      * ```
      */
     get(params: types.GetFileParameters): Promise<types.File>;
+    /**
+     * Deletes a remotely stored file.
+     *
+     * @param params - The parameters for the delete request.
+     * @return The DeleteFileResponse, the response for the delete method.
+     *
+     * @example
+     * The following code deletes an example file named "files/mehozpxf877d".
+     *
+     * ```ts
+     * await ai.files.delete({name: file.name});
+     * ```
+     */
+    delete(params: types.DeleteFileParameters): Promise<types.DeleteFileResponse>;
 }
 
 export declare enum FileSource {
@@ -1355,6 +1406,12 @@ export declare interface GeneratedImage {
     enhancedPrompt?: string;
 }
 
+/** A generated video. */
+export declare interface GeneratedVideo {
+    /** The output video */
+    video?: Video;
+}
+
 /** The config for generating an images. */
 export declare interface GenerateImagesConfig {
     /** Used to override HTTP request options. */
@@ -1386,7 +1443,8 @@ export declare interface GenerateImagesConfig {
     /** Allows generation of people by the model.
      */
     personGeneration?: PersonGeneration;
-    /** Whether to report the safety scores of each image in the response.
+    /** Whether to report the safety scores of each generated image and
+     the positive prompt in the response.
      */
     includeSafetyAttributes?: boolean;
     /** Whether to include the Responsible AI filter reason if the image
@@ -1429,6 +1487,78 @@ export declare class GenerateImagesResponse {
     /** List of generated images.
      */
     generatedImages?: GeneratedImage[];
+    /** Safety attributes of the positive prompt. Only populated if
+     ``include_safety_attributes`` is set to True.
+     */
+    positivePromptSafetyAttributes?: SafetyAttributes;
+}
+
+/** Configuration for generating videos. */
+export declare interface GenerateVideosConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+    /** Number of output videos. */
+    numberOfVideos?: number;
+    /** The gcs bucket where to save the generated videos. */
+    outputGcsUri?: string;
+    /** Frames per second for video generation. */
+    fps?: number;
+    /** Duration of the clip for video generation in seconds. */
+    durationSeconds?: number;
+    /** The RNG seed. If RNG seed is exactly same for each request with unchanged inputs, the prediction results will be consistent. Otherwise, a random RNG seed will be used each time to produce a different result. */
+    seed?: number;
+    /** The aspect ratio for the generated video. 16:9 (landscape) and 9:16 (portrait) are supported. */
+    aspectRatio?: string;
+    /** The resolution for the generated video. 1280x720, 1920x1080 are supported. */
+    resolution?: string;
+    /** Whether allow to generate person videos, and restrict to specific ages. Supported values are: dont_allow, allow_adult. */
+    personGeneration?: string;
+    /** The pubsub topic where to publish the video generation progress. */
+    pubsubTopic?: string;
+    /** Optional field in addition to the text content. Negative prompts can be explicitly stated here to help generate the video. */
+    negativePrompt?: string;
+    /** Whether to use the prompt rewriting logic. */
+    enhancePrompt?: boolean;
+}
+
+/** A video generation operation. */
+export declare interface GenerateVideosOperation {
+    /** The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`. */
+    name?: string;
+    /** Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.  Any method that returns a long-running operation should document the metadata type, if any. */
+    metadata?: Record<string, unknown>;
+    /** If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available. */
+    done?: boolean;
+    /** The error result of the operation in case of failure or cancellation. */
+    error?: Record<string, unknown>;
+    /** The normal response of the operation in case of success. */
+    response?: Record<string, unknown>;
+    /** The generated videos. */
+    result?: GenerateVideosResponse;
+}
+
+/** Class that represents the parameters for generating an image. */
+export declare interface GenerateVideosParameters {
+    /** 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;
+    /** The text prompt for generating the videos. Optional for image to video use cases. */
+    prompt?: string;
+    /** The input image for generating the videos.
+     Optional if prompt is provided. */
+    image?: Image_2;
+    /** Configuration for generating videos. */
+    config?: GenerateVideosConfig;
+}
+
+/** Response with generated videos. */
+export declare class GenerateVideosResponse {
+    /** List of the generated videos */
+    generatedVideos?: GeneratedVideo[];
+    /** Returns if any videos were filtered due to RAI policies. */
+    raiMediaFilteredCount?: number;
+    /** Returns rai failure reasons if any. */
+    raiMediaFilteredReasons?: string[];
 }
 
 /** Generation config. */
@@ -1515,6 +1645,19 @@ export declare interface GetFileParameters {
     config?: GetFileConfig;
 }
 
+export declare interface GetOperationConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+}
+
+/** Parameters for the GET method. */
+export declare interface GetOperationParameters {
+    /** The server-assigned name for the operation. */
+    operationName: string;
+    /** Used to override the default configuration. */
+    config?: GetOperationConfig;
+}
+
 declare function getValueByPath(data: unknown, keys: string[]): unknown;
 
 /**
@@ -1558,6 +1701,7 @@ export declare class GoogleGenAI {
     readonly chats: Chats;
     readonly caches: Caches;
     readonly files: Files;
+    readonly operations: Operations;
     constructor(options: GoogleGenAIOptions);
 }
 
@@ -2204,6 +2348,15 @@ export declare enum MaskReferenceMode {
     MASK_MODE_SEMANTIC = "MASK_MODE_SEMANTIC"
 }
 
+export declare enum MediaModality {
+    MODALITY_UNSPECIFIED = "MODALITY_UNSPECIFIED",
+    TEXT = "TEXT",
+    IMAGE = "IMAGE",
+    VIDEO = "VIDEO",
+    AUDIO = "AUDIO",
+    DOCUMENT = "DOCUMENT"
+}
+
 export declare enum MediaResolution {
     MEDIA_RESOLUTION_UNSPECIFIED = "MEDIA_RESOLUTION_UNSPECIFIED",
     MEDIA_RESOLUTION_LOW = "MEDIA_RESOLUTION_LOW",
@@ -2221,7 +2374,7 @@ export declare enum Modality {
 /** Represents token counting info for a single modality. */
 export declare interface ModalityTokenCount {
     /** The modality associated with this token count. */
-    modality?: Modality;
+    modality?: MediaModality;
     /** Number of tokens. */
     tokenCount?: number;
 }
@@ -2315,6 +2468,28 @@ export declare class Models extends BaseModule {
      * ```
      */
     generateContentStream: (params: types.GenerateContentParameters) => Promise<AsyncGenerator<types.GenerateContentResponse>>;
+    /**
+     * 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.
+     * @return The response from the API.
+     *
+     * @example
+     * ```ts
+     * 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);
+     * ```
+     */
+    generateImages: (params: types.GenerateImagesParameters) => Promise<types.GenerateImagesResponse>;
     private generateContentInternal;
     private generateContentStreamInternal;
     /**
@@ -2358,7 +2533,7 @@ export declare class Models extends BaseModule {
      * console.log(response?.generatedImages?.[0]?.image?.imageBytes);
      * ```
      */
-    generateImages(params: types.GenerateImagesParameters): Promise<types.GenerateImagesResponse>;
+    private generateImagesInternal;
     /**
      * Counts the number of tokens in the given contents. Multimodal input is
      * supported for Gemini models.
@@ -2395,6 +2570,52 @@ export declare class Models extends BaseModule {
      * ```
      */
     computeTokens(params: types.ComputeTokensParameters): Promise<types.ComputeTokensResponse>;
+    /**
+     *  Generates videos based on a text description and configuration.
+     *
+     * @param params - The parameters for generating videos.
+     * @return A Promise<GenerateVideosOperation> which allows you to track the progress and eventually retrieve the generated videos using the operations.get method.
+     *
+     * @example
+     * ```ts
+     * const operation = await ai.models.generateVideos({
+     *  model: 'veo-2.0-generate-001',
+     *  prompt: 'A neon hologram of a cat driving at top speed',
+     *  config: {
+     *    numberOfVideos: 1
+     * });
+     *
+     * while (!operation.done) {
+     *   await new Promise(resolve => setTimeout(resolve, 10000));
+     *   operation = await ai.operations.get({operation: operation});
+     * }
+     *
+     * console.log(operation.result?.generatedVideos?.[0]?.video?.uri);
+     * ```
+     */
+    generateVideos(params: types.GenerateVideosParameters): Promise<types.GenerateVideosOperation>;
+}
+
+/** Parameters for the get method of the operations module. */
+export declare interface OperationGetParameters {
+    /** The operation to be retrieved. */
+    operation: GenerateVideosOperation;
+    /** Used to override the default configuration. */
+    config?: GetOperationConfig;
+}
+
+export declare class Operations extends BaseModule {
+    private readonly apiClient;
+    constructor(apiClient: ApiClient);
+    /**
+     * Gets the status of a long-running operation.
+     *
+     * @param operation The Operation object returned by a previous API call.
+     * @return The updated Operation object, with the latest status or result.
+     */
+    get(parameters: types.OperationGetParameters): Promise<types.GenerateVideosOperation>;
+    private getVideosOperationInternal;
+    private fetchPredictVideosOperationInternal;
 }
 
 /**
@@ -2417,7 +2638,7 @@ export declare enum Outcome {
 /**
  * Pagers for the GenAI List APIs.
  */
-declare enum PagedItem {
+export declare enum PagedItem {
     PAGED_ITEM_BATCH_JOBS = "batchJobs",
     PAGED_ITEM_MODELS = "models",
     PAGED_ITEM_TUNING_JOBS = "tuningJobs",
@@ -2444,7 +2665,7 @@ declare interface PagedItemResponse<T> {
 /**
  * Pager class for iterating through paginated results.
  */
-declare class Pager<T> implements AsyncIterable<T> {
+export declare class Pager<T> implements AsyncIterable<T> {
     private nameInternal;
     private pageInternal;
     private paramsInternal;
@@ -2647,6 +2868,9 @@ export declare interface SafetyAttributes {
     /** List of scores of each categories.
      */
     scores?: number[];
+    /** Internal use only.
+     */
+    contentType?: string;
 }
 
 export declare enum SafetyFilterLevel {
@@ -2696,8 +2920,6 @@ export declare interface Schema {
     default?: unknown;
     /** Optional. Maximum length of the Type.STRING */
     maxLength?: string;
-    /** Optional. The title of the Schema. */
-    title?: string;
     /** Optional. SCHEMA FIELDS FOR TYPE STRING Minimum length of the Type.STRING */
     minLength?: string;
     /** Optional. Minimum number of the properties for Type.OBJECT. */
@@ -2730,6 +2952,8 @@ export declare interface Schema {
     propertyOrdering?: string[];
     /** Optional. Required properties of Type.OBJECT. */
     required?: string[];
+    /** Optional. The title of the Schema. */
+    title?: string;
     /** Optional. The type of the data. */
     type?: Type;
 }
@@ -2995,6 +3219,8 @@ export declare interface TestTableItem {
     hasUnion?: boolean;
     /** When set to a reason string, this test will be skipped in the API mode. Use this flag for tests that can not be reproduced with the real API. E.g. a test that deletes a resource. */
     skipInApiMode?: string;
+    /** Keys to ignore when comparing the request and response. This is useful for tests that are not deterministic. */
+    ignoreKeys?: string[];
 }
 
 /** The thinking features configuration. */
@@ -3089,6 +3315,7 @@ declare namespace types {
         MaskReferenceMode,
         ControlReferenceType,
         SubjectReferenceType,
+        MediaModality,
         VideoMetadata,
         CodeExecutionResult,
         ExecutableCode,
@@ -3162,6 +3389,12 @@ declare namespace types {
         ComputeTokensParameters,
         TokensInfo,
         ComputeTokensResponse,
+        GenerateVideosConfig,
+        GenerateVideosParameters,
+        Video,
+        GeneratedVideo,
+        GenerateVideosResponse,
+        GenerateVideosOperation,
         CreateCachedContentConfig,
         CreateCachedContentParameters,
         CachedContentUsageMetadata,
@@ -3188,6 +3421,13 @@ declare namespace types {
         CreateFileResponse,
         GetFileConfig,
         GetFileParameters,
+        DeleteFileConfig,
+        DeleteFileParameters,
+        DeleteFileResponse,
+        GetOperationConfig,
+        GetOperationParameters,
+        FetchPredictOperationConfig,
+        FetchPredictOperationParameters,
         TestTableItem,
         TestTableFile,
         ReplayRequest,
@@ -3224,6 +3464,7 @@ declare namespace types {
         LiveSendClientContentParameters,
         LiveSendRealtimeInputParameters,
         LiveSendToolResponseParameters,
+        OperationGetParameters,
         PartUnion,
         PartListUnion,
         ContentUnion,
@@ -3238,9 +3479,9 @@ declare namespace types {
 export declare interface UpdateCachedContentConfig {
     /** Used to override HTTP request options. */
     httpOptions?: HttpOptions;
-    /** The TTL for this resource. The expiration time is computed: now + TTL. */
+    /** The TTL for this resource. The expiration time is computed: now + TTL. It is a duration string, with up to nine fractional digits, terminated by 's'. Example: "3.5s". */
     ttl?: string;
-    /** Timestamp of when this resource is considered expired. */
+    /** Timestamp of when this resource is considered expired. Uses RFC 3339 format, Example: 2014-10-02T15:01:23Z. */
     expireTime?: string;
 }
 
@@ -3327,10 +3568,12 @@ export declare interface UpscaleImageParameters {
     config?: UpscaleImageConfig;
 }
 
-/** Retrieve from Vertex AI Search datastore for grounding. See https://cloud.google.com/products/agent-builder */
+/** Retrieve from Vertex AI Search datastore or engine for grounding. datastore and engine are mutually exclusive. See https://cloud.google.com/products/agent-builder */
 export declare interface VertexAISearch {
-    /** Required. Fully-qualified Vertex AI Search data store resource ID. Format: `projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}` */
+    /** Optional. Fully-qualified Vertex AI Search data store resource ID. Format: `projects/{project}/locations/{location}/collections/{collection}/dataStores/{dataStore}` */
     datastore?: string;
+    /** Optional. Fully-qualified Vertex AI Search engine resource ID. Format: `projects/{project}/locations/{location}/collections/{collection}/engines/{engine}` */
+    engine?: string;
 }
 
 /** Retrieve from Vertex RAG Store for grounding. */
@@ -3353,6 +3596,16 @@ export declare interface VertexRagStoreRagResource {
     ragFileIds?: string[];
 }
 
+/** A generated video. */
+export declare interface Video {
+    /** Path to another storage. */
+    uri?: string;
+    /** Video bytes. */
+    videoBytes?: string;
+    /** Video encoding, for example "video/mp4". */
+    mimeType?: string;
+}
+
 /** Metadata describes the input video content. */
 export declare interface VideoMetadata {
     /** Optional. The end offset of the video. */