POST /tryon-api

Generate a virtual try-on by combining a shopper photo with a product image.

Endpoint

POST https://api.wearo.io/functions/v1/tryon-api

Request body

Field	Type	Required	Description
`userPhoto`	string	Yes	Shopper photo — URL or Base64 (see formats below)
`productImage`	string	Yes	Product image — URL or Base64 (same formats as `userPhoto`)
`clothingType`	string	No	Category hint (e.g., `"T-shirt"`, `"Dress"`, `"Jacket"`)
`productType`	string	No	Set to `"wedding-dress"` to enable bridal train rendering (see below). This mode consumes 2 credits.
`parentUrl`	string	No	Source product page URL (used for attribution / analytics)
`locale`	string	No	Output locale hint (e.g., `"en"`, `"fr"`)

Image formats

Both userPhoto and productImage accept a public URL or a Base64 string. URL (recommended for server-to-server):

{
  "userPhoto": "https://example.com/customer-photo.jpg",
  "productImage": "https://mystore.com/products/shirt.jpg"
}

Base64 with data URI prefix:

{
  "userPhoto": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "productImage": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Base64 raw (without prefix):

{
  "userPhoto": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "productImage": "/9j/4AAQSkZJRgABAQAAAQABAAD..."
}

Wedding-dress mode (train rendering)

The try-on engine normally drops the train of long / wedding gowns. Set productType: "wedding-dress" to render the full gown including the train spread on the floor. Example request

curl -X POST https://api.wearo.io/functions/v1/tryon-api \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wk_live_xxx" \
  -d '{
    "userPhoto": "https://cdn.example.com/person.jpg",
    "productImage": "https://cdn.example.com/gown.jpg",
    "clothingType": "Wedding Dress",
    "productType": "wedding-dress",
    "parentUrl": "https://merchant.com/product/gown",
    "locale": "en"
  }'

Only productType: "wedding-dress" is specific to bridal mode — every other field is identical to a standard try-on.

Train evaluation and refunds

After generation, the engine scores how well the train (the gown’s trailing fabric) was rendered. The verdict is returned in the bridal object:

bridal.applied: true → the train was rendered satisfactorily. 2 credits are consumed.
bridal.applied: false → the train was not rendered (low trainScore). No credit is consumed — both credits are refunded and the result is still delivered without regeneration.

This mode consumes 2 credits (a standard try-on consumes 1).

If the train verdict is unsatisfactory (bridal.applied: false) → both credits are refunded (no credit consumed).
If the generation fails outright → both credits are refunded.
If only the train pre-treatment can’t run → the extra credit is refunded and you are billed a single credit for the standard try-on that is still delivered.

Best results

Both the customer and the gown photos should be full-length, front-facing, standing.
A cropped, angled, or partial customer photo noticeably degrades the result.

Never breaks. If the pre-treatment can’t run, the request falls back to a standard try-on (gown rendered without the train) — it does not return an error.

Success response — 200 OK

{
  "success": true,
  "tryOnId": "9f1c2d3e-ab9e-41d2-8828-60c2800bbf91",
  "shortId": "aB7xQ2",
  "resultUrl": "https://api.wearo.io/results/user123/result_1234567890.jpg",
  "creditsRemaining": 18,
  "bridal": {
    "applied": true,
    "trainScore": 0.82
  }
}

Field	Type	Description
`success`	boolean	`true` for successful requests
`tryOnId`	string	Unique identifier for this generation
`shortId`	string \| null	Short shareable identifier; `null` when the bridal train verdict fails
`resultUrl`	string	Public URL of the generated image (permanent, no expiration)
`creditsRemaining`	number	Remaining credit balance after this request
`bridal.applied`	boolean	`true` when the bridal train was rendered satisfactorily
`bridal.trainScore`	number \| null	Train rendering quality score (0–1). `null` if the sidecar score is unavailable

Train not rendered (verdict fail)

When bridal.applied is false, the train was not rendered. Both credits are refunded and the result is still delivered — there is no regeneration.

{
  "success": true,
  "tryOnId": "7a2b3c4d-ab9e-41d2-8828-60c2800bbf91",
  "shortId": null,
  "resultUrl": "https://api.wearo.io/results/user123/result_1234567890.jpg",
  "creditsRemaining": 20,
  "bridal": {
    "applied": false,
    "trainScore": 0.03
  }
}

trainScore may be null if the sidecar /score endpoint is unavailable. The result is still delivered, but without a refund (the verdict could not be evaluated).

Error responses

HTTP	Error	Cause
400	Missing / invalid field	A required field is missing, the image can’t be fetched, or the image is smaller than 1 KB
401	`Authentication required`	Missing auth header or invalid API key
402	`Insufficient credits`	No credits remaining
403	Forbidden	Key inactive or domain not authorized
422	`ai_content_rejected`	The AI engine rejected the content
500	AI generation / infra error	AI model or infrastructure error — retry
503	`bridal_preprocessing_failed`	Wedding-dress pre-processing crashed — generation cancelled and fully refunded

If the wedding-dress pre-processing crashes, the request returns:

{
  "error": "Wedding-dress processing is temporarily unavailable. No credits were charged.",
  "errorCode": "bridal_preprocessing_failed"
}

HTTP 503 — generation is cancelled and fully refunded.

A 404 from Cloudflare ({"error":"requested path is invalid"}, with a CF-RAY header) means the request URL is wrong — not a Wearo error. Double-check the path is /functions/v1/tryon-api and that your key is sent as the X-API-Key header, never as a query parameter.

Full error reference →

Code examples

See Code examples → for curl, Node, Python, PHP, and Ruby.

Getting started

Install the widget

Configure the widget

Direct API

Privacy & compliance

Resources

POST /tryon-api

POST /tryon-api

Endpoint

Request body

Image formats

Wedding-dress mode (train rendering)

Train evaluation and refunds

Best results

Success response — 200 OK

Train not rendered (verdict fail)

Error responses

Code examples

​POST /tryon-api

​Endpoint

​Request body

​Image formats

​Wedding-dress mode (train rendering)

​Train evaluation and refunds

​Best results

​Success response — 200 OK

​Train not rendered (verdict fail)

​Error responses

​Code examples

POST /tryon-api

Endpoint

Request body

Image formats

Wedding-dress mode (train rendering)

Train evaluation and refunds

Best results

Success response — 200 OK

Train not rendered (verdict fail)

Error responses

Code examples