diff --git a/common/api-review/vertexai.api.md b/common/api-review/vertexai.api.md index a1cd9cba066..4521aaf2b70 100644 --- a/common/api-review/vertexai.api.md +++ b/common/api-review/vertexai.api.md @@ -346,7 +346,7 @@ export class GenerativeModel extends VertexAIModel { // @public export function getGenerativeModel(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: RequestOptions): GenerativeModel; -// @public (undocumented) +// @beta export function getImagenModel(vertexAI: VertexAI, modelParams: ImagenModelParams, requestOptions?: RequestOptions): ImagenModel; // @public @@ -430,122 +430,87 @@ export enum HarmSeverity { HARM_SEVERITY_NEGLIGIBLE = "HARM_SEVERITY_NEGLIGIBLE" } -// @public (undocumented) +// @beta export enum ImagenAspectRatio { - // (undocumented) LANDSCAPE_16x9 = "16:9", - // (undocumented) LANDSCAPE_3x4 = "3:4", - // (undocumented) PORTRAIT_4x3 = "4:3", - // (undocumented) PORTRAIT_9x16 = "9:16", - // (undocumented) SQUARE = "1:1" } -// @public (undocumented) +// @public export interface ImagenGCSImage { - // (undocumented) gcsURI: string; - // (undocumented) mimeType: string; } -// @public (undocumented) +// @beta export interface ImagenGenerationConfig { - // (undocumented) addWatermark?: boolean; - // (undocumented) aspectRatio?: ImagenAspectRatio; - // (undocumented) imageFormat?: ImagenImageFormat; - // (undocumented) negativePrompt?: string; - // (undocumented) numberOfImages?: number; } -// @public (undocumented) +// @beta export interface ImagenGenerationResponse { - // (undocumented) filteredReason?: string; - // (undocumented) images: T[]; } -// @public +// @beta export class ImagenImageFormat { - // (undocumented) compressionQuality?: number; - // (undocumented) static jpeg(compressionQuality?: number): ImagenImageFormat; - // (undocumented) mimeType: string; - // (undocumented) static png(): ImagenImageFormat; } -// @public +// @beta export interface ImagenInlineImage { - // (undocumented) bytesBase64Encoded: string; - // (undocumented) mimeType: string; } -// @public (undocumented) +// @beta export class ImagenModel extends VertexAIModel { constructor(vertexAI: VertexAI, modelParams: ImagenModelParams, requestOptions?: RequestOptions | undefined); - // (undocumented) generateImages(prompt: string): Promise>; - // (undocumented) + // @internal generateImagesGCS(prompt: string, gcsURI: string): Promise>; - // (undocumented) generationConfig?: ImagenGenerationConfig; // (undocumented) requestOptions?: RequestOptions | undefined; - // (undocumented) safetySettings?: ImagenSafetySettings; } -// @public (undocumented) +// @beta export interface ImagenModelParams { - // (undocumented) generationConfig?: ImagenGenerationConfig; - // (undocumented) model: string; - // (undocumented) safetySettings?: ImagenSafetySettings; } -// @public (undocumented) +// @beta export enum ImagenPersonFilterLevel { - // (undocumented) ALLOW_ADULT = "allow_adult", - // (undocumented) ALLOW_ALL = "allow_all", - // (undocumented) BLOCK_ALL = "dont_allow" } -// @public (undocumented) +// @beta export enum ImagenSafetyFilterLevel { - // (undocumented) BLOCK_LOW_AND_ABOVE = "block_low_and_above", - // (undocumented) BLOCK_MEDIUM_AND_ABOVE = "block_medium_and_above", - // (undocumented) BLOCK_NONE = "block_none", - // (undocumented) BLOCK_ONLY_HIGH = "block_only_high" } -// @public (undocumented) +// @beta export interface ImagenSafetySettings { - // (undocumented) personFilterLevel?: ImagenPersonFilterLevel; - // (undocumented) safetyFilterLevel?: ImagenSafetyFilterLevel; } @@ -838,13 +803,12 @@ export const enum VertexAIErrorCode { RESPONSE_ERROR = "response-error" } -// @public (undocumented) +// @public export abstract class VertexAIModel { // @internal protected constructor(vertexAI: VertexAI, modelName: string); // @internal (undocumented) protected _apiSettings: ApiSettings; - // (undocumented) readonly model: string; static normalizeModelName(modelName: string): string; } diff --git a/docs-devsite/vertexai.imagengcsimage.md b/docs-devsite/vertexai.imagengcsimage.md index af4717129f7..b094e63c1d8 100644 --- a/docs-devsite/vertexai.imagengcsimage.md +++ b/docs-devsite/vertexai.imagengcsimage.md @@ -10,6 +10,10 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenGCSImage interface +An image generated by Imagen, stored in a Cloud Storage for Firebase bucket. + +This feature is not available yet. + Signature: ```typescript @@ -20,19 +24,29 @@ export interface ImagenGCSImage | Property | Type | Description | | --- | --- | --- | -| [gcsURI](./vertexai.imagengcsimage.md#imagengcsimagegcsuri) | string | | -| [mimeType](./vertexai.imagengcsimage.md#imagengcsimagemimetype) | string | | +| [gcsURI](./vertexai.imagengcsimage.md#imagengcsimagegcsuri) | string | The URI of the file stored in a Cloud Storage for Firebase bucket. | +| [mimeType](./vertexai.imagengcsimage.md#imagengcsimagemimetype) | string | The MIME type of the image; either "image/png" or "image/jpeg".To request a different format, set the imageFormat property in your [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface). | ## ImagenGCSImage.gcsURI +The URI of the file stored in a Cloud Storage for Firebase bucket. + Signature: ```typescript gcsURI: string; ``` +### Example + +`"gs://bucket-name/path/sample_0.jpg"`. + ## ImagenGCSImage.mimeType +The MIME type of the image; either `"image/png"` or `"image/jpeg"`. + +To request a different format, set the `imageFormat` property in your [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface). + Signature: ```typescript diff --git a/docs-devsite/vertexai.imagengenerationconfig.md b/docs-devsite/vertexai.imagengenerationconfig.md index 4b2e91f01a7..cee7734f789 100644 --- a/docs-devsite/vertexai.imagengenerationconfig.md +++ b/docs-devsite/vertexai.imagengenerationconfig.md @@ -10,6 +10,13 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenGenerationConfig interface +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Configuration options for generating images with Imagen. + +See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images-imagen) for more details. + Signature: ```typescript @@ -20,14 +27,23 @@ export interface ImagenGenerationConfig | Property | Type | Description | | --- | --- | --- | -| [addWatermark](./vertexai.imagengenerationconfig.md#imagengenerationconfigaddwatermark) | boolean | | -| [aspectRatio](./vertexai.imagengenerationconfig.md#imagengenerationconfigaspectratio) | [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | | -| [imageFormat](./vertexai.imagengenerationconfig.md#imagengenerationconfigimageformat) | [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) | | -| [negativePrompt](./vertexai.imagengenerationconfig.md#imagengenerationconfignegativeprompt) | string | | -| [numberOfImages](./vertexai.imagengenerationconfig.md#imagengenerationconfignumberofimages) | number | | +| [addWatermark](./vertexai.imagengenerationconfig.md#imagengenerationconfigaddwatermark) | boolean | (Public Preview) Whether to add an invisible watermark to generated images.If set to true, an invisible SynthID watermark is embedded in generated images to indicate that they are AI generated. If set to false, watermarking will be disabled.For Imagen 3 models, the default value is true; see the addWatermark documentation for more details. | +| [aspectRatio](./vertexai.imagengenerationconfig.md#imagengenerationconfigaspectratio) | [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | (Public Preview) The aspect ratio of the generated images. The default value is square 1:1. Supported aspect ratios depend on the Imagen model, see [ImagenAspectRatio](./vertexai.md#imagenaspectratio) for more details. | +| [imageFormat](./vertexai.imagengenerationconfig.md#imagengenerationconfigimageformat) | [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) | (Public Preview) The image format of the generated images. The default is PNG.See [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) for more details. | +| [negativePrompt](./vertexai.imagengenerationconfig.md#imagengenerationconfignegativeprompt) | string | (Public Preview) A description of what should be omitted from the generated images.Support for negative prompts depends on the Imagen model.See the [documentation](http://firebase.google.com/docs/vertex-ai/model-parameters#imagen) for more details. | +| [numberOfImages](./vertexai.imagengenerationconfig.md#imagengenerationconfignumberofimages) | number | (Public Preview) The number of images to generate. The default value is 1.The number of sample images that may be generated in each request depends on the model (typically up to 4); see the sampleCount documentation for more details. | ## ImagenGenerationConfig.addWatermark +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Whether to add an invisible watermark to generated images. + +If set to `true`, an invisible SynthID watermark is embedded in generated images to indicate that they are AI generated. If set to `false`, watermarking will be disabled. + +For Imagen 3 models, the default value is `true`; see the addWatermark documentation for more details. + Signature: ```typescript @@ -36,6 +52,11 @@ addWatermark?: boolean; ## ImagenGenerationConfig.aspectRatio +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The aspect ratio of the generated images. The default value is square 1:1. Supported aspect ratios depend on the Imagen model, see [ImagenAspectRatio](./vertexai.md#imagenaspectratio) for more details. + Signature: ```typescript @@ -44,6 +65,13 @@ aspectRatio?: ImagenAspectRatio; ## ImagenGenerationConfig.imageFormat +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The image format of the generated images. The default is PNG. + +See [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) for more details. + Signature: ```typescript @@ -52,6 +80,15 @@ imageFormat?: ImagenImageFormat; ## ImagenGenerationConfig.negativePrompt +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +A description of what should be omitted from the generated images. + +Support for negative prompts depends on the Imagen model. + +See the [documentation](http://firebase.google.com/docs/vertex-ai/model-parameters#imagen) for more details. + Signature: ```typescript @@ -60,6 +97,13 @@ negativePrompt?: string; ## ImagenGenerationConfig.numberOfImages +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The number of images to generate. The default value is 1. + +The number of sample images that may be generated in each request depends on the model (typically up to 4); see the sampleCount documentation for more details. + Signature: ```typescript diff --git a/docs-devsite/vertexai.imagengenerationresponse.md b/docs-devsite/vertexai.imagengenerationresponse.md index 320e2b68533..32ed69718f9 100644 --- a/docs-devsite/vertexai.imagengenerationresponse.md +++ b/docs-devsite/vertexai.imagengenerationresponse.md @@ -10,6 +10,11 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenGenerationResponse interface +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The response from a request to generate images with Imagen. + Signature: ```typescript @@ -20,11 +25,20 @@ export interface ImagenGenerationResponse(Public Preview) The reason that images were filtered out. This property will only be defined if one or more images were filtered.Images may be filtered out due to the [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel), [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel), or filtering included in the model. The filter levels may be adjusted in your [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface).See the [Responsible AI and usage guidelines for Imagen](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen) for more details. | +| [images](./vertexai.imagengenerationresponse.md#imagengenerationresponseimages) | T\[\] | (Public Preview) The images generated by Imagen.The number of images generated may be fewer than the number requested if one or more were filtered out; see filteredReason. | ## ImagenGenerationResponse.filteredReason +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The reason that images were filtered out. This property will only be defined if one or more images were filtered. + +Images may be filtered out due to the [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel), [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel), or filtering included in the model. The filter levels may be adjusted in your [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface). + +See the [Responsible AI and usage guidelines for Imagen](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen) for more details. + Signature: ```typescript @@ -33,6 +47,13 @@ filteredReason?: string; ## ImagenGenerationResponse.images +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The images generated by Imagen. + +The number of images generated may be fewer than the number requested if one or more were filtered out; see `filteredReason`. + Signature: ```typescript diff --git a/docs-devsite/vertexai.imagenimageformat.md b/docs-devsite/vertexai.imagenimageformat.md index f52af54d9f4..785c7c726fc 100644 --- a/docs-devsite/vertexai.imagenimageformat.md +++ b/docs-devsite/vertexai.imagenimageformat.md @@ -10,13 +10,12 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenImageFormat class - Copyright 2025 Google LLC +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at +Defines the image format for images generated by Imagen. -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +Use this class to specify the desired format (JPEG or PNG) and compression quality for images generated by Imagen. This is typically included as part of [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface). Signature: @@ -28,18 +27,23 @@ export declare class ImagenImageFormat | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [compressionQuality](./vertexai.imagenimageformat.md#imagenimageformatcompressionquality) | | number | | -| [mimeType](./vertexai.imagenimageformat.md#imagenimageformatmimetype) | | string | | +| [compressionQuality](./vertexai.imagenimageformat.md#imagenimageformatcompressionquality) | | number | (Public Preview) The level of compression (a number between 0 and 100). | +| [mimeType](./vertexai.imagenimageformat.md#imagenimageformatmimetype) | | string | (Public Preview) The MIME type. | ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [jpeg(compressionQuality)](./vertexai.imagenimageformat.md#imagenimageformatjpeg) | static | | -| [png()](./vertexai.imagenimageformat.md#imagenimageformatpng) | static | | +| [jpeg(compressionQuality)](./vertexai.imagenimageformat.md#imagenimageformatjpeg) | static | (Public Preview) Creates an [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) for a JPEG image. | +| [png()](./vertexai.imagenimageformat.md#imagenimageformatpng) | static | (Public Preview) Creates an [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) for a PNG image. | ## ImagenImageFormat.compressionQuality +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The level of compression (a number between 0 and 100). + Signature: ```typescript @@ -48,6 +52,11 @@ compressionQuality?: number; ## ImagenImageFormat.mimeType +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The MIME type. + Signature: ```typescript @@ -56,6 +65,11 @@ mimeType: string; ## ImagenImageFormat.jpeg() +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Creates an [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) for a JPEG image. + Signature: ```typescript @@ -66,14 +80,21 @@ static jpeg(compressionQuality?: number): ImagenImageFormat; | Parameter | Type | Description | | --- | --- | --- | -| compressionQuality | number | | +| compressionQuality | number | The level of compression (a number between 0 and 100). | Returns: [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) +An [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) object for a JPEG image. + ## ImagenImageFormat.png() +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Creates an [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) for a PNG image. + Signature: ```typescript @@ -83,3 +104,16 @@ static png(): ImagenImageFormat; [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) +An [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) object for a PNG image. + +### Example + + +```javascript +const imagenModelParams = { + // ... other ImagenModelParams + imageFormat: ImagenImageFormat.jpeg(75) // JPEG with a compression level of 75. +} + +``` + diff --git a/docs-devsite/vertexai.imageninlineimage.md b/docs-devsite/vertexai.imageninlineimage.md index b1b2fb3e52c..19fe8a67764 100644 --- a/docs-devsite/vertexai.imageninlineimage.md +++ b/docs-devsite/vertexai.imageninlineimage.md @@ -10,13 +10,10 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenInlineImage interface - Copyright 2025 Google LLC +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +An image generated by Imagen, represented as inline data. Signature: @@ -28,11 +25,16 @@ export interface ImagenInlineImage | Property | Type | Description | | --- | --- | --- | -| [bytesBase64Encoded](./vertexai.imageninlineimage.md#imageninlineimagebytesbase64encoded) | string | | -| [mimeType](./vertexai.imageninlineimage.md#imageninlineimagemimetype) | string | | +| [bytesBase64Encoded](./vertexai.imageninlineimage.md#imageninlineimagebytesbase64encoded) | string | (Public Preview) The base64-encoded image data. | +| [mimeType](./vertexai.imageninlineimage.md#imageninlineimagemimetype) | string | (Public Preview) The MIME type of the image; either "image/png" or "image/jpeg".To request a different format, set the imageFormat property in your [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface). | ## ImagenInlineImage.bytesBase64Encoded +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The base64-encoded image data. + Signature: ```typescript @@ -41,6 +43,13 @@ bytesBase64Encoded: string; ## ImagenInlineImage.mimeType +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The MIME type of the image; either `"image/png"` or `"image/jpeg"`. + +To request a different format, set the `imageFormat` property in your [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface). + Signature: ```typescript diff --git a/docs-devsite/vertexai.imagenmodel.md b/docs-devsite/vertexai.imagenmodel.md index c2730170180..63e15ff133a 100644 --- a/docs-devsite/vertexai.imagenmodel.md +++ b/docs-devsite/vertexai.imagenmodel.md @@ -10,6 +10,13 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenModel class +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Class for Imagen model APIs. + +This class provides methods for generating images using the Imagen model. + Signature: ```typescript @@ -21,26 +28,28 @@ export declare class ImagenModel extends VertexAIModel | Constructor | Modifiers | Description | | --- | --- | --- | -| [(constructor)(vertexAI, modelParams, requestOptions)](./vertexai.imagenmodel.md#imagenmodelconstructor) | | Constructs a new instance of the ImagenModel class | +| [(constructor)(vertexAI, modelParams, requestOptions)](./vertexai.imagenmodel.md#imagenmodelconstructor) | | (Public Preview) Constructs a new instance of the [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class) class. | ## Properties | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [generationConfig](./vertexai.imagenmodel.md#imagenmodelgenerationconfig) | | [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface) | | -| [requestOptions](./vertexai.imagenmodel.md#imagenmodelrequestoptions) | | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) \| undefined | | -| [safetySettings](./vertexai.imagenmodel.md#imagenmodelsafetysettings) | | [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface) | | +| [generationConfig](./vertexai.imagenmodel.md#imagenmodelgenerationconfig) | | [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface) | (Public Preview) The Imagen generation configuration. | +| [requestOptions](./vertexai.imagenmodel.md#imagenmodelrequestoptions) | | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) \| undefined | (Public Preview) | +| [safetySettings](./vertexai.imagenmodel.md#imagenmodelsafetysettings) | | [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface) | (Public Preview) Safety settings for filtering inappropriate content. | ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [generateImages(prompt)](./vertexai.imagenmodel.md#imagenmodelgenerateimages) | | | -| [generateImagesGCS(prompt, gcsURI)](./vertexai.imagenmodel.md#imagenmodelgenerateimagesgcs) | | | +| [generateImages(prompt)](./vertexai.imagenmodel.md#imagenmodelgenerateimages) | | (Public Preview) Generates images using the Imagen model and returns them as base64-encoded strings. | ## ImagenModel.(constructor) -Constructs a new instance of the `ImagenModel` class +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Constructs a new instance of the [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class) class. Signature: @@ -52,12 +61,21 @@ constructor(vertexAI: VertexAI, modelParams: ImagenModelParams, requestOptions?: | Parameter | Type | Description | | --- | --- | --- | -| vertexAI | [VertexAI](./vertexai.vertexai.md#vertexai_interface) | | -| modelParams | [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface) | | -| requestOptions | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) \| undefined | | +| vertexAI | [VertexAI](./vertexai.vertexai.md#vertexai_interface) | An instance of the Vertex AI in Firebase SDK. | +| modelParams | [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface) | Parameters to use when making requests to Imagen. | +| requestOptions | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) \| undefined | Additional options to use when making requests. | + +#### Exceptions + +If the `apiKey` or `projectId` fields are missing in your Firebase config. ## ImagenModel.generationConfig +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The Imagen generation configuration. + Signature: ```typescript @@ -66,6 +84,9 @@ generationConfig?: ImagenGenerationConfig; ## ImagenModel.requestOptions +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + Signature: ```typescript @@ -74,6 +95,11 @@ requestOptions?: RequestOptions | undefined; ## ImagenModel.safetySettings +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Safety settings for filtering inappropriate content. + Signature: ```typescript @@ -82,6 +108,13 @@ safetySettings?: ImagenSafetySettings; ## ImagenModel.generateImages() +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Generates images using the Imagen model and returns them as base64-encoded strings. + +If the prompt was not blocked, but one or more of the generated images were filtered, the returned object will have a `filteredReason` property. If all images are filtered, the `images` array will be empty. + Signature: ```typescript @@ -92,28 +125,33 @@ generateImages(prompt: string): PromiseReturns: Promise<[ImagenGenerationResponse](./vertexai.imagengenerationresponse.md#imagengenerationresponse_interface)<[ImagenInlineImage](./vertexai.imageninlineimage.md#imageninlineimage_interface)>> -## ImagenModel.generateImagesGCS() +A promise that resolves to an [ImagenGenerationResponse](./vertexai.imagengenerationresponse.md#imagengenerationresponse_interface) object containing the generated images. -Signature: +#### Exceptions -```typescript -generateImagesGCS(prompt: string, gcsURI: string): Promise>; -``` +If the request to generate images fails. This happens if the prompt is blocked. -#### Parameters +### Example -| Parameter | Type | Description | -| --- | --- | --- | -| prompt | string | | -| gcsURI | string | | -Returns: +```javascript +const imagen = new ImagenModel( + vertexAI, + { + model: 'imagen-3.0-generate-002' + } +); -Promise<[ImagenGenerationResponse](./vertexai.imagengenerationresponse.md#imagengenerationresponse_interface)<[ImagenGCSImage](./vertexai.imagengcsimage.md#imagengcsimage_interface)>> +const response = await imagen.generateImages('A photo of a cat'); +if (response.images.length > 0) { + console.log(response.images[0].bytesBase64Encoded); +} + +``` diff --git a/docs-devsite/vertexai.imagenmodelparams.md b/docs-devsite/vertexai.imagenmodelparams.md index 21dbd533006..66c4bb0bfe6 100644 --- a/docs-devsite/vertexai.imagenmodelparams.md +++ b/docs-devsite/vertexai.imagenmodelparams.md @@ -10,6 +10,11 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenModelParams interface +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Parameters for configuring an [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class). + Signature: ```typescript @@ -20,12 +25,17 @@ export interface ImagenModelParams | Property | Type | Description | | --- | --- | --- | -| [generationConfig](./vertexai.imagenmodelparams.md#imagenmodelparamsgenerationconfig) | [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface) | | -| [model](./vertexai.imagenmodelparams.md#imagenmodelparamsmodel) | string | | -| [safetySettings](./vertexai.imagenmodelparams.md#imagenmodelparamssafetysettings) | [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface) | | +| [generationConfig](./vertexai.imagenmodelparams.md#imagenmodelparamsgenerationconfig) | [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface) | (Public Preview) Configuration options for generating images with Imagen. | +| [model](./vertexai.imagenmodelparams.md#imagenmodelparamsmodel) | string | (Public Preview) The Imagen model to use for generating images. For example: imagen-3.0-generate-002.Only Imagen 3 models (named imagen-3.0-*) are supported.See [model versions](https://firebase.google.com/docs/vertex-ai/models) for a full list of supported Imagen 3 models. | +| [safetySettings](./vertexai.imagenmodelparams.md#imagenmodelparamssafetysettings) | [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface) | (Public Preview) Safety settings for filtering potentially inappropriate content. | ## ImagenModelParams.generationConfig +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Configuration options for generating images with Imagen. + Signature: ```typescript @@ -34,6 +44,15 @@ generationConfig?: ImagenGenerationConfig; ## ImagenModelParams.model +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +The Imagen model to use for generating images. For example: `imagen-3.0-generate-002`. + +Only Imagen 3 models (named `imagen-3.0-*`) are supported. + +See [model versions](https://firebase.google.com/docs/vertex-ai/models) for a full list of supported Imagen 3 models. + Signature: ```typescript @@ -42,6 +61,11 @@ model: string; ## ImagenModelParams.safetySettings +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Safety settings for filtering potentially inappropriate content. + Signature: ```typescript diff --git a/docs-devsite/vertexai.imagensafetysettings.md b/docs-devsite/vertexai.imagensafetysettings.md index 0f5ea97c3e4..3cf7931a959 100644 --- a/docs-devsite/vertexai.imagensafetysettings.md +++ b/docs-devsite/vertexai.imagensafetysettings.md @@ -10,6 +10,13 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # ImagenSafetySettings interface +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Settings for controlling the aggressiveness of filtering out sensitive content. + +See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details. + Signature: ```typescript @@ -20,11 +27,16 @@ export interface ImagenSafetySettings | Property | Type | Description | | --- | --- | --- | -| [personFilterLevel](./vertexai.imagensafetysettings.md#imagensafetysettingspersonfilterlevel) | [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel) | | -| [safetyFilterLevel](./vertexai.imagensafetysettings.md#imagensafetysettingssafetyfilterlevel) | [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel) | | +| [personFilterLevel](./vertexai.imagensafetysettings.md#imagensafetysettingspersonfilterlevel) | [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel) | (Public Preview) A filter level controlling whether generation of images containing people or faces is allowed. | +| [safetyFilterLevel](./vertexai.imagensafetysettings.md#imagensafetysettingssafetyfilterlevel) | [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel) | (Public Preview) A filter level controlling how aggressive to filter out sensitive content from generated images. | ## ImagenSafetySettings.personFilterLevel +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +A filter level controlling whether generation of images containing people or faces is allowed. + Signature: ```typescript @@ -33,6 +45,11 @@ personFilterLevel?: ImagenPersonFilterLevel; ## ImagenSafetySettings.safetyFilterLevel +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +A filter level controlling how aggressive to filter out sensitive content from generated images. + Signature: ```typescript diff --git a/docs-devsite/vertexai.md b/docs-devsite/vertexai.md index efc0cb92402..1d284345c39 100644 --- a/docs-devsite/vertexai.md +++ b/docs-devsite/vertexai.md @@ -20,7 +20,7 @@ The Vertex AI in Firebase Web SDK. | [getVertexAI(app, options)](./vertexai.md#getvertexai_04094cf) | Returns a [VertexAI](./vertexai.vertexai.md#vertexai_interface) instance for the given app. | | function(vertexAI, ...) | | [getGenerativeModel(vertexAI, modelParams, requestOptions)](./vertexai.md#getgenerativemodel_e3037c9) | Returns a [GenerativeModel](./vertexai.generativemodel.md#generativemodel_class) class with methods for inference and other functionality. | -| [getImagenModel(vertexAI, modelParams, requestOptions)](./vertexai.md#getimagenmodel_812c375) | | +| [getImagenModel(vertexAI, modelParams, requestOptions)](./vertexai.md#getimagenmodel_812c375) | (Public Preview) Returns an [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class) class with methods for using Imagen.Only Imagen 3 models (named imagen-3.0-*) are supported. | ## Classes @@ -30,15 +30,15 @@ The Vertex AI in Firebase Web SDK. | [BooleanSchema](./vertexai.booleanschema.md#booleanschema_class) | Schema class for "boolean" types. | | [ChatSession](./vertexai.chatsession.md#chatsession_class) | ChatSession class that enables sending chat messages and stores history of sent and received messages so far. | | [GenerativeModel](./vertexai.generativemodel.md#generativemodel_class) | Class for generative model APIs. | -| [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) | Copyright 2025 Google LLCLicensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | -| [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class) | | +| [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) | (Public Preview) Defines the image format for images generated by Imagen.Use this class to specify the desired format (JPEG or PNG) and compression quality for images generated by Imagen. This is typically included as part of [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface). | +| [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class) | (Public Preview) Class for Imagen model APIs.This class provides methods for generating images using the Imagen model. | | [IntegerSchema](./vertexai.integerschema.md#integerschema_class) | Schema class for "integer" types. | | [NumberSchema](./vertexai.numberschema.md#numberschema_class) | Schema class for "number" types. | | [ObjectSchema](./vertexai.objectschema.md#objectschema_class) | Schema class for "object" types. The properties param must be a map of Schema objects. | | [Schema](./vertexai.schema.md#schema_class) | Parent class encompassing all Schema types, with static methods that allow building specific Schema types. This class can be converted with JSON.stringify() into a JSON string accepted by Vertex AI REST endpoints. (This string conversion is automatically done when calling SDK methods.) | | [StringSchema](./vertexai.stringschema.md#stringschema_class) | Schema class for "string" types. Can be used with or without enum values. | | [VertexAIError](./vertexai.vertexaierror.md#vertexaierror_class) | Error class for the Vertex AI in Firebase SDK. | -| [VertexAIModel](./vertexai.vertexaimodel.md#vertexaimodel_class) | | +| [VertexAIModel](./vertexai.vertexaimodel.md#vertexaimodel_class) | Base class for Vertex AI in Firebase model APIs. | ## Enumerations @@ -52,9 +52,9 @@ The Vertex AI in Firebase Web SDK. | [HarmCategory](./vertexai.md#harmcategory) | Harm categories that would cause prompts or candidates to be blocked. | | [HarmProbability](./vertexai.md#harmprobability) | Probability that a prompt or candidate matches a harm category. | | [HarmSeverity](./vertexai.md#harmseverity) | Harm severity levels. | -| [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | | -| [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel) | | -| [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel) | | +| [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | (Public Preview) Aspect ratios for Imagen images.To specify an aspect ratio for generated images, set the aspectRatio property in your [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface).See the the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. | +| [ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel) | (Public Preview) A filter level controlling whether generation of images containing people or faces is allowed.See the personGeneration documentation for more details. | +| [ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel) | (Public Preview) A filter level controlling how aggressively to filter sensitive content.Text prompts provided as inputs and images (generated or uploaded) through Imagen on Vertex AI are assessed against a list of safety filters, which include 'harmful categories' (for example, violence, sexual, derogatory, and toxic). This filter level controls how aggressively to filter out potentially harmful content from responses. See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) and the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters) for more details. | | [SchemaType](./vertexai.md#schematype) | Contains the list of OpenAPI data types as defined by the [OpenAPI specification](https://swagger.io/docs/specification/data-models/data-types/) | | [VertexAIErrorCode](./vertexai.md#vertexaierrorcode) | Standardized error codes that [VertexAIError](./vertexai.vertexaierror.md#vertexaierror_class) can have. | @@ -90,12 +90,12 @@ The Vertex AI in Firebase Web SDK. | [GenerativeContentBlob](./vertexai.generativecontentblob.md#generativecontentblob_interface) | Interface for sending an image. | | [GroundingAttribution](./vertexai.groundingattribution.md#groundingattribution_interface) | | | [GroundingMetadata](./vertexai.groundingmetadata.md#groundingmetadata_interface) | Metadata returned to client when grounding is enabled. | -| [ImagenGCSImage](./vertexai.imagengcsimage.md#imagengcsimage_interface) | | -| [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface) | | -| [ImagenGenerationResponse](./vertexai.imagengenerationresponse.md#imagengenerationresponse_interface) | | -| [ImagenInlineImage](./vertexai.imageninlineimage.md#imageninlineimage_interface) | Copyright 2025 Google LLCLicensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. | -| [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface) | | -| [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface) | | +| [ImagenGCSImage](./vertexai.imagengcsimage.md#imagengcsimage_interface) | An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.This feature is not available yet. | +| [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface) | (Public Preview) Configuration options for generating images with Imagen.See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images-imagen) for more details. | +| [ImagenGenerationResponse](./vertexai.imagengenerationresponse.md#imagengenerationresponse_interface) | (Public Preview) The response from a request to generate images with Imagen. | +| [ImagenInlineImage](./vertexai.imageninlineimage.md#imageninlineimage_interface) | (Public Preview) An image generated by Imagen, represented as inline data. | +| [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface) | (Public Preview) Parameters for configuring an [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class). | +| [ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface) | (Public Preview) Settings for controlling the aggressiveness of filtering out sensitive content.See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details. | | [InlineDataPart](./vertexai.inlinedatapart.md#inlinedatapart_interface) | Content part interface if the part represents an image. | | [ModelParams](./vertexai.modelparams.md#modelparams_interface) | Params passed to [getGenerativeModel()](./vertexai.md#getgenerativemodel_e3037c9). | | [ObjectSchemaInterface](./vertexai.objectschemainterface.md#objectschemainterface_interface) | Interface for [ObjectSchema](./vertexai.objectschema.md#objectschema_class) class. | @@ -182,6 +182,13 @@ export declare function getGenerativeModel(vertexAI: VertexAI, modelParams: Mode ### getImagenModel(vertexAI, modelParams, requestOptions) {:#getimagenmodel_812c375} +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Returns an [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class) class with methods for using Imagen. + +Only Imagen 3 models (named `imagen-3.0-*`) are supported. + Signature: ```typescript @@ -192,14 +199,18 @@ export declare function getImagenModel(vertexAI: VertexAI, modelParams: ImagenMo | Parameter | Type | Description | | --- | --- | --- | -| vertexAI | [VertexAI](./vertexai.vertexai.md#vertexai_interface) | | -| modelParams | [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface) | | -| requestOptions | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) | | +| vertexAI | [VertexAI](./vertexai.vertexai.md#vertexai_interface) | An instance of the Vertex AI in Firebase SDK. | +| modelParams | [ImagenModelParams](./vertexai.imagenmodelparams.md#imagenmodelparams_interface) | Parameters to use when making Imagen requests. | +| requestOptions | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) | Additional options to use when making requests. | Returns: [ImagenModel](./vertexai.imagenmodel.md#imagenmodel_class) +#### Exceptions + +If the `apiKey` or `projectId` fields are missing in your Firebase config. + ## POSSIBLE\_ROLES Possible roles. @@ -398,6 +409,15 @@ export declare enum HarmSeverity ## ImagenAspectRatio +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +Aspect ratios for Imagen images. + +To specify an aspect ratio for generated images, set the `aspectRatio` property in your [ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface). + +See the the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) for more details and examples of the supported aspect ratios. + Signature: ```typescript @@ -408,14 +428,21 @@ export declare enum ImagenAspectRatio | Member | Value | Description | | --- | --- | --- | -| LANDSCAPE\_16x9 | "16:9" | | -| LANDSCAPE\_3x4 | "3:4" | | -| PORTRAIT\_4x3 | "4:3" | | -| PORTRAIT\_9x16 | "9:16" | | -| SQUARE | "1:1" | | +| LANDSCAPE\_16x9 | "16:9" | (Public Preview) Landscape (16:9) aspect ratio. | +| LANDSCAPE\_3x4 | "3:4" | (Public Preview) Landscape (3:4) aspect ratio. | +| PORTRAIT\_4x3 | "4:3" | (Public Preview) Portrait (4:3) aspect ratio. | +| PORTRAIT\_9x16 | "9:16" | (Public Preview) Portrait (9:16) aspect ratio. | +| SQUARE | "1:1" | (Public Preview) Square (1:1) aspect ratio. | ## ImagenPersonFilterLevel +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +A filter level controlling whether generation of images containing people or faces is allowed. + +See the personGeneration documentation for more details. + Signature: ```typescript @@ -426,12 +453,19 @@ export declare enum ImagenPersonFilterLevel | Member | Value | Description | | --- | --- | --- | -| ALLOW\_ADULT | "allow_adult" | | -| ALLOW\_ALL | "allow_all" | | -| BLOCK\_ALL | "dont_allow" | | +| ALLOW\_ADULT | "allow_adult" | (Public Preview) Allow generation of images containing adults only; images of children are filtered out.Generation of images containing people or faces may require your use case to be reviewed and approved by Cloud support; see the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen) for more details. | +| ALLOW\_ALL | "allow_all" | (Public Preview) Allow generation of images containing adults only; images of children are filtered out.Generation of images containing people or faces may require your use case to be reviewed and approved by Cloud support; see the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen) for more details. | +| BLOCK\_ALL | "dont_allow" | (Public Preview) Disallow generation of images containing people or faces; images of people are filtered out. | ## ImagenSafetyFilterLevel +> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. +> + +A filter level controlling how aggressively to filter sensitive content. + +Text prompts provided as inputs and images (generated or uploaded) through Imagen on Vertex AI are assessed against a list of safety filters, which include 'harmful categories' (for example, `violence`, `sexual`, `derogatory`, and `toxic`). This filter level controls how aggressively to filter out potentially harmful content from responses. See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images) and the [Responsible AI and usage guidelines](https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters) for more details. + Signature: ```typescript @@ -442,10 +476,10 @@ export declare enum ImagenSafetyFilterLevel | Member | Value | Description | | --- | --- | --- | -| BLOCK\_LOW\_AND\_ABOVE | "block_low_and_above" | | -| BLOCK\_MEDIUM\_AND\_ABOVE | "block_medium_and_above" | | -| BLOCK\_NONE | "block_none" | | -| BLOCK\_ONLY\_HIGH | "block_only_high" | | +| BLOCK\_LOW\_AND\_ABOVE | "block_low_and_above" | (Public Preview) The most aggressive filtering level; most strict blocking. | +| BLOCK\_MEDIUM\_AND\_ABOVE | "block_medium_and_above" | (Public Preview) Blocks some sensitive prompts and responses. | +| BLOCK\_NONE | "block_none" | (Public Preview) The least aggressive filtering level; blocks very few sensitive prompts and responses.Access to this feature is restricted and may require your case to be reviewed and approved by Cloud support. | +| BLOCK\_ONLY\_HIGH | "block_only_high" | (Public Preview) Blocks few sensitive prompts and responses. | ## SchemaType diff --git a/docs-devsite/vertexai.vertexaimodel.md b/docs-devsite/vertexai.vertexaimodel.md index 31d7e1d9c32..5c3244fe1e5 100644 --- a/docs-devsite/vertexai.vertexaimodel.md +++ b/docs-devsite/vertexai.vertexaimodel.md @@ -10,6 +10,8 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # VertexAIModel class +Base class for Vertex AI in Firebase model APIs. + The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `VertexAIModel` class. Signature: @@ -22,7 +24,7 @@ export declare abstract class VertexAIModel | Property | Modifiers | Type | Description | | --- | --- | --- | --- | -| [model](./vertexai.vertexaimodel.md#vertexaimodelmodel) | | string | | +| [model](./vertexai.vertexaimodel.md#vertexaimodelmodel) | | string | The fully qualified model resource name to use for generating images (for example, publishers/google/models/imagen-3.0-generate-002). | ## Methods @@ -32,6 +34,8 @@ export declare abstract class VertexAIModel ## VertexAIModel.model +The fully qualified model resource name to use for generating images (for example, `publishers/google/models/imagen-3.0-generate-002`). + Signature: ```typescript diff --git a/packages/vertexai/src/api.ts b/packages/vertexai/src/api.ts index 8b7477f306d..752e75c7e23 100644 --- a/packages/vertexai/src/api.ts +++ b/packages/vertexai/src/api.ts @@ -82,6 +82,20 @@ export function getGenerativeModel( return new GenerativeModel(vertexAI, modelParams, requestOptions); } +/** + * Returns an {@link ImagenModel} class with methods for using Imagen. + * + * Only Imagen 3 models (named `imagen-3.0-*`) are supported. + * + * @param vertexAI - An instance of the Vertex AI in Firebase SDK. + * @param modelParams - Parameters to use when making Imagen requests. + * @param requestOptions - Additional options to use when making requests. + * + * @throws If the `apiKey` or `projectId` fields are missing in your + * Firebase config. + * + * @beta + */ export function getImagenModel( vertexAI: VertexAI, modelParams: ImagenModelParams, diff --git a/packages/vertexai/src/models/imagen-model.ts b/packages/vertexai/src/models/imagen-model.ts index 8d9ab93b6ba..89c740852a3 100644 --- a/packages/vertexai/src/models/imagen-model.ts +++ b/packages/vertexai/src/models/imagen-model.ts @@ -30,10 +30,48 @@ import { } from '../types'; import { VertexAIModel } from './vertexai-model'; +/** + * Class for Imagen model APIs. + * + * This class provides methods for generating images using the Imagen model. + * + * @example + * ```javascript + * const imagen = new ImagenModel( + * vertexAI, + * { + * model: 'imagen-3.0-generate-002' + * } + * ); + * + * const response = await imagen.generateImages('A photo of a cat'); + * if (response.images.length > 0) { + * console.log(response.images[0].bytesBase64Encoded); + * } + * ``` + * + * @beta + */ export class ImagenModel extends VertexAIModel { + /** + * The Imagen generation configuration. + */ generationConfig?: ImagenGenerationConfig; + /** + * Safety settings for filtering inappropriate content. + */ safetySettings?: ImagenSafetySettings; + /** + * Constructs a new instance of the {@link ImagenModel} class. + * + * @param vertexAI - An instance of the Vertex AI in Firebase SDK. + * @param modelParams - Parameters to use when making requests to Imagen. + * @param requestOptions - Additional options to use when making requests. + * + * @throws If the `apiKey` or `projectId` fields are missing in your + * Firebase config. + */ constructor( vertexAI: VertexAI, modelParams: ImagenModelParams, @@ -45,6 +83,24 @@ export class ImagenModel extends VertexAIModel { this.safetySettings = safetySettings; } + /** + * Generates images using the Imagen model and returns them as + * base64-encoded strings. + * + * @param prompt - A text prompt describing the image(s) to generate. + * @returns A promise that resolves to an {@link ImagenGenerationResponse} + * object containing the generated images. + * + * @throws If the request to generate images fails. This happens if the + * prompt is blocked. + * + * @remarks + * If the prompt was not blocked, but one or more of the generated images were filtered, the + * returned object will have a `filteredReason` property. + * If all images are filtered, the `images` array will be empty. + * + * @beta + */ async generateImages( prompt: string ): Promise> { @@ -63,6 +119,25 @@ export class ImagenModel extends VertexAIModel { return handlePredictResponse(response); } + /** + * Generates images to Cloud Storage for Firebase using the Imagen model. + * + * @internal This method is temporarily internal. + * + * @param prompt - A text prompt describing the image(s) to generate. + * @param gcsURI - The URI of file stored in a Cloud Storage for Firebase bucket. + * This should be a directory. For example, `gs://my-bucket/my-directory/`. + * @returns A promise that resolves to an {@link ImagenGenerationResponse} + * object containing the URLs of the generated images. + * + * @throws If the request fails to generate images fails. This happens if + * the prompt is blocked. + * + * @remarks + * If the prompt was not blocked, but one or more of the generated images were filtered, the + * returned object will have a `filteredReason` property. + * If all images are filtered, the `images` array will be empty. + */ async generateImagesGCS( prompt: string, gcsURI: string diff --git a/packages/vertexai/src/models/vertexai-model.ts b/packages/vertexai/src/models/vertexai-model.ts index 5bed60d6279..4e211c0cf94 100644 --- a/packages/vertexai/src/models/vertexai-model.ts +++ b/packages/vertexai/src/models/vertexai-model.ts @@ -21,7 +21,16 @@ import { VertexAIService } from '../service'; import { ApiSettings } from '../types/internal'; import { _isFirebaseServerApp } from '@firebase/app'; +/** + * Base class for Vertex AI in Firebase model APIs. + * + * @public + */ export abstract class VertexAIModel { + /** + * The fully qualified model resource name to use for generating images + * (for example, `publishers/google/models/imagen-3.0-generate-002`). + */ readonly model: string; /** diff --git a/packages/vertexai/src/requests/imagen-image-format.ts b/packages/vertexai/src/requests/imagen-image-format.ts index e6dbab041a6..283dc80bfaf 100644 --- a/packages/vertexai/src/requests/imagen-image-format.ts +++ b/packages/vertexai/src/requests/imagen-image-format.ts @@ -17,14 +17,45 @@ import { logger } from '../logger'; +/** + * Defines the image format for images generated by Imagen. + * + * Use this class to specify the desired format (JPEG or PNG) and compression quality + * for images generated by Imagen. This is typically included as part of + * {@link ImagenModelParams}. + * + * @example + * ```javascript + * const imagenModelParams = { + * // ... other ImagenModelParams + * imageFormat: ImagenImageFormat.jpeg(75) // JPEG with a compression level of 75. + * } + * ``` + * + * @beta + */ export class ImagenImageFormat { + /** + * The MIME type. + */ mimeType: string; + /** + * The level of compression (a number between 0 and 100). + */ compressionQuality?: number; private constructor() { this.mimeType = 'image/png'; } + /** + * Creates an {@link ImagenImageFormat} for a JPEG image. + * + * @param compressionQuality - The level of compression (a number between 0 and 100). + * @returns An {@link ImagenImageFormat} object for a JPEG image. + * + * @beta + */ static jpeg(compressionQuality?: number): ImagenImageFormat { if ( compressionQuality && @@ -37,6 +68,13 @@ export class ImagenImageFormat { return { mimeType: 'image/jpeg', compressionQuality }; } + /** + * Creates an {@link ImagenImageFormat} for a PNG image. + * + * @returns An {@link ImagenImageFormat} object for a PNG image. + * + * @beta + */ static png(): ImagenImageFormat { return { mimeType: 'image/png' }; } diff --git a/packages/vertexai/src/requests/request-helpers.ts b/packages/vertexai/src/requests/request-helpers.ts index 33d2fab266a..b99c327c044 100644 --- a/packages/vertexai/src/requests/request-helpers.ts +++ b/packages/vertexai/src/requests/request-helpers.ts @@ -126,7 +126,7 @@ export function formatGenerateContentInput( } /** - * Convert the user-defined parameters in {@link ImagenGenerationParams} to the format + * Convert the user-defined parameters in {@link ImagenGenerationParams} to the format * that is expected from the REST API. * * @internal diff --git a/packages/vertexai/src/types/imagen/internal.ts b/packages/vertexai/src/types/imagen/internal.ts index fb81e634617..02a8a55e01c 100644 --- a/packages/vertexai/src/types/imagen/internal.ts +++ b/packages/vertexai/src/types/imagen/internal.ts @@ -121,7 +121,7 @@ export interface PredictRequestBody { */ export type ImagenGenerationParams = { /** - * The Google Cloud Storage (GCS) URI where the images should be stored + * The Cloud Storage for Firebase bucket URI where the images should be stored * (for GCS requests only). */ gcsURI?: string; diff --git a/packages/vertexai/src/types/imagen/requests.ts b/packages/vertexai/src/types/imagen/requests.ts index cf72391dc41..ac37488dfb5 100644 --- a/packages/vertexai/src/types/imagen/requests.ts +++ b/packages/vertexai/src/types/imagen/requests.ts @@ -17,42 +17,196 @@ import { ImagenImageFormat } from '../../requests/imagen-image-format'; +/** + * Parameters for configuring an {@link ImagenModel}. + * + * @beta + */ export interface ImagenModelParams { + /** + * The Imagen model to use for generating images. + * For example: `imagen-3.0-generate-002`. + * + * Only Imagen 3 models (named `imagen-3.0-*`) are supported. + * + * See {@link https://firebase.google.com/docs/vertex-ai/models | model versions} + * for a full list of supported Imagen 3 models. + */ model: string; + /** + * Configuration options for generating images with Imagen. + */ generationConfig?: ImagenGenerationConfig; + /** + * Safety settings for filtering potentially inappropriate content. + */ safetySettings?: ImagenSafetySettings; } +/** + * Configuration options for generating images with Imagen. + * + * See the {@link http://firebase.google.com/docs/vertex-ai/generate-images-imagen | documentation} for + * more details. + * + * @beta + */ export interface ImagenGenerationConfig { + /** + * A description of what should be omitted from the generated images. + * + * Support for negative prompts depends on the Imagen model. + * + * See the {@link http://firebase.google.com/docs/vertex-ai/model-parameters#imagen | documentation} for more details. + */ negativePrompt?: string; + /** + * The number of images to generate. The default value is 1. + * + * The number of sample images that may be generated in each request depends on the model + * (typically up to 4); see the sampleCount + * documentation for more details. + */ numberOfImages?: number; + /** + * The aspect ratio of the generated images. The default value is square 1:1. + * Supported aspect ratios depend on the Imagen model, see {@link ImagenAspectRatio} + * for more details. + */ aspectRatio?: ImagenAspectRatio; + /** + * The image format of the generated images. The default is PNG. + * + * See {@link ImagenImageFormat} for more details. + */ imageFormat?: ImagenImageFormat; + /** + * Whether to add an invisible watermark to generated images. + * + * If set to `true`, an invisible SynthID watermark is embedded in generated images to indicate + * that they are AI generated. If set to `false`, watermarking will be disabled. + * + * For Imagen 3 models, the default value is `true`; see the addWatermark + * documentation for more details. + */ addWatermark?: boolean; } +/** + * A filter level controlling how aggressively to filter sensitive content. + * + * Text prompts provided as inputs and images (generated or uploaded) through Imagen on Vertex AI + * are assessed against a list of safety filters, which include 'harmful categories' (for example, + * `violence`, `sexual`, `derogatory`, and `toxic`). This filter level controls how aggressively to + * filter out potentially harmful content from responses. See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } + * and the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#safety-filters | Responsible AI and usage guidelines} + * for more details. + * + * @beta + */ export enum ImagenSafetyFilterLevel { + /** + * The most aggressive filtering level; most strict blocking. + */ BLOCK_LOW_AND_ABOVE = 'block_low_and_above', + /** + * Blocks some sensitive prompts and responses. + */ BLOCK_MEDIUM_AND_ABOVE = 'block_medium_and_above', + /** + * Blocks few sensitive prompts and responses. + */ BLOCK_ONLY_HIGH = 'block_only_high', + /** + * The least aggressive filtering level; blocks very few sensitive prompts and responses. + * + * Access to this feature is restricted and may require your case to be reviewed and approved by + * Cloud support. + */ BLOCK_NONE = 'block_none' } +/** + * A filter level controlling whether generation of images containing people or faces is allowed. + * + * See the personGeneration + * documentation for more details. + * + * @beta + */ export enum ImagenPersonFilterLevel { + /** + * Disallow generation of images containing people or faces; images of people are filtered out. + */ BLOCK_ALL = 'dont_allow', + /** + * Allow generation of images containing adults only; images of children are filtered out. + * + * Generation of images containing people or faces may require your use case to be + * reviewed and approved by Cloud support; see the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen | Responsible AI and usage guidelines} + * for more details. + */ ALLOW_ADULT = 'allow_adult', + /** + * Allow generation of images containing adults only; images of children are filtered out. + * + * Generation of images containing people or faces may require your use case to be + * reviewed and approved by Cloud support; see the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen#person-face-gen | Responsible AI and usage guidelines} + * for more details. + */ ALLOW_ALL = 'allow_all' } +/** + * Settings for controlling the aggressiveness of filtering out sensitive content. + * + * See the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } + * for more details. + * + * @beta + */ export interface ImagenSafetySettings { + /** + * A filter level controlling how aggressive to filter out sensitive content from generated + * images. + */ safetyFilterLevel?: ImagenSafetyFilterLevel; + /** + * A filter level controlling whether generation of images containing people or faces is allowed. + */ personFilterLevel?: ImagenPersonFilterLevel; } +/** + * Aspect ratios for Imagen images. + * + * To specify an aspect ratio for generated images, set the `aspectRatio` property in your + * {@link ImagenGenerationConfig}. + * + * See the the {@link http://firebase.google.com/docs/vertex-ai/generate-images | documentation } + * for more details and examples of the supported aspect ratios. + * + * @beta + */ export enum ImagenAspectRatio { + /** + * Square (1:1) aspect ratio. + */ SQUARE = '1:1', + /** + * Landscape (3:4) aspect ratio. + */ LANDSCAPE_3x4 = '3:4', + /** + * Portrait (4:3) aspect ratio. + */ PORTRAIT_4x3 = '4:3', + /** + * Landscape (16:9) aspect ratio. + */ LANDSCAPE_16x9 = '16:9', + /** + * Portrait (9:16) aspect ratio. + */ PORTRAIT_9x16 = '9:16' } diff --git a/packages/vertexai/src/types/imagen/responses.ts b/packages/vertexai/src/types/imagen/responses.ts index 514acc601b1..c5cf5dd9057 100644 --- a/packages/vertexai/src/types/imagen/responses.ts +++ b/packages/vertexai/src/types/imagen/responses.ts @@ -15,19 +15,69 @@ * limitations under the License. */ +/** + * An image generated by Imagen, represented as inline data. + * + * @beta + */ export interface ImagenInlineImage { + /** + * The MIME type of the image; either `"image/png"` or `"image/jpeg"`. + * + * To request a different format, set the `imageFormat` property in your {@link ImagenGenerationConfig}. + */ mimeType: string; + /** + * The base64-encoded image data. + */ bytesBase64Encoded: string; } +/** + * An image generated by Imagen, stored in a Cloud Storage for Firebase bucket. + * + * This feature is not available yet. + */ export interface ImagenGCSImage { + /** + * The MIME type of the image; either `"image/png"` or `"image/jpeg"`. + * + * To request a different format, set the `imageFormat` property in your {@link ImagenGenerationConfig}. + */ mimeType: string; + /** + * The URI of the file stored in a Cloud Storage for Firebase bucket. + * + * @example `"gs://bucket-name/path/sample_0.jpg"`. + */ gcsURI: string; } +/** + * The response from a request to generate images with Imagen. + * + * @beta + */ export interface ImagenGenerationResponse< T extends ImagenInlineImage | ImagenGCSImage > { + /** + * The images generated by Imagen. + * + * The number of images generated may be fewer than the number requested if one or more were + * filtered out; see `filteredReason`. + */ images: T[]; + /** + * The reason that images were filtered out. This property will only be defined if one + * or more images were filtered. + * + * Images may be filtered out due to the {@link ImagenSafetyFilterLevel}, + * {@link ImagenPersonFilterLevel}, or filtering included in the model. + * The filter levels may be adjusted in your {@link ImagenSafetySettings}. + * + * See the {@link https://cloud.google.com/vertex-ai/generative-ai/docs/image/responsible-ai-imagen | Responsible AI and usage guidelines for Imagen} + * for more details. + */ filteredReason?: string; }