Add Image Generation support using Imagen

.changeset/violet-planets-impress.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/vertexai': minor
+---
+
+**Public Preview** Added support for generating images using the Imagen 3 model.

common/api-review/vertexai.api.md

@@ -323,16 +323,14 @@ export interface GenerativeContentBlob {
 }
 
 // @public
-export class GenerativeModel {
+export class GenerativeModel extends VertexAIModel {
     constructor(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: RequestOptions);
     countTokens(request: CountTokensRequest | string | Array<string | Part>): Promise<CountTokensResponse>;
     generateContent(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentResult>;
     generateContentStream(request: GenerateContentRequest | string | Array<string | Part>): Promise<GenerateContentStreamResult>;
     // (undocumented)
     generationConfig: GenerationConfig;
     // (undocumented)
-    model: string;
-    // (undocumented)
     requestOptions?: RequestOptions;
     // (undocumented)
     safetySettings: SafetySetting[];
@@ -348,6 +346,9 @@ export class GenerativeModel {
 // @public
 export function getGenerativeModel(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: RequestOptions): GenerativeModel;
 
+// @beta
+export function getImagenModel(vertexAI: VertexAI, modelParams: ImagenModelParams, requestOptions?: RequestOptions): ImagenModel;
+
 // @public
 export function getVertexAI(app?: FirebaseApp, options?: VertexAIOptions): VertexAI;
 
@@ -429,6 +430,90 @@ export enum HarmSeverity {
     HARM_SEVERITY_NEGLIGIBLE = "HARM_SEVERITY_NEGLIGIBLE"
 }
 
+// @beta
+export enum ImagenAspectRatio {
+    LANDSCAPE_16x9 = "16:9",
+    LANDSCAPE_3x4 = "3:4",
+    PORTRAIT_4x3 = "4:3",
+    PORTRAIT_9x16 = "9:16",
+    SQUARE = "1:1"
+}
+
+// @public
+export interface ImagenGCSImage {
+    gcsURI: string;
+    mimeType: string;
+}
+
+// @beta
+export interface ImagenGenerationConfig {
+    addWatermark?: boolean;
+    aspectRatio?: ImagenAspectRatio;
+    imageFormat?: ImagenImageFormat;
+    negativePrompt?: string;
+    numberOfImages?: number;
+}
+
+// @beta
+export interface ImagenGenerationResponse<T extends ImagenInlineImage | ImagenGCSImage> {
+    filteredReason?: string;
+    images: T[];
+}
+
+// @beta
+export class ImagenImageFormat {
+    compressionQuality?: number;
+    static jpeg(compressionQuality?: number): ImagenImageFormat;
+    mimeType: string;
+    static png(): ImagenImageFormat;
+}
+
+// @beta
+export interface ImagenInlineImage {
+    bytesBase64Encoded: string;
+    mimeType: string;
+}
+
+// @beta
+export class ImagenModel extends VertexAIModel {
+    constructor(vertexAI: VertexAI, modelParams: ImagenModelParams, requestOptions?: RequestOptions | undefined);
+    generateImages(prompt: string): Promise<ImagenGenerationResponse<ImagenInlineImage>>;
+    // @internal
+    generateImagesGCS(prompt: string, gcsURI: string): Promise<ImagenGenerationResponse<ImagenGCSImage>>;
+    generationConfig?: ImagenGenerationConfig;
+    // (undocumented)
+    requestOptions?: RequestOptions | undefined;
+    safetySettings?: ImagenSafetySettings;
+}
+
+// @beta
+export interface ImagenModelParams {
+    generationConfig?: ImagenGenerationConfig;
+    model: string;
+    safetySettings?: ImagenSafetySettings;
+}
+
+// @beta
+export enum ImagenPersonFilterLevel {
+    ALLOW_ADULT = "allow_adult",
+    ALLOW_ALL = "allow_all",
+    BLOCK_ALL = "dont_allow"
+}
+
+// @beta
+export enum ImagenSafetyFilterLevel {
+    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"
+}
+
+// @beta
+export interface ImagenSafetySettings {
+    personFilterLevel?: ImagenPersonFilterLevel;
+    safetyFilterLevel?: ImagenSafetyFilterLevel;
+}
+
 // @public
 export interface InlineDataPart {
     // (undocumented)
@@ -718,6 +803,16 @@ export const enum VertexAIErrorCode {
     RESPONSE_ERROR = "response-error"
 }
 
+// @public
+export abstract class VertexAIModel {
+    // @internal
+    protected constructor(vertexAI: VertexAI, modelName: string);
+    // @internal (undocumented)
+    protected _apiSettings: ApiSettings;
+    readonly model: string;
+    static normalizeModelName(modelName: string): string;
+}
+
 // @public
 export interface VertexAIOptions {
     // (undocumented)

docs-devsite/_toc.yaml

@@ -536,6 +536,22 @@ toc:
     path: /docs/reference/js/vertexai.groundingattribution.md
   - title: GroundingMetadata
     path: /docs/reference/js/vertexai.groundingmetadata.md
+  - title: ImagenGCSImage
+    path: /docs/reference/js/vertexai.imagengcsimage.md
+  - title: ImagenGenerationConfig
+    path: /docs/reference/js/vertexai.imagengenerationconfig.md
+  - title: ImagenGenerationResponse
+    path: /docs/reference/js/vertexai.imagengenerationresponse.md
+  - title: ImagenImageFormat
+    path: /docs/reference/js/vertexai.imagenimageformat.md
+  - title: ImagenInlineImage
+    path: /docs/reference/js/vertexai.imageninlineimage.md
+  - title: ImagenModel
+    path: /docs/reference/js/vertexai.imagenmodel.md
+  - title: ImagenModelParams
+    path: /docs/reference/js/vertexai.imagenmodelparams.md
+  - title: ImagenSafetySettings
+    path: /docs/reference/js/vertexai.imagensafetysettings.md
   - title: InlineDataPart
     path: /docs/reference/js/vertexai.inlinedatapart.md
   - title: IntegerSchema
@@ -584,6 +600,8 @@ toc:
     path: /docs/reference/js/vertexai.vertexai.md
   - title: VertexAIError
     path: /docs/reference/js/vertexai.vertexaierror.md
+  - title: VertexAIModel
+    path: /docs/reference/js/vertexai.vertexaimodel.md
   - title: VertexAIOptions
     path: /docs/reference/js/vertexai.vertexaioptions.md
   - title: VideoMetadata

docs-devsite/vertexai.generativemodel.md

@@ -15,8 +15,9 @@ Class for generative model APIs.
 <b>Signature:</b>
 
 ```typescript
-export declare class GenerativeModel 
+export declare class GenerativeModel extends VertexAIModel 
 ```
+<b>Extends:</b> [VertexAIModel](./vertexai.vertexaimodel.md#vertexaimodel_class)
 
 ## Constructors
 
@@ -29,7 +30,6 @@ export declare class GenerativeModel
 |  Property | Modifiers | Type | Description |
 |  --- | --- | --- | --- |
 |  [generationConfig](./vertexai.generativemodel.md#generativemodelgenerationconfig) |  | [GenerationConfig](./vertexai.generationconfig.md#generationconfig_interface) |  |
-|  [model](./vertexai.generativemodel.md#generativemodelmodel) |  | string |  |
 |  [requestOptions](./vertexai.generativemodel.md#generativemodelrequestoptions) |  | [RequestOptions](./vertexai.requestoptions.md#requestoptions_interface) |  |
 |  [safetySettings](./vertexai.generativemodel.md#generativemodelsafetysettings) |  | [SafetySetting](./vertexai.safetysetting.md#safetysetting_interface)<!-- -->\[\] |  |
 |  [systemInstruction](./vertexai.generativemodel.md#generativemodelsysteminstruction) |  | [Content](./vertexai.content.md#content_interface) |  |
@@ -71,14 +71,6 @@ constructor(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: Reque
 generationConfig: GenerationConfig;
 ```
 
-## GenerativeModel.model
-
-<b>Signature:</b>
-
-```typescript
-model: string;
-```
-
 ## GenerativeModel.requestOptions
 
 <b>Signature:</b>

docs-devsite/vertexai.imagengcsimage.md

@@ -0,0 +1,54 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+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.
+
+<b>Signature:</b>
+
+```typescript
+export interface ImagenGCSImage 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [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 <code>&quot;image/png&quot;</code> or <code>&quot;image/jpeg&quot;</code>.<!-- -->To request a different format, set the <code>imageFormat</code> property in your <code>[ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface)</code>. |
+
+## ImagenGCSImage.gcsURI
+
+The URI of the file stored in a Cloud Storage for Firebase bucket.
+
+<b>Signature:</b>
+
+```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 <code>[ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface)</code>.
+
+<b>Signature:</b>
+
+```typescript
+mimeType: string;
+```

docs-devsite/vertexai.imagengenerationconfig.md

@@ -0,0 +1,111 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+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.
+
+<b>Signature:</b>
+
+```typescript
+export interface ImagenGenerationConfig 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [addWatermark](./vertexai.imagengenerationconfig.md#imagengenerationconfigaddwatermark) | boolean | <b><i>(Public Preview)</i></b> Whether to add an invisible watermark to generated images.<!-- -->If set to <code>true</code>, an invisible SynthID watermark is embedded in generated images to indicate that they are AI generated. If set to <code>false</code>, watermarking will be disabled.<!-- -->For Imagen 3 models, the default value is <code>true</code>; see the <a href="http://firebase.google.com/docs/vertex-ai/model-parameters#imagen"><code>addWatermark</code></a> documentation for more details. |
+|  [aspectRatio](./vertexai.imagengenerationconfig.md#imagengenerationconfigaspectratio) | [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | <b><i>(Public Preview)</i></b> The aspect ratio of the generated images. The default value is square 1:1. Supported aspect ratios depend on the Imagen model, see <code>[ImagenAspectRatio](./vertexai.md#imagenaspectratio)</code> for more details. |
+|  [imageFormat](./vertexai.imagengenerationconfig.md#imagengenerationconfigimageformat) | [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) | <b><i>(Public Preview)</i></b> The image format of the generated images. The default is PNG.<!-- -->See <code>[ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class)</code> for more details. |
+|  [negativePrompt](./vertexai.imagengenerationconfig.md#imagengenerationconfignegativeprompt) | string | <b><i>(Public Preview)</i></b> 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 | <b><i>(Public Preview)</i></b> 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 <a href="http://firebase.google.com/docs/vertex-ai/model-parameters#imagen"><code>sampleCount</code></a> 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 <a href="http://firebase.google.com/docs/vertex-ai/model-parameters#imagen"><code>addWatermark</code></a> documentation for more details.
+
+<b>Signature:</b>
+
+```typescript
+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 <code>[ImagenAspectRatio](./vertexai.md#imagenaspectratio)</code> for more details.
+
+<b>Signature:</b>
+
+```typescript
+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 <code>[ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class)</code> for more details.
+
+<b>Signature:</b>
+
+```typescript
+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.
+
+<b>Signature:</b>
+
+```typescript
+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 <a href="http://firebase.google.com/docs/vertex-ai/model-parameters#imagen"><code>sampleCount</code></a> documentation for more details.
+
+<b>Signature:</b>
+
+```typescript
+numberOfImages?: number;
+```