@google/genai 0.13.0 → 0.14.0

package/README.md

@@ -102,6 +102,33 @@ const ai = new GoogleGenAI({
 });
 ```
 
+## API Selection
+
+By default, the SDK uses the beta API endpoints provided by Google to support
+preview features in the APIs. The stable API endpoints can be selected by
+setting the API version to `v1`.
+
+To set the API version use `apiVersion`. For example, to set the API version to
+`v1` for Vertex AI:
+
+```typescript
+const ai = new GoogleGenAI({
+    vertexai: true,
+    project: 'your_project',
+    location: 'your_location',
+    apiVersion: 'v1'
+});
+```
+
+To set the API version to `v1alpha` for the Gemini Developer API:
+
+```typescript
+const ai = new GoogleGenAI({
+    apiKey: 'GEMINI_API_KEY',
+    apiVersion: 'v1alpha'
+});
+```
+
 ## GoogleGenAI overview
 
 All API features are accessed through an instance of the `GoogleGenAI` classes.
@@ -128,7 +155,6 @@ The submodules bundle together related API methods:
 More samples can be found in the
 [github samples directory](https://github.com/googleapis/js-genai/tree/main/sdk-samples).
 
-
 ### Streaming
 
 For quicker, more responsive API interactions use the `generateContentStream`

package/dist/genai.d.ts

@@ -274,6 +274,8 @@ export declare interface BaseUrlParameters {
 
 /** Content blob. */
 declare interface Blob_2 {
+    /** Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs. This field is not currently used in the Gemini GenerateContent calls. */
+    displayName?: string;
     /** Required. Raw bytes. */
     data?: string;
     /** Required. The IANA standard MIME type of the source data. */
@@ -560,6 +562,19 @@ export declare class Chats {
     create(params: types.CreateChatParameters): Chat;
 }
 
+/** Describes the machine learning model version checkpoint. */
+export declare interface Checkpoint {
+    /** The ID of the checkpoint.
+     */
+    checkpointId?: string;
+    /** The epoch of the checkpoint.
+     */
+    epoch?: string;
+    /** The step of the checkpoint.
+     */
+    step?: string;
+}
+
 /** Source attributions for content. */
 export declare interface Citation {
     /** Output only. End index into the content. */
@@ -689,7 +704,7 @@ export declare interface ControlReferenceConfig {
  A control image is an image that represents a sketch image of areas for the
  model to fill in based on the prompt.
  */
-export declare interface ControlReferenceImage {
+export declare class ControlReferenceImage {
     /** The reference image for the editing operation. */
     referenceImage?: Image_2;
     /** The id of the reference image. */
@@ -698,6 +713,8 @@ export declare interface ControlReferenceImage {
     referenceType?: string;
     /** Configuration for the control reference image. */
     config?: ControlReferenceConfig;
+    /** Internal method to convert to ReferenceImageAPIInternal. */
+    toReferenceImageAPI(): any;
 }
 
 /** Enum representing the control type of a control reference image. */
@@ -912,6 +929,8 @@ export declare interface CreateTuningJobConfig {
     epochCount?: number;
     /** Multiplier for adjusting the default learning rate. */
     learningRateMultiplier?: number;
+    /** If set to true, disable intermediate checkpoints for SFT and only the last checkpoint will be exported. Otherwise, enable intermediate checkpoints for SFT. */
+    exportLastCheckpointOnly?: boolean;
     /** Adapter size for tuning. */
     adapterSize?: AdapterSize;
     /** The batch size hyperparameter for tuning. If not set, a default of 4 or 16 will be used based on the number of training examples. */
@@ -1144,6 +1163,100 @@ export declare enum DynamicRetrievalConfigMode {
     MODE_DYNAMIC = "MODE_DYNAMIC"
 }
 
+/** Configuration for editing an image. */
+export declare interface EditImageConfig {
+    /** 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;
+    /** Cloud Storage URI used to store the generated images.
+     */
+    outputGcsUri?: string;
+    /** Description of what to discourage in the generated images.
+     */
+    negativePrompt?: string;
+    /** Number of images to generate.
+     */
+    numberOfImages?: number;
+    /** Aspect ratio of the generated images.
+     */
+    aspectRatio?: string;
+    /** Controls how much the model adheres to the text prompt. Large
+     values increase output and prompt alignment, but may compromise image
+     quality.
+     */
+    guidanceScale?: number;
+    /** Random seed for image generation. This is not available when
+     ``add_watermark`` is set to true.
+     */
+    seed?: number;
+    /** Filter level for safety filtering.
+     */
+    safetyFilterLevel?: SafetyFilterLevel;
+    /** Allows generation of people by the model.
+     */
+    personGeneration?: PersonGeneration;
+    /** 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
+     is filtered out of the response.
+     */
+    includeRaiReason?: boolean;
+    /** Language of the text in the prompt.
+     */
+    language?: ImagePromptLanguage;
+    /** MIME type of the generated image.
+     */
+    outputMimeType?: string;
+    /** Compression quality of the generated image (for ``image/jpeg``
+     only).
+     */
+    outputCompressionQuality?: number;
+    /** Describes the editing mode for the request. */
+    editMode?: EditMode;
+    /** The number of sampling steps. A higher value has better image
+     quality, while a lower value has better latency. */
+    baseSteps?: number;
+}
+
+/** Parameters for the request to edit an image. */
+export declare interface EditImageParameters {
+    /** The model to use. */
+    model: string;
+    /** A text description of the edit to apply to the image. */
+    prompt: string;
+    /** The reference images for Imagen 3 editing. */
+    referenceImages: ReferenceImage[];
+    /** Configuration for editing. */
+    config?: EditImageConfig;
+}
+
+/** Response for the request to edit an image. */
+export declare class EditImageResponse {
+    /** Generated images. */
+    generatedImages?: GeneratedImage[];
+}
+
+/** Enum representing the Imagen 3 Edit mode. */
+export declare enum EditMode {
+    EDIT_MODE_DEFAULT = "EDIT_MODE_DEFAULT",
+    EDIT_MODE_INPAINT_REMOVAL = "EDIT_MODE_INPAINT_REMOVAL",
+    EDIT_MODE_INPAINT_INSERTION = "EDIT_MODE_INPAINT_INSERTION",
+    EDIT_MODE_OUTPAINT = "EDIT_MODE_OUTPAINT",
+    EDIT_MODE_CONTROLLED_EDITING = "EDIT_MODE_CONTROLLED_EDITING",
+    EDIT_MODE_STYLE = "EDIT_MODE_STYLE",
+    EDIT_MODE_BGSWAP = "EDIT_MODE_BGSWAP",
+    EDIT_MODE_PRODUCT_IMAGE = "EDIT_MODE_PRODUCT_IMAGE"
+}
+
+/** Optional parameters for the embed_content method. */
 export declare interface EmbedContentConfig {
     /** Used to override HTTP request options. */
     httpOptions?: HttpOptions;
@@ -1610,10 +1723,21 @@ export declare interface GenerateContentConfig {
      random number is used.
      */
     seed?: number;
-    /** Output response media type of the generated candidate text.
+    /** Output response mimetype of the generated candidate text.
+     Supported mimetype:
+     - `text/plain`: (default) Text output.
+     - `application/json`: JSON response in the candidates.
+     The model needs to be prompted to output the appropriate response type,
+     otherwise the behavior is undefined.
+     This is a preview feature.
      */
     responseMimeType?: string;
-    /** Schema that the generated candidate text must adhere to.
+    /** 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?: SchemaUnion;
     /** Configuration for model router requests.
@@ -3106,7 +3230,6 @@ export declare interface LiveServerSessionResumptionUpdate {
     lastConsumedClientMessageIndex?: string;
 }
 
-/** Sent in response to a `LiveGenerateContentSetup` message from the client. */
 export declare interface LiveServerSetupComplete {
 }
 
@@ -3174,7 +3297,7 @@ export declare interface MaskReferenceConfig {
  image. If the user provides a mask image, the mask must be in the same
  dimensions as the raw image.
  */
-export declare interface MaskReferenceImage {
+export declare class MaskReferenceImage {
     /** The reference image for the editing operation. */
     referenceImage?: Image_2;
     /** The id of the reference image. */
@@ -3183,6 +3306,8 @@ export declare interface MaskReferenceImage {
     referenceType?: string;
     /** Configuration for the mask reference image. */
     config?: MaskReferenceConfig;
+    /** Internal method to convert to ReferenceImageAPIInternal. */
+    toReferenceImageAPI(): any;
 }
 
 /** Enum representing the mask mode of a mask reference image. */
@@ -3260,6 +3385,11 @@ export declare interface Model {
     outputTokenLimit?: number;
     /** List of actions that are supported by the model. */
     supportedActions?: string[];
+    /** The default checkpoint id of a model version.
+     */
+    defaultCheckpointId?: string;
+    /** The checkpoints of the model. */
+    checkpoints?: Checkpoint[];
 }
 
 export declare class Models extends BaseModule {
@@ -3349,9 +3479,7 @@ 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
@@ -3369,6 +3497,48 @@ export declare class Models extends BaseModule {
      */
     generateImages: (params: types.GenerateImagesParameters) => Promise<types.GenerateImagesResponse>;
     list: (params?: types.ListModelsParameters) => Promise<Pager<types.Model>>;
+    /**
+     * Edits an image based on a prompt, list of reference images, and configuration.
+     *
+     * @param params - The parameters for editing an image.
+     * @return The response from the API.
+     *
+     * @example
+     * ```ts
+     * const response = await client.models.editImage({
+     *  model: 'imagen-3.0-capability-001',
+     *  prompt: 'Generate an image containing a mug with the product logo [1] visible on the side of the mug.',
+     *  referenceImages: [subjectReferenceImage]
+     *  config: {
+     *    numberOfImages: 1,
+     *    includeRaiReason: true,
+     *  },
+     * });
+     * console.log(response?.generatedImages?.[0]?.image?.imageBytes);
+     * ```
+     */
+    editImage: (params: types.EditImageParameters) => Promise<types.EditImageResponse>;
+    /**
+     * Upscales an image based on an image, upscale factor, and configuration.
+     * Only supported in Vertex AI currently.
+     *
+     * @param params - The parameters for upscaling an image.
+     * @return The response from the API.
+     *
+     * @example
+     * ```ts
+     * const response = await client.models.upscaleImage({
+     *  model: 'imagen-3.0-generate-002',
+     *  image: image,
+     *  upscaleFactor: 'x2',
+     *  config: {
+     *    includeRaiReason: true,
+     *  },
+     * });
+     * console.log(response?.generatedImages?.[0]?.image?.imageBytes);
+     * ```
+     */
+    upscaleImage: (params: types.UpscaleImageParameters) => Promise<types.UpscaleImageResponse>;
     private generateContentInternal;
     private generateContentStreamInternal;
     /**
@@ -3413,6 +3583,8 @@ export declare class Models extends BaseModule {
      * ```
      */
     private generateImagesInternal;
+    private editImageInternal;
+    private upscaleImageInternal;
     /**
      * Fetches information about a model by name.
      *
@@ -3706,6 +3878,8 @@ export declare interface Part {
     videoMetadata?: VideoMetadata;
     /** Indicates if the part is thought from the model. */
     thought?: boolean;
+    /** Optional. Inlined bytes data. */
+    inlineData?: Blob_2;
     /** Optional. Result of executing the [ExecutableCode]. */
     codeExecutionResult?: CodeExecutionResult;
     /** Optional. Code generated by the model that is meant to be executed. */
@@ -3716,8 +3890,6 @@ export declare interface Part {
     functionCall?: FunctionCall;
     /** Optional. The result output of a [FunctionCall] that contains a string representing the [FunctionDeclaration.name] and a structured JSON object containing any output from the function call. It is used as context to the model. */
     functionResponse?: FunctionResponse;
-    /** Optional. Inlined bytes data. */
-    inlineData?: Blob_2;
     /** Optional. Text part (can be code). */
     text?: string;
 }
@@ -3804,13 +3976,15 @@ export declare interface RagRetrievalConfigRankingRankService {
  It can optionally be provided in addition to a mask reference image or
  a style reference image.
  */
-export declare interface RawReferenceImage {
+export declare class RawReferenceImage {
     /** The reference image for the editing operation. */
     referenceImage?: Image_2;
     /** The id of the reference image. */
     referenceId?: number;
     /** The type of the reference image. Only set by the SDK. */
     referenceType?: string;
+    /** Internal method to convert to ReferenceImageAPIInternal. */
+    toReferenceImageAPI(): any;
 }
 
 /** Marks the end of user activity.
@@ -3827,6 +4001,8 @@ export declare interface RealtimeInputConfig {
     turnCoverage?: TurnCoverage;
 }
 
+export declare type ReferenceImage = RawReferenceImage | MaskReferenceImage | ControlReferenceImage | StyleReferenceImage | SubjectReferenceImage;
+
 /** Represents a recorded session. */
 export declare interface ReplayFile {
     replayId?: string;
@@ -4224,7 +4400,7 @@ export declare interface StyleReferenceConfig {
  A raw reference image can also be provided as a destination for the style to
  be applied to.
  */
-export declare interface StyleReferenceImage {
+export declare class StyleReferenceImage {
     /** The reference image for the editing operation. */
     referenceImage?: Image_2;
     /** The id of the reference image. */
@@ -4233,6 +4409,8 @@ export declare interface StyleReferenceImage {
     referenceType?: string;
     /** Configuration for the style reference image. */
     config?: StyleReferenceConfig;
+    /** Internal method to convert to ReferenceImageAPIInternal. */
+    toReferenceImageAPI(): any;
 }
 
 /** Configuration for a Subject reference image. */
@@ -4251,7 +4429,7 @@ export declare interface SubjectReferenceConfig {
  A raw reference image can also be provided as a destination for the subject to
  be applied to.
  */
-export declare interface SubjectReferenceImage {
+export declare class SubjectReferenceImage {
     /** The reference image for the editing operation. */
     referenceImage?: Image_2;
     /** The id of the reference image. */
@@ -4260,6 +4438,7 @@ export declare interface SubjectReferenceImage {
     referenceType?: string;
     /** Configuration for the subject reference image. */
     config?: SubjectReferenceConfig;
+    toReferenceImageAPI(): any;
 }
 
 /** Enum representing the subject type of a subject reference image. */
@@ -4346,6 +4525,8 @@ export declare interface SupervisedTuningSpec {
     trainingDatasetUri?: string;
     /** Optional. Cloud Storage path to file containing validation dataset for tuning. The dataset must be formatted as a JSONL file. */
     validationDatasetUri?: string;
+    /** Optional. If set to true, disable intermediate checkpoints for SFT and only the last checkpoint will be exported. */
+    exportLastCheckpointOnly?: boolean;
 }
 
 export declare interface TestTableFile {
@@ -4454,6 +4635,27 @@ export declare interface TunedModel {
     model?: string;
     /** Output only. A resource name of an Endpoint. Format: `projects/{project}/locations/{location}/endpoints/{endpoint}`. */
     endpoint?: string;
+    /** The checkpoints associated with this TunedModel.
+     This field is only populated for tuning jobs that enable intermediate
+     checkpoints. */
+    checkpoints?: TunedModelCheckpoint[];
+}
+
+/** TunedModelCheckpoint for the Tuned Model of a Tuning Job. */
+export declare interface TunedModelCheckpoint {
+    /** The ID of the checkpoint.
+     */
+    checkpointId?: string;
+    /** The epoch of the checkpoint.
+     */
+    epoch?: string;
+    /** The step of the checkpoint.
+     */
+    step?: string;
+    /** The Endpoint resource name that the checkpoint is deployed to.
+     Format: `projects/{project}/locations/{location}/endpoints/{endpoint}`.
+     */
+    endpoint?: string;
 }
 
 /** A tuned machine learning model. */
@@ -4627,23 +4829,24 @@ declare namespace types {
         SafetyFilterLevel,
         PersonGeneration,
         ImagePromptLanguage,
-        FileState,
-        FileSource,
         MaskReferenceMode,
         ControlReferenceType,
         SubjectReferenceType,
+        EditMode,
+        FileState,
+        FileSource,
         MediaModality,
         StartSensitivity,
         EndSensitivity,
         ActivityHandling,
         TurnCoverage,
+        Blob_2 as Blob,
         VideoMetadata,
         CodeExecutionResult,
         ExecutableCode,
         FileData,
         FunctionCall,
         FunctionResponse,
-        Blob_2 as Blob,
         Part,
         Content,
         HttpOptions,
@@ -4707,6 +4910,8 @@ declare namespace types {
         ModalityTokenCount,
         GenerateContentResponseUsageMetadata,
         GenerateContentResponse,
+        ReferenceImage,
+        EditImageParameters,
         EmbedContentConfig,
         EmbedContentParameters,
         ContentEmbeddingStatistics,
@@ -4719,10 +4924,18 @@ declare namespace types {
         SafetyAttributes,
         GeneratedImage,
         GenerateImagesResponse,
+        MaskReferenceConfig,
+        ControlReferenceConfig,
+        StyleReferenceConfig,
+        SubjectReferenceConfig,
+        EditImageConfig,
+        EditImageResponse,
+        UpscaleImageResponse,
         GetModelConfig,
         GetModelParameters,
         Endpoint,
         TunedModelInfo,
+        Checkpoint,
         Model,
         ListModelsConfig,
         ListModelsParameters,
@@ -4748,6 +4961,7 @@ declare namespace types {
         GenerateVideosOperation,
         GetTuningJobConfig,
         GetTuningJobParameters,
+        TunedModelCheckpoint,
         TunedModel,
         GoogleRpcStatus,
         SupervisedHyperParameters,
@@ -4820,13 +5034,9 @@ declare namespace types {
         UpscaleImageConfig,
         UpscaleImageParameters,
         RawReferenceImage,
-        MaskReferenceConfig,
         MaskReferenceImage,
-        ControlReferenceConfig,
         ControlReferenceImage,
-        StyleReferenceConfig,
         StyleReferenceImage,
-        SubjectReferenceConfig,
         SubjectReferenceImage,
         LiveServerSetupComplete,
         Transcription,
@@ -4848,6 +5058,7 @@ declare namespace types {
         ActivityStart,
         ActivityEnd,
         LiveClientRealtimeInput,
+        LiveSendRealtimeInputParameters,
         LiveClientToolResponse,
         LiveClientMessage,
         LiveConnectConfig,
@@ -4855,7 +5066,6 @@ declare namespace types {
         CreateChatParameters,
         SendMessageParameters,
         LiveSendClientContentParameters,
-        LiveSendRealtimeInputParameters,
         LiveSendToolResponseParameters,
         OperationGetParameters,
         BlobImageUnion,
@@ -4909,6 +5119,7 @@ export declare interface UpdateModelConfig {
     abortSignal?: AbortSignal;
     displayName?: string;
     description?: string;
+    defaultCheckpointId?: string;
 }
 
 /** Configuration for updating a tuned model. */
@@ -5005,6 +5216,11 @@ export declare interface UpscaleImageParameters {
     config?: UpscaleImageConfig;
 }
 
+export declare class UpscaleImageResponse {
+    /** Generated images. */
+    generatedImages?: GeneratedImage[];
+}
+
 /** Usage metadata about response(s). */
 export declare interface UsageMetadata {
     /** Number of tokens in the prompt. When `cached_content` is set, this is still the total effective prompt size meaning this includes the number of tokens in the cached content. */