Image generation API

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

View Imagen for Generation model card

Supported model versions

Caution: The following Imagen 4 preview models will be removed on November 30, 2025 : imagen-4.0-generate-preview-06-06 , imagen-4.0-ultra-generate-preview-06-06 , and imagen-4.0-fast-generate-preview-06-06 . To avoid service disruption, migrate all workflows that use Imagen 4 preview models before November 30, 2025 , 2025, to the following Imagen 4 Generally Available models: imagen-4.0-generate-001 , imagen-4.0-ultra-generate-001 , imagen-4.0-fast-generate-001 .

Imagen API supports the following models:

imagen-4.0-generate-001
imagen-4.0-fast-generate-001
imagen-4.0-ultra-generate-001
imagen-3.0-generate-002
imagen-3.0-generate-001
imagen-3.0-fast-generate-001
imagen-3.0-capability-001

For more information about the features that each model supports, see Imagen models .

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 
 ( 
 " MODEL_VERSION 
" 
 ) 
 response 
 = 
 generation_model 
 . 
 generate_images 
 ( 
 prompt 
 = 
 " ... 
" 
 , 
 negative_prompt 
 = 
 " ... 
" 
 , 
 aspect_ratio 
 = ... 
 
 , 
 ) 
 response 
 . 
 images 
 [ 
 0 
 ] 
 . 
 show 
 ()

Generate images

REST

Parameters

addWatermark

bool

Optional. Add an invisible watermark to the generated images.

The default value is true .

aspectRatio

string

Optional. The aspect ratio for the generated output image. The default value is "1:1". This parameter doesn't apply to upscaled output.

enhancePrompt

boolean

Optional. An optional parameter to use an LLM-based prompt rewriting feature to deliver higher quality images that better reflect the original prompt's intent. Disabling this feature may impact image quality and prompt adherence.

language

string

Optional. The language code that corresponds to your text prompt language. The following values are supported:

auto : Automatic detection. If Imagen detects a supported language, the prompt and an optional negative prompt are translated to English. If the language detected isn't supported, Imagen uses the input text verbatim, which might result in an unexpected output. No error code is returned.
en : English (if omitted, the default value)
zh or zh-CN : Chinese (simplified)
zh-TW : Chinese (traditional)
hi : Hindi
ja : Japanese
ko : Korean
pt : Portuguese
es : Spanish

negativePrompt

string

Optional. A description of what to discourage in the generated images.

negativePrompt isn't supported by imagen-3.0-generate-002 and newer models.

outputOptions

Optional. Describes the output image format in an outputOptions object .

prompt

string

Required. The text prompt for the image.

personGeneration

string

Optional. 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

string

Optional. 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" .

sampleCount

int

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

sampleImageSize

string

Optional. Specifies the generated image's output resolution. The accepted values are "1K" or "2K" . The default value is "1K" .

seed

Uint32

Optional. The random seed for image generation. This isn't available when addWatermark is set to true .

If enhancePrompt is set to true , the seed parameter won't work, because enhancePrompt generates a new prompt, which results in a new or different image.

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

add_watermark

bool

Optional. Add a watermark to the generated image.

The default value is true .

aspect_ratio

string

Optional. The aspect ratio for the generated output image. The default value is "1:1". This parameter doesn't apply to upscaled output.

compression_quality

int

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

language

string

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

auto : Automatic detection. If Imagen detects a supported language, the prompt and an optional negative prompt are translated to English. If the language detected isn't supported, Imagen uses the input text verbatim, which might result in an unexpected output. No error code is returned.
en : English (if omitted, the default value)
zh or zh-CN : Chinese (simplified)
zh-TW : Chinese (traditional)
hi : Hindi
ja : Japanese
ko : Korean
pt : Portuguese
es : Spanish

The default value is "auto" .

negative_prompt

string

Optional. A description of what to discourage in the generated images.

negative_prompt isn't supported by imagen-3.0-generate-002 and newer models.

number_of_images

int

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

output_gcs_uri

string

Optional. Cloud Storage URI to store the generated images.

output_mime_type

string

Optional. 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" .

prompt

string

Required. The text prompt for the image.

person_generation

string

Optional. 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" .

safety_filter_level

string

Optional. 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" .

sample_image_size

string

Optional. Specifies the generated image's output resolution. The accepted values are "1K" or "2K" . The default value is "1K" .

seed

int

Optional. The random seed for image generation. This isn't available when addWatermark is set to true .

If enhancePrompt is set to true , the seed won't work, because enhancePrompt generates a new prompt, which results in a new or different image.

Upscale images

REST

Parameter

mode

string

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

upscaleConfig

UpscaleConfig

Required. An UpscaleConfig object .

outputOptions

OutputOptions

Optional. Describes the output image format in an outputOptions object .

storageUri

string

Optional. Cloud Storage URI for where to store the generated images.

Upscale config object

Parameter

upscaleConfig.upscaleFactor

string

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

Response

The response body from the REST request.

Parameter

predictions

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:

REGION : The region that your project is located in. For more information about supported regions, see Generative AI on Vertex AI locations .
PROJECT_ID : Your Google Cloud project ID .
MODEL_VERSION : The Imagen model version to use. For more information about available models, see Imagen models .
TEXT_PROMPT : The text prompt that guides what images the model generates. This field is required for both generation and editing.
IMAGE_COUNT : The number of images to generate. The accepted range of values is 1 to 4 .

Additional optional parameters

Use the following optional variables depending on your use case. Add some or all of the following parameters in the "parameters": {} object. This list shows common optional parameters and isn't meant to be exhaustive. For more information about optional parameters, see Imagen API reference: Generate images .

"parameters": {
  "sampleCount": IMAGE_COUNT 
, "addWatermark": ADD_WATERMARK 
,
  "aspectRatio": " ASPECT_RATIO 
",
  "enhancePrompt": ENABLE_PROMPT_REWRITING 
,
  "includeRaiReason": INCLUDE_RAI_REASON 
,
  "includeSafetyAttributes": INCLUDE_SAFETY_ATTRIBUTES 
,
  "outputOptions": {
    "mimeType": " MIME_TYPE 
",
    "compressionQuality": COMPRESSION_QUALITY 
},
  "personGeneration": " PERSON_SETTING 
",
  "safetySetting": " SAFETY_SETTING 
",
  "seed": SEED_NUMBER 
,
  "storageUri": " OUTPUT_STORAGE_URI 
"}

ADD_WATERMARK : boolean. Optional. Whether to enable a watermark for generated images. Any image generated when the field is set to true contains a digital SynthID that you can use to verify a watermarked image. If you omit this field, the default value of true is used; you must set the value to false to disable this feature. You can use the seed field to get deterministic output only when this field is set to false .
ASPECT_RATIO : string. Optional. A generation mode parameter that controls aspect ratio. Supported ratio values and their intended use:
- 1:1 (default, square)
- 3:4 (Ads, social media)
- 4:3 (TV, photography)
- 16:9 (landscape)
- 9:16 (portrait)
ENABLE_PROMPT_REWRITING : boolean. Optional. A parameter to use an LLM-based prompt rewriting feature to deliver higher quality images that better reflect the original prompt's intent. Disabling this feature may impact image quality and prompt adherence. Default value: true .
INCLUDE_RAI_REASON : boolean. Optional. Whether to enable the Responsible AI filtered reason code in responses with blocked input or output. Default value: true .
INCLUDE_SAFETY_ATTRIBUTES : boolean. Optional. Whether to enable rounded Responsible AI scores for a list of safety attributes in responses for unfiltered input and output. Safety attribute categories: "Death, Harm & Tragedy" , "Firearms & Weapons" , "Hate" , "Health" , "Illicit Drugs" , "Politics" , "Porn" , "Religion & Belief" , "Toxic" , "Violence" , "Vulgarity" , "War & Conflict" . Default value: false .
MIME_TYPE : string. Optional. The MIME type of the content of the image. Available values:
- image/jpeg
- image/gif
- image/png
- image/webp
- image/bmp
- image/tiff
- image/vnd.microsoft.icon
COMPRESSION_QUALITY : integer. Optional. Only applies to JPEG output files. The level of detail the model preserves for images generated in JPEG file format. Values: 0 to 100 , where a higher number means more compression. Default: 75 .
PERSON_SETTING : string. Optional. The safety setting that controls the type of people or face generation the model allows. Available values:
- allow_adult (default): Allow generation of adults only, except for celebrity generation. Celebrity generation is not allowed for any setting.
- dont_allow : Disable the inclusion of people or faces in generated images.
SAFETY_SETTING : string. Optional. A setting that controls safety filter thresholds for generated images. Available values:
- block_low_and_above : The highest safety threshold, resulting in the largest amount of generated images that are filtered. Previous value: block_most .
- block_medium_and_above (default): A medium safety threshold that balances filtering for potentially harmful and safe content. Previous value: block_some .
- block_only_high : A safety threshold that reduces the number of requests blocked due to safety filters. This setting might increase objectionable content generated by Imagen. Previous value: block_few .
SEED_NUMBER : integer. Optional. Any non-negative integer you provide to make output images deterministic. Providing the same seed number always results in the same output images. If the model you're using supports digital watermarking, you must set "addWatermark": false to use this field. Accepted integer values: 1 - 2147483647 .
OUTPUT_STORAGE_URI : string. Optional. The Cloud Storage bucket to store the output images. If not provided, base64-encoded image bytes are returned in the response. Sample value: gs://image-bucket/output/ .

HTTP method and URL:

POST https:// REGION 
-aiplatform.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ REGION 
/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

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell , which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list .

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:// REGION 
-aiplatform.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ REGION 
/publishers/google/models/ MODEL_VERSION 
:predict"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list .

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:// REGION 
-aiplatform.googleapis.com/v1/projects/ PROJECT_ID 
/locations/ REGION 
/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 
" 
  
 } 
  
 ] 
 }

If you use a model that supports prompt enhancement, the response includes an additional prompt field with the enhanced prompt used for generation:

{
  "predictions": [
    {
      "mimeType": " MIME_TYPE 
", "prompt": " ENHANCED_PROMPT_1 
","bytesBase64Encoded": " BASE64_IMG_BYTES_1 
"
    },
    {
      "mimeType": " MIME_TYPE 
", "prompt": " ENHANCED_PROMPT_2 
","bytesBase64Encoded": " BASE64_IMG_BYTES_2 
"
    }
  ]
}

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-002" 
 ) 
 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

For more information, see Imagen on Vertex AI overview and Generate images using text prompts .

Generate images using text prompts