> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wearo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# POST /tryon-api
> Generate a virtual try-on image via the Wearo Direct API.
# 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](#wedding-dress-mode-train-rendering)). 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):**
```json theme={"dark"}
{
"userPhoto": "https://example.com/customer-photo.jpg",
"productImage": "https://mystore.com/products/shirt.jpg"
}
```
**Base64 with data URI prefix:**
```json theme={"dark"}
{
"userPhoto": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
"productImage": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
}
```
**Base64 raw (without prefix):**
```json theme={"dark"}
{
"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**
```bash theme={"dark"}
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
```json theme={"dark"}
{
"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**.
```json theme={"dark"}
{
"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:
```json theme={"dark"}
{
"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 →](/resources/troubleshooting)
## Code examples
See [Code examples →](/api/code-examples) for curl, Node, Python, PHP, and Ruby.