Skip to main content
POST
Virtual try-on
Send a person photo and one to four garment references. The defaults are V6, standard quality, and one output image. V6 is available to all Studio API accounts with the required plan and credits.

Choose your inputs

There are two independent choices:
  1. Person photo: send person_image_url for a direct image URL, or person_image_id for an uploaded image.
  2. Garments: send one array: outfit_image_urls for direct image URLs, outfit_image_ids for uploaded images, or outfit_asset_ids for saved products.
You can combine any person source with any garment source. For example, a person URL works with saved product IDs. Use exactly one person field and one garment array per request.

Request examples

Replace the example URLs or IDs with your own references. Each array entry is one garment; num_images controls how many output images to generate.
One person and one garment, using direct image URLs.
Run the single-item example →

Submit and retrieve the result

A successful request returns HTTP 202 with a jobs array. Save each id, then get the job until it finishes. Read the completed media from result.url and its reusable ID from result.id. Use an Idempotency-Key when submitting work that may be retried. The Body reference below shows the required fields for each combination of person and garment sources.

Authorizations

Authorization
string
header
required

Create an API key in Studio → account menu → API Keys. Keep it on your server.

Headers

Idempotency-Key
string

Use a unique key for each intended creation. Retry the same method, path and JSON with the same key to replay its response for 24 hours after completion. Conflicting requests and unfinished or uncertain outcomes return 409. An uncertain receipt is never automatically rerun.

Required string length: 1 - 128
Pattern: ^[!-~]+$

Body

application/json
person_image_id
string<uuid>
required

Uploaded person image. Supply this or person_image_url.

outfit_image_ids
string<uuid>[]
required

Garment references. Choose one outfit source array per request. V6 supports up to four items; other models may accept fewer.

Required array length: 1 - 4 elements

Resource ID.

model
enum<string>
default:v6

Defaults to v6, available to all Studio API accounts with the required plan and credits. Older v4/v4x/v5 models can require account access.

Available options:
v6,
v1,
nano-banana,
nano-banana-pro,
nano-banana-2,
v4,
v4x,
v5
resolution
enum<string>
default:standard

Output quality; dimensions depend on the model and aspect ratio.

Available options:
standard,
high
num_images
integer
default:1

Number of outputs. Defaults to 1. Account limits still apply.

Required range: 1 <= x <= 8
Example:

1

seed
integer

Optional seed; it does not guarantee identical results.

aspect_ratio
string

Optional model-dependent output ratio.

person_image_url
string<uri>

Direct URL of a person photo.

outfit_image_urls
string<uri>[]

Garment references. Choose one outfit source array per request. V6 supports up to four items; other models may accept fewer.

Required array length: 1 - 4 elements
outfit_asset_ids
string<uuid>[]

Garment references. Choose one outfit source array per request. V6 supports up to four items; other models may accept fewer.

Required array length: 1 - 4 elements

Resource ID.

prompt
string

Optional styling instructions.

style
string

Optional style directions.

asset_ids
string[]

Additional reusable reference asset IDs. Supported types depend on the operation.

speed
string

V6 accepts fast (the default processing mode); choose resolution for quality. Other models have their own speed options.

Example:

"fast"

Response

Accepted; poll each job.

jobs
object[]
required
Minimum array length: 1