Imagen product recontext API

The Imagen product recontext on Vertex AI API lets you edit product images into different scenes or backgrounds. You provide an image of a product and a prompt, and Imagen product recontext generates images of your product in new scenes or with different backgrounds.

To request access to Imagen product recontext, complete the Vertex AI - Generative Media for Marketing Access Request form.

Supported model versions

Imagen product recontext supports the following models:

  • imagen-product-recontext-preview-06-30

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

HTTP request

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_ID:predict \

-d '{
  "instances": [
    {
      "prompt": string,
      "productImages": [
        // The following fields can be repeated up to 3 times for different
        // views of the same product.
        {
          "image": {
            // Union field can be only one of the following:
            "bytesBase64Encoded": string,
            "gcsUri": string,
            // End of list of possible types for union field.
          },
        }
      ]
    }
  ],
  "parameters": {
    "addWatermark": boolean,
    "enhancePrompt": boolean
    "personGeneration": string,
    "safetySetting": string,
    "sampleCount": integer,
    "seed": integer,
    "storageUri": string,
    "outputOptions": {
      "mimeType": string,
      "compressionQuality": integer
    }
  }
}'

Instances

Instances
prompt

string

Optional. A text prompt to guide the scene generation.
productImages

list[productImages]

A list of up to three different ProductImages of different views of the same product. The model uses the images to recontextualize the product into different scenes or backgrounds.

productImages object

The productImages object describes the image assets to place into different scenes or backgrounds.

productImages

Union field image.

Product image for imagen-product-recontext-preview-06-30 as input for different views of the product. Each image can be either a bytesBase64Encoded string that encodes an image or a gcsUri string URI to a Cloud Storage bucket location.

bytesBase64Encoded

string

A bytes base64-encoded string of an image or a video file.
gcsUri

string

A string URI to a Cloud Storage bucket location.

Parameters

Parameters
addWatermark

boolean

Optional. Add an invisible watermark to the generated images.

The default value is true.

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.

The default value is true.

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

The number of images to generate.

An integer value in the range of 1-4. The default value is 1.

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

string

Optional. A string URI to a Cloud Storage bucket location that is used to store the generated images. If a Cloud Storage bucket isn't provided, then base64-encoded image bytes are returned in the response.

outputOptions

outputOptions

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

Output options object

The outputOptions object describes the image output.

Parameters
outputOptions.mimeType

Optional: string

The image output format. 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- 100. The default value is 75.

Sample request

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.
  • TEXT_PROMPT: Optional. A text prompt to guide the images that the model generates.
  • BASE64_SUBJECT_IMAGE: A base64-encoded image of the subject image.
  • PERSON_SETTING: Optional: A string value that controls the type of person or face generation that the model allows. You can use the following values for personGeneration:
    • "allow_adult": Allows generation of adults only, except for celebrity generation. Celebrity generation isn't allowed for any setting. This is the default setting.
    • "allow_all": Allows generation of people of all ages, except for celebrity generation. Celebrity generation is not allowed for any setting.
    • "dont_allow": Doesn't allow generation of people or faces in generated output.
  • SAFETY_SETTING: Optional: A string value that controls the safety filter threshold for generated images. You can use the following values to select your safety setting:
    • "block_low_and_above": The most stringent safety threshold. "block_low_and_above" filters the largest number of generated images.
    • "block_medium_and_above": The medium safety threshold, which balances filtering for potentially harmful and safe content. "block_medium_and_above" is the default safety setting.
    • "block_only_high": The lowest safety threshold, which reduces the number of requests blocked due to safety filter. Using "block_only_high" safety threshold might increase the number of objectionable images generated by the model.
  • WATERMARK_SETTING: Optional: A boolean. When this values is set to true, the model adds a digital watermark that you can use to verify the generated image. The default value is true.
  • IMAGE_COUNT: The number of images to generate. The accepted range of values is 1-4.
  • PROMPT_SETTING: Optional: A boolean. When this value is set to true, the model uses enhanced prmopts. The default value is true.

HTTP method and URL: 

POST https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/imagen-product-recontext-preview-06-30:predict

Request JSON body: 

{
  "instances": [
    {
      "prompt": "TEXT_PROMPT",
      "productImages": [
        {
          "image": {
            "bytesBase64Encoded": "BASE64_SUBJECT_IMAGE"
          },
        }
      ]
    }
  ],
  "parameters": {
    "personGeneration": PERSON_SETTING,
    "safetySetting": SAFETY_SETTING,
    "addWatermark": WATERMARK_SETTING,
    "sampleCount": IMAGE_COUNT,
    "enhancePrompt": PROMPT_SETTING
  }
}

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://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/imagen-product-recontext-preview-06-30: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://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/imagen-product-recontext-preview-06-30:predict" | Select-Object -Expand Content
The request returns image objects. In this example, two image objects are returned, with two prediction objects as base64-encoded images. 
{
  "predictions": [
    {
      "mimeType": "image/png",
      "bytesBase64Encoded": "BASE64_IMG_BYTES"
    },
    {
      "bytesBase64Encoded": "BASE64_IMG_BYTES",
      "mimeType": "image/png"
    }
  ]
}