API guides / Virtual Try-On

See the possibility.

Generate a visual preview of a garment on a person, inside the experience you design.

Submit a generation

POST/v1/tryon

Send a person image and garment references. BeforeAI handles the generation. An optional hint identifies which garment to use in a busy reference image.

Field	Type	Usage
`person_image_url`	string	Required. Accessible HTTPS URL of the person image.
`garment_image_urls`	string or string[]	Required. One garment URL or a list of garment URLs. Confirm your account’s multi-garment capabilities and limits.
`garment_type`	string	Optional garment-category hint for a single garment. Omit it when uncertain.
`details`	string	Optional additional direction for the garment preview.

Try-On request body

{
  "person_image_url": "https://your-cdn.example.com/person.jpg",
  "garment_image_urls": "https://your-cdn.example.com/shirt.jpg",
  "garment_type": "upper_body"
}

Garment hints

The integration uses this vocabulary:

upper_bodylower_bodydressfull_bodyouterwearglassesshoesheadwearaccessories

For one garment, send a single string hint. For multiple garments, omit the hint unless your onboarding guide specifies otherwise. An incorrect hint can be less useful than leaving it out.

Immediate results

Field	Type	Usage
`generation_id`	string	Identifier for the generation.
`result_urls`	string[]	Generated images to display in your application.
`credits_charged`	number	Credits charged for this request.
`credits_available`	number	Account credit balance reported after the request.

Use the returned URLs rather than constructing result paths. A visual try-on is not a sizing or physical-fit guarantee.

Queued generations

Submission can return HTTP 202 when the generation is queued. Save the generation ID and show a pending state.

Illustrative queued response

{
  "generation_id": "example-generation-id",
  "status": "queued",
  "credits_charged": 16,
  "credits_available": 84
}

The ID and credit values above are illustrative, not a price quote.

GET/v1/tryon/{generation_id}

Field	Type	Usage
`generation_id`	string	The submitted job identifier.
`status`	string	queued, processing, completed, or failed.
`result_urls`	string[] or null	Available when the generation completes.
`error`	string or null	Failure detail, when provided.

Poll with the same API key. Stop on completed or failed. Use bounded polling with a delay and backoff, and let the user return to a pending job after your interface times out. Do not resubmit a generation simply because the result is not ready.

Design the customer journey

Collect a clear person photo and the chosen garment.
Upload images to storage and obtain accessible URLs.
Submit from your backend and preserve the generation ID.
Display the image when available, or a clear recovery action on failure.

PREVIOUSAuthentication

NEXTStylist