Generate images

The Imagen API lets you create high quality images in seconds, using text prompt to guide the generation. You can also upscale images using Imagen API.

Supported Models

Model Code
Image Generation imagen-3.0-generate-001
imagen-3.0-fast-generate-001
imagegeneration@006
imagegeneration@005
imagegeneration@002

For more information on how the features each model supports, see Model versioning.

Example syntax

Syntax to create an image from a text prompt.

Syntax

Syntax to generate an image.

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \

https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_VERSION}:predict \
-d '{
  "instances": [
    {
      "prompt": "..."
    }
  ],
  "parameters": {
    "sampleCount": ...
  }
}'

Python

generation_model = ImageGenerationModel.from_pretrained("imagen-3.0-generate-001")

response = generation_model.generate_images(
    prompt="...",
    negative_prompt="...",
    aspect_ratio=...,
)
response.images[0].show()

Parameter list

See examples for implementation details.

Generate images

REST

Parameters
prompt

Required: string

The text prompt for the image.

The imagen-3.0-generate-001 model supports up to 480 tokens.

The imagen-3.0-fast-generate-001 model supports up to 480 tokens.

The imagegeneration@006 model supports up to 128 tokens.

The imagegeneration@005 model supports up to 128 tokens.

The imagegeneration@002 model supports up to 64 tokens.
sampleCount

Required: int

The number of images to generate. The default value is 4.

The imagen-3.0-generate-001 model supports values 1 through 4.

The imagen-3.0-fast-generate-001 model supports values 1 through 4.

The imagegeneration@006 model supports values 1 through 4.

The imagegeneration@005 model supports values 1 through 4.

The imagegeneration@002 model supports values 1 through 8.
seed

Optional: Uint32

The random seed for image generation. This is not available when addWatermark is set to true.
negativePrompt

Optional: string

A description of what to discourage in the generated images.

The imagen-3.0-generate-001 model supports up to 480 tokens.

The imagen-3.0-fast-generate-001 model supports up to 480 tokens.

The imagegeneration@006 model supports up to 128 tokens.

The imagegeneration@005 model supports up to 128 tokens.

The imagegeneration@002 model supports up to 64 tokens.
aspectRatio

Optional: string

The aspect ratio for the image. The default value is "1:1".

The imagen-3.0-generate-001 model supports "1:1", "9:16", "16:9", "3:4", or "4:3".

The imagen-3.0-fast-generate-001 model supports "1:1", "9:16", "16:9", "3:4", or "4:3".

The imagegeneration@006 model supports "1:1", "9:16", "16:9", "3:4", or "4:3".

The imagegeneration@005 model supports "1:1" or "9:16".

The imagegeneration@002 model supports "1:1".
outputOptions

Optional: outputOptions

Describes the output image format in an outputOptions object.
sampleImageStyle

Optional: string (imagegeneration@002 only)

Describes the style for the generated images. The following values are supported:

  • "photograph"
  • "digital_art"
  • "landscape"
  • "sketch"
  • "watercolor"
  • "cyberpunk"
  • "pop_art"
personGeneration

Optional: string (imagen-3.0-generate-001, imagen-3.0-fast-generate-001, and imagegeneration@006 only)

Allow generation of people by the model. The following values are supported:

  • "dont_allow": Disallow the inclusion of people or faces in images.
  • "allow_adult": Allow generation of adults only.
  • "allow_all": Allow generation of people of all ages.

The default value is "allow_adult".
safetySetting

Optional: string (imagen-3.0-generate-001, imagen-3.0-fast-generate-001, and imagegeneration@006 only)

Adds a filter level to safety filtering. The following values are supported:

  • "block_low_and_above": Strongest filtering level, most strict blocking. Deprecated value: "block_most".
  • "block_medium_and_above": Block some problematic prompts and responses. Deprecated value: "block_some".
  • "block_only_high": Reduces the number of requests blocked due to safety filters. May increase objectionable content generated by Imagen. Deprecated value: "block_few".
  • "block_none": Block very few problematic prompts and responses. Access to this feature is restricted. Previous field value: "block_fewest".

The default value is "block_medium_and_above".
addWatermark

Optional: bool

Add an invisible watermark to the generated images. The default value is false for the imagegeneration@002 and imagegeneration@005 models, and true for the imagen-3.0-fast-generate-001, imagegeneration@006, and imagegeneration@006 models.
storageUri

Optional: string

Cloud Storage URI to store the generated images.

Output options object

The outputOptions object describes the image output.

Parameters
outputOptions.mimeType

Optional: string

The image format that the output should be saved as. The following values are supported:

  • "image/png": Save as a PNG image
  • "image/jpeg": Save as a JPEG image

The default value is "image/png".
outputOptions.compressionQuality

Optional: int

The level of compression if the output type is "image/jpeg". Accepted values are 0 through 100. The default value is 75.

Response

The response body from the REST request.

Parameter
predictions

An array of VisionGenerativeModelResult objects, one for each requested sampleCount. If any images are filtered by responsible AI, they are not included, unless includeRaiReason is set to true.

Vision generative model result object

Information about the model result.

Parameter
bytesBase64Encoded

The base64 encoded generated image. Not present if the output image did not pass responsible AI filters.
mimeType

The type of the generated image. Not present if the output image did not pass responsible AI filters.
raiFilteredReason

The responsible AI filter reason. Only returned if includeRaiReason is enabled and this image was filtered out.
safetyAttributes.categories

The safety attribute name. Only returned if includeSafetyAttributes is enabled, and the output image passed responsible AI filters.
safetyAttributes.scores

The safety attribute score. Only returned if includeSafetyAttributes is enabled, and the output image passed responsible AI filters.

Python

Parameters
prompt

Required: string

The text prompt for the image.

The imagen-3.0-generate-001 model supports up to 480 tokens.

The imagen-3.0-fast-generate-001 model supports up to 480 tokens.

The imagegeneration@006 model supports up to 128 tokens.

The imagegeneration@005 model supports up to 128 tokens.

The imagegeneration@002 model supports up to 64 tokens.
number_of_images

Required: int

The number of images to generate. The default value is 1.

The imagen-3.0-generate-001 model supports values 1 through 8.

The imagen-3.0-fast-generate-001 model supports values 1 through 8.

The imagegeneration@006 model supports values 1 through 4.

The imagegeneration@005 model supports values 1 through 4.

The imagegeneration@002 model supports values 1 through 8.
seed

Optional: int

The random seed for image generation. This is not available when addWatermark is set to true.
negative_prompt

Optional: string

A description of what to discourage in the generated images.

The imagen-3.0-generate-001 model supports up to 480 tokens.

The imagen-3.0-fast-generate-001 model supports up to 480 tokens.

The imagegeneration@006 model supports up to 128 tokens.

The imagegeneration@005 model supports up to 128 tokens.

The imagegeneration@002 model supports up to 64 tokens.
aspect_ratio

Optional: string

The aspect ratio for the image. The default value is "1:1".

The imagen-3.0-generate-001 model supports "1:1", "9:16", "16:9", "3:4", or "4:3".

The imagen-3.0-fast-generate-001 model supports "1:1", "9:16", "16:9", "3:4", or "4:3".

The imagegeneration@006 model supports "1:1", "9:16", "16:9", "3:4", or "4:3".
output_mime_type

Optional: string (imagen-3.0-generate-001, imagen-3.0-fast-generate-001, and imagegeneration@006 only)

The image format that the output should be saved as. The following values are supported:

  • "image/png": Save as a PNG image
  • "image/jpeg": Save as a JPEG image

The default value is "image/png".
compression_quality

Optional: int

The level of compression if the output mime type is "image/jpeg". The default value is 75.
language

Optional: string

The language of the text prompt for the image. The following values are supported:

  • "en": English
  • "hi": Hindi
  • "ja": Japanese
  • "ko": Korean
  • "auto": Automatic language detection

The default value is "auto".
output_gcs_uri

Optional: string

Cloud Storage URI to store the generated images.
add_watermark

Optional: bool

Add a watermark to the generated image. The default value is false for the imagegeneration@002 and imagegeneration@005 models, and true for the imagen-3.0-fast-generate-001, imagen-3.0-generate-001, and imagegeneration@006 models.
safety_filter_level

Optional: string

Adds a filter level to safety filtering. The following values are supported:

  • "block_low_and_above": The strongest filtering level, resulting in the most strict blocking. Deprecated value: "block_most".
  • "block_medium_and_above": Block some problematic prompts and responses. Deprecated value: "block_some".
  • "block_only_high": Block fewer problematic prompts and responses. Deprecated value: "block_few".
  • "block_none": Block very few problematic prompts and responses. Deprecated value: "block_fewest".

The default value is "block_medium_and_above".
person_generation

Optional: string (imagen-3.0-generate-001, imagen-3.0-fast-generate-001, and imagegeneration@006 only)

Allow generation of people by the model. The following values are supported:

  • "dont_allow": Block generation of people
  • "allow_adult": Generate adults, but not children
  • "allow_all": Generate adults and children

The default value is "allow_adult".

Upscale images

REST

Parameter
mode

Required: string

Must be set to "upscale" for upscaling requests.
upscaleConfig

Required: UpscaleConfig

An UpscaleConfig object.
outputOptions

Optional: OutputOptions

Describes the output image format in an outputOptions object.
storageUri

Optional: string

Cloud Storage URI for where to store the generated images.

Upscale config object

Parameter
upscaleConfig.upscaleFactor

Required: string

The upscale factor. The supported values are "x2" and "x4".

Response

The response body from the REST request.

Parameter
predictions

An array of VisionGenerativeModelResult objects, one for each requested sampleCount. If any images are filtered by responsible AI, they are not included, unless includeRaiReason is set to true.

Examples

The following examples show how to use the Imagen models to generate images.

Generate images

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID.
  • MODEL_VERSION: The imagegeneration model version to use. Available values:
    • Imagen 3:
      • imagen-3.0-generate-001
      • imagen-3.0-fast-generate-001 - Low latency model version.
    • Default model version:
      • imagegeneration - Uses the default model version v.006. As a best practice, you should always specify a model version, especially in production environments.

    For more information about model versions and features, see model versions.

  • LOCATION: Your project's region. For example, us-central1, europe-west2, or asia-northeast3. For a list of available regions, see Generative AI on Vertex AI locations.
  • TEXT_PROMPT: The text prompt guides what images the model generates. This field is required for both generation and editing.
  • IMAGE_COUNT: The number of generated images. Accepted integer values: 1-8 (v.002), 1-4 (all other model versions). Default value: 4.

HTTP method and URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict

Request JSON body: 

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT"
    }
  ],
  "parameters": {
    "sampleCount": IMAGE_COUNT
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_VERSION:predict" | Select-Object -Expand Content
The following sample response is for a request with "sampleCount": 2. The response returns two prediction objects, with the generated image bytes base64-encoded. 
{
  "predictions": [
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    },
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "BASE64_IMG_BYTES"
    }
  ]
}

Python

Before trying this sample, follow the Python setup instructions in the Vertex AI quickstart using client libraries. For more information, see the Vertex AI Python API reference documentation.

To authenticate to Vertex AI, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

In this sample you call the generate_images method on the ImageGenerationModel (@006 version) and save generated images locally. You then can optionally use the show() method in a notebook to show you the generated images. For more information on model versions and features, see model versions.


import vertexai
from vertexai.preview.vision_models import ImageGenerationModel

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# output_file = "input-image.png"
# prompt = "" # The text prompt describing what you want to see.

vertexai.init(project=PROJECT_ID, location="us-central1")

model = ImageGenerationModel.from_pretrained("imagen-3.0-generate-001")

images = model.generate_images(
    prompt=prompt,
    # Optional parameters
    number_of_images=1,
    language="en",
    # You can't use a seed value and watermark at the same time.
    # add_watermark=False,
    # seed=100,
    aspect_ratio="1:1",
    safety_filter_level="block_some",
    person_generation="allow_adult",
)

images[0].save(location=output_file, include_generation_parameters=False)

# Optional. View the generated image in a notebook.
# images[0].show()

print(f"Created output image using {len(images[0]._image_bytes)} bytes")
# Example response:
# Created output image using 1234567 bytes

Upscale images

REST

Before using any of the request data, make the following replacements:

  • LOCATION: Your project's region. For example, us-central1, europe-west2, or asia-northeast3. For a list of available regions, see Generative AI on Vertex AI locations.
  • PROJECT_ID: Your Google Cloud project ID.
  • B64_BASE_IMAGE: The base image to edit or upscale. The image must be specified as a base64-encoded byte string. Size limit: 10 MB.
  • IMAGE_SOURCE: The Cloud Storage location of the image you want to edit or upscale. For example: gs://output-bucket/source-photos/photo.png.
  • UPSCALE_FACTOR: Optional. The factor to which the image will be upscaled. If not specified, the upscale factor will be determined from the longer side of the input image and sampleImageSize. Available values: x2 or x4 .

HTTP method and URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict

Request JSON body: 

{
  "instances": [
    {
      "prompt": "",
      "image": {
        // use one of the following to specify the image to upscale
        "bytesBase64Encoded": "B64_BASE_IMAGE"
        "gcsUri": "IMAGE_SOURCE"
        // end of base image input options
      },
    }
  ],
  "parameters": {
    "sampleCount": 1,
    "mode": "upscale",
    "upscaleConfig": {
      "upscaleFactor": "UPSCALE_FACTOR"
    }
  }
}

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict"

PowerShell

Save the request body in a file named request.json, and execute the following command: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/imagegeneration@002:predict" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "predictions": [
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "iVBOR..[base64-encoded-upscaled-image]...YII="
    }
  ]
}

What's next