Virtual Try-On API

This guide shows you how to use the Virtual Try-On API to generate virtual try-on images of people modeling clothing products.

This page covers the following topics:

Image input options

When you provide an image of a person or a clothing product, you can specify it as either a Base64-encoded byte string or a Cloud Storage URI. The following table provides a comparison of these two options to help you decide which one to use.

Option Description Pros Cons Use Case
bytesBase64Encoded The image data is sent directly within the JSON request body. Simple for smaller images; no need for a separate storage step. Increases request size; not suitable for very large images due to JSON payload limits. Quick tests or applications where images are generated or processed on the fly and not stored long-term.
gcsUri A URI pointing to an image file stored in a Cloud Storage bucket. Efficient for large images; keeps the request payload small. Requires uploading the image to Cloud Storage first, which adds an extra step. Batch processing, workflows where images are already stored in Cloud Storage, or when dealing with large image files.

Supported model versions

Virtual Try-On supports the following model:

  • virtual-try-on-preview-08-04

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

HTTP request

To generate an image, send a POST request to the model's predict endpoint.

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": [     {       "personImage": {         "image": {           // Union field can be only one of the following:           "bytesBase64Encoded": string,           "gcsUri": string,         }       },       "productImages": [         {           "image": {             // Union field can be only one of the following:             "bytesBase64Encoded": string,             "gcsUri": string,           }         }       ]     }   ],   "parameters": {     "addWatermark": boolean,     "baseSteps": integer,     "personGeneration": string,     "safetySetting": string,     "sampleCount": integer,     "seed": integer,     "storageUri": string,     "outputOptions": {       "mimeType": string,       "compressionQuality": integer     }   } }'
Instances

personImage

string

Required. An image of a person to try-on the clothing product, which can be either of the following:

  • A bytesBase64Encoded string that encodes an image.
  • A gcsUri string URI to a Cloud Storage bucket location.

productImages

string

Required. An image of a product to try-on a person, which can be either of the following:

  • A bytesBase64Encoded string that encodes an image.
  • A gcsUri string URI to a Cloud Storage bucket location.
Parameters
addWatermark

bool

Optional. Add an invisible watermark to the generated images.

The default value is true.

baseSteps

int

Required. An integer that controls image generation, with higher steps trading higher quality for increased latency.

Integer values greater than 0. The default is 32.

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.

An integer value between 1 and 4, inclusive. The default value is 1.

seed

Uint32

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

storageUri

string

Optional. A string URI to a Cloud Storage bucket location to store the generated images.

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 through 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.
  • BASE64_PERSON_IMAGE: The Base64-encoded image of the person image.
  • BASE64_PRODUCT_IMAGE: The Base64-encoded image of the product image.
  • IMAGE_COUNT: The number of images to generate. The accepted range of values is 1 to 4.
  • GCS_OUTPUT_PATH: The Cloud Storage path to store the virtual try-on output to.

HTTP method and URL: 

POST https://REGION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/publishers/google/models/virtual-try-on-preview-08-04:predict

Request JSON body: 

 {   "instances": [     {       "personImage": {         "image": {           "bytesBase64Encoded": "BASE64_PERSON_IMAGE"         }       },       "productImages": [         {           "image": {             "bytesBase64Encoded": "BASE64_PRODUCT_IMAGE"           }         }       ]     }   ],   "parameters": {     "sampleCount": IMAGE_COUNT,     "storageUri": "GCS_OUTPUT_PATH"   } }

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/virtual-try-on-preview-08-04: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/virtual-try-on-preview-08-04: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"     }   ] }