Generate deterministic images

REST

Seed number is an optional field in the parameters object of a JSON request body.

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

• PROJECT_ID: Your Google Cloud project ID.

• MODEL_VERSION: The Imagen model version to use. For more information about available models, see Imagen models.

• 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 that 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 (imagegeneration@002), 1-4 (all other model versions). Default value: 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://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 -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"

$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

{
  "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"
    }
  ]
}

1. Replace the following:

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

{
  "instances": [
    ...
  ],
  "parameters": {
    "sampleCount": IMAGE_COUNT,
    "seed": SEED_NUMBER,
    // required for model version 006 and greater only when using a seed number
    "addWatermark": false
  }
}