Skip to content

Commit 0900f82

Browse files
dlarocquedlarocque
authored
Imagen Documentation (#8776)
* Revert "remove public docs" This reverts commit f095563. * update docs * update docs * format * minor fixes * format * mark all APIs beta instead of public * review fixes * format * Replace (BETA) with (Public Preview) in docs * fix links * another pass * format * review fixes
1 parent 0e9ff0a commit 0900f82

19 files changed

+679
-136
lines changed

‎common/api-review/vertexai.api.md

+14-50
Original file line numberDiff line numberDiff line change
@@ -346,7 +346,7 @@ export class GenerativeModel extends VertexAIModel {
346346
// @public
347347
export function getGenerativeModel(vertexAI: VertexAI, modelParams: ModelParams, requestOptions?: RequestOptions): GenerativeModel;
348348

349-
// @public (undocumented)
349+
// @beta
350350
export function getImagenModel(vertexAI: VertexAI, modelParams: ImagenModelParams, requestOptions?: RequestOptions): ImagenModel;
351351

352352
// @public
@@ -430,122 +430,87 @@ export enum HarmSeverity {
430430
HARM_SEVERITY_NEGLIGIBLE = "HARM_SEVERITY_NEGLIGIBLE"
431431
}
432432

433-
// @public (undocumented)
433+
// @beta
434434
export enum ImagenAspectRatio {
435-
// (undocumented)
436435
LANDSCAPE_16x9 = "16:9",
437-
// (undocumented)
438436
LANDSCAPE_3x4 = "3:4",
439-
// (undocumented)
440437
PORTRAIT_4x3 = "4:3",
441-
// (undocumented)
442438
PORTRAIT_9x16 = "9:16",
443-
// (undocumented)
444439
SQUARE = "1:1"
445440
}
446441

447-
// @public (undocumented)
442+
// @public
448443
export interface ImagenGCSImage {
449-
// (undocumented)
450444
gcsURI: string;
451-
// (undocumented)
452445
mimeType: string;
453446
}
454447

455-
// @public (undocumented)
448+
// @beta
456449
export interface ImagenGenerationConfig {
457-
// (undocumented)
458450
addWatermark?: boolean;
459-
// (undocumented)
460451
aspectRatio?: ImagenAspectRatio;
461-
// (undocumented)
462452
imageFormat?: ImagenImageFormat;
463-
// (undocumented)
464453
negativePrompt?: string;
465-
// (undocumented)
466454
numberOfImages?: number;
467455
}
468456

469-
// @public (undocumented)
457+
// @beta
470458
export interface ImagenGenerationResponse<T extends ImagenInlineImage | ImagenGCSImage> {
471-
// (undocumented)
472459
filteredReason?: string;
473-
// (undocumented)
474460
images: T[];
475461
}
476462

477-
// @public
463+
// @beta
478464
export class ImagenImageFormat {
479-
// (undocumented)
480465
compressionQuality?: number;
481-
// (undocumented)
482466
static jpeg(compressionQuality?: number): ImagenImageFormat;
483-
// (undocumented)
484467
mimeType: string;
485-
// (undocumented)
486468
static png(): ImagenImageFormat;
487469
}
488470

489-
// @public
471+
// @beta
490472
export interface ImagenInlineImage {
491-
// (undocumented)
492473
bytesBase64Encoded: string;
493-
// (undocumented)
494474
mimeType: string;
495475
}
496476

497-
// @public (undocumented)
477+
// @beta
498478
export class ImagenModel extends VertexAIModel {
499479
constructor(vertexAI: VertexAI, modelParams: ImagenModelParams, requestOptions?: RequestOptions | undefined);
500-
// (undocumented)
501480
generateImages(prompt: string): Promise<ImagenGenerationResponse<ImagenInlineImage>>;
502-
// (undocumented)
481+
// @internal
503482
generateImagesGCS(prompt: string, gcsURI: string): Promise<ImagenGenerationResponse<ImagenGCSImage>>;
504-
// (undocumented)
505483
generationConfig?: ImagenGenerationConfig;
506484
// (undocumented)
507485
requestOptions?: RequestOptions | undefined;
508-
// (undocumented)
509486
safetySettings?: ImagenSafetySettings;
510487
}
511488

512-
// @public (undocumented)
489+
// @beta
513490
export interface ImagenModelParams {
514-
// (undocumented)
515491
generationConfig?: ImagenGenerationConfig;
516-
// (undocumented)
517492
model: string;
518-
// (undocumented)
519493
safetySettings?: ImagenSafetySettings;
520494
}
521495

522-
// @public (undocumented)
496+
// @beta
523497
export enum ImagenPersonFilterLevel {
524-
// (undocumented)
525498
ALLOW_ADULT = "allow_adult",
526-
// (undocumented)
527499
ALLOW_ALL = "allow_all",
528-
// (undocumented)
529500
BLOCK_ALL = "dont_allow"
530501
}
531502

532-
// @public (undocumented)
503+
// @beta
533504
export enum ImagenSafetyFilterLevel {
534-
// (undocumented)
535505
BLOCK_LOW_AND_ABOVE = "block_low_and_above",
536-
// (undocumented)
537506
BLOCK_MEDIUM_AND_ABOVE = "block_medium_and_above",
538-
// (undocumented)
539507
BLOCK_NONE = "block_none",
540-
// (undocumented)
541508
BLOCK_ONLY_HIGH = "block_only_high"
542509
}
543510

544-
// @public (undocumented)
511+
// @beta
545512
export interface ImagenSafetySettings {
546-
// (undocumented)
547513
personFilterLevel?: ImagenPersonFilterLevel;
548-
// (undocumented)
549514
safetyFilterLevel?: ImagenSafetyFilterLevel;
550515
}
551516

@@ -838,13 +803,12 @@ export const enum VertexAIErrorCode {
838803
RESPONSE_ERROR = "response-error"
839804
}
840805

841-
// @public (undocumented)
806+
// @public
842807
export abstract class VertexAIModel {
843808
// @internal
844809
protected constructor(vertexAI: VertexAI, modelName: string);
845810
// @internal (undocumented)
846811
protected _apiSettings: ApiSettings;
847-
// (undocumented)
848812
readonly model: string;
849813
static normalizeModelName(modelName: string): string;
850814
}

‎docs-devsite/vertexai.imagengcsimage.md

+16-2
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ https://github.com/firebase/firebase-js-sdk
1010
{% endcomment %}
1111

1212
# ImagenGCSImage interface
13+
An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.
14+
15+
This feature is not available yet.
16+
1317
<b>Signature:</b>
1418

1519
```typescript
@@ -20,19 +24,29 @@ export interface ImagenGCSImage
2024

2125
| Property | Type | Description |
2226
| --- | --- | --- |
23-
| [gcsURI](./vertexai.imagengcsimage.md#imagengcsimagegcsuri) | string | |
24-
| [mimeType](./vertexai.imagengcsimage.md#imagengcsimagemimetype) | string | |
27+
| [gcsURI](./vertexai.imagengcsimage.md#imagengcsimagegcsuri) | string | The URI of the file stored in a Cloud Storage for Firebase bucket. |
28+
| [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>. |
2529

2630
## ImagenGCSImage.gcsURI
2731

32+
The URI of the file stored in a Cloud Storage for Firebase bucket.
33+
2834
<b>Signature:</b>
2935

3036
```typescript
3137
gcsURI: string;
3238
```
3339

40+
### Example
41+
42+
`"gs://bucket-name/path/sample_0.jpg"`<!-- -->.
43+
3444
## ImagenGCSImage.mimeType
3545

46+
The MIME type of the image; either `"image/png"` or `"image/jpeg"`<!-- -->.
47+
48+
To request a different format, set the `imageFormat` property in your <code>[ImagenGenerationConfig](./vertexai.imagengenerationconfig.md#imagengenerationconfig_interface)</code>.
49+
3650
<b>Signature:</b>
3751

3852
```typescript

‎docs-devsite/vertexai.imagengenerationconfig.md

+49-5
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,13 @@ https://github.com/firebase/firebase-js-sdk
1010
{% endcomment %}
1111

1212
# ImagenGenerationConfig interface
13+
> 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.
14+
>
15+
16+
Configuration options for generating images with Imagen.
17+
18+
See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images-imagen) for more details.
19+
1320
<b>Signature:</b>
1421

1522
```typescript
@@ -20,14 +27,23 @@ export interface ImagenGenerationConfig
2027

2128
| Property | Type | Description |
2229
| --- | --- | --- |
23-
| [addWatermark](./vertexai.imagengenerationconfig.md#imagengenerationconfigaddwatermark) | boolean | |
24-
| [aspectRatio](./vertexai.imagengenerationconfig.md#imagengenerationconfigaspectratio) | [ImagenAspectRatio](./vertexai.md#imagenaspectratio) | |
25-
| [imageFormat](./vertexai.imagengenerationconfig.md#imagengenerationconfigimageformat) | [ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class) | |
26-
| [negativePrompt](./vertexai.imagengenerationconfig.md#imagengenerationconfignegativeprompt) | string | |
27-
| [numberOfImages](./vertexai.imagengenerationconfig.md#imagengenerationconfignumberofimages) | number | |
30+
| [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. |
31+
| [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. |
32+
| [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. |
33+
| [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. |
34+
| [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. |
2835

2936
## ImagenGenerationConfig.addWatermark
3037

38+
> 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.
39+
>
40+
41+
Whether to add an invisible watermark to generated images.
42+
43+
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.
44+
45+
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.
46+
3147
<b>Signature:</b>
3248

3349
```typescript
@@ -36,6 +52,11 @@ addWatermark?: boolean;
3652

3753
## ImagenGenerationConfig.aspectRatio
3854

55+
> 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.
56+
>
57+
58+
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.
59+
3960
<b>Signature:</b>
4061

4162
```typescript
@@ -44,6 +65,13 @@ aspectRatio?: ImagenAspectRatio;
4465

4566
## ImagenGenerationConfig.imageFormat
4667

68+
> 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.
69+
>
70+
71+
The image format of the generated images. The default is PNG.
72+
73+
See <code>[ImagenImageFormat](./vertexai.imagenimageformat.md#imagenimageformat_class)</code> for more details.
74+
4775
<b>Signature:</b>
4876

4977
```typescript
@@ -52,6 +80,15 @@ imageFormat?: ImagenImageFormat;
5280

5381
## ImagenGenerationConfig.negativePrompt
5482

83+
> 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.
84+
>
85+
86+
A description of what should be omitted from the generated images.
87+
88+
Support for negative prompts depends on the Imagen model.
89+
90+
See the [documentation](http://firebase.google.com/docs/vertex-ai/model-parameters#imagen) for more details.
91+
5592
<b>Signature:</b>
5693

5794
```typescript
@@ -60,6 +97,13 @@ negativePrompt?: string;
6097

6198
## ImagenGenerationConfig.numberOfImages
6299

100+
> 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.
101+
>
102+
103+
The number of images to generate. The default value is 1.
104+
105+
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.
106+
63107
<b>Signature:</b>
64108

65109
```typescript

‎docs-devsite/vertexai.imagengenerationresponse.md

+23-2
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ https://github.com/firebase/firebase-js-sdk
1010
{% endcomment %}
1111

1212
# ImagenGenerationResponse interface
13+
> 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.
14+
>
15+
16+
The response from a request to generate images with Imagen.
17+
1318
<b>Signature:</b>
1419

1520
```typescript
@@ -20,11 +25,20 @@ export interface ImagenGenerationResponse<T extends ImagenInlineImage | ImagenGC
2025

2126
| Property | Type | Description |
2227
| --- | --- | --- |
23-
| [filteredReason](./vertexai.imagengenerationresponse.md#imagengenerationresponsefilteredreason) | string | |
24-
| [images](./vertexai.imagengenerationresponse.md#imagengenerationresponseimages) | T\[\] | |
28+
| [filteredReason](./vertexai.imagengenerationresponse.md#imagengenerationresponsefilteredreason) | string | <b><i>(Public Preview)</i></b> 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 <code>[ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel)</code>, <code>[ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel)</code>, or filtering included in the model. The filter levels may be adjusted in your <code>[ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface)</code>.<!-- -->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. |
29+
| [images](./vertexai.imagengenerationresponse.md#imagengenerationresponseimages) | T\[\] | <b><i>(Public Preview)</i></b> 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 <code>filteredReason</code>. |
2530

2631
## ImagenGenerationResponse.filteredReason
2732

33+
> 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.
34+
>
35+
36+
The reason that images were filtered out. This property will only be defined if one or more images were filtered.
37+
38+
Images may be filtered out due to the <code>[ImagenSafetyFilterLevel](./vertexai.md#imagensafetyfilterlevel)</code>, <code>[ImagenPersonFilterLevel](./vertexai.md#imagenpersonfilterlevel)</code>, or filtering included in the model. The filter levels may be adjusted in your <code>[ImagenSafetySettings](./vertexai.imagensafetysettings.md#imagensafetysettings_interface)</code>.
39+
40+
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.
41+
2842
<b>Signature:</b>
2943

3044
```typescript
@@ -33,6 +47,13 @@ filteredReason?: string;
3347

3448
## ImagenGenerationResponse.images
3549

50+
> 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.
51+
>
52+
53+
The images generated by Imagen.
54+
55+
The number of images generated may be fewer than the number requested if one or more were filtered out; see `filteredReason`<!-- -->.
56+
3657
<b>Signature:</b>
3758

3859
```typescript

0 commit comments

Comments
 (0)