Skip to main content

​
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

FieldTypeRequiredDescription
userPhotostringYesShopper photo — URL or Base64 (see formats below)
productImagestringYesProduct image — URL or Base64 (same formats as userPhoto)
clothingTypestringNoCategory hint (e.g., "T-shirt", "Dress", "Jacket")
productTypestringNoSet to "wedding-dress" to enable bridal train rendering (see below). This mode consumes 2 credits.
parentUrlstringNoSource product page URL (used for attribution / analytics)
localestringNoOutput 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
  }
}
FieldTypeDescription
successbooleantrue for successful requests
tryOnIdstringUnique identifier for this generation
shortIdstring | nullShort shareable identifier; null when the bridal train verdict fails
resultUrlstringPublic URL of the generated image (permanent, no expiration)
creditsRemainingnumberRemaining credit balance after this request
bridal.appliedbooleantrue when the bridal train was rendered satisfactorily
bridal.trainScorenumber | nullTrain 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

HTTPErrorCause
400Missing / invalid fieldA required field is missing, the image can’t be fetched, or the image is smaller than 1 KB
401Authentication requiredMissing auth header or invalid API key
402Insufficient creditsNo credits remaining
403ForbiddenKey inactive or domain not authorized
422ai_content_rejectedThe AI engine rejected the content
500AI generation / infra errorAI model or infrastructure error — retry
503bridal_preprocessing_failedWedding-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.