# Generate a try-on

`POST https://www.tryoncloud.com/api/v1/generate`

Send a garment and a person, get the finished try-on back as the response body. One request, one image, no polling.

## Headers

| Header | Value |
|---|---|
| `X-API-KEY` | Your key, `tk_dev_v1_...` (required) |
| `X-Mock` | `true` for free test mode (optional, same as `?mock=true`) |
| `Idempotency-Key` | Optional. Your own unique value per try-on (1 to 255 printable characters). A retry with the same key is never charged twice. See [Retries and idempotency](#retries-and-idempotency) |

## Body

Send `multipart/form-data` **or** `application/json`. Two images are required.

| Field | Type | Description |
|---|---|---|
| `garment_image` | file | The garment photo. Or use `garment_url` or `garment_base64` |
| `garment_url` | string | A public `https` image URL. We download it server-side |
| `garment_base64` | string | Base64 image, with or without a `data:` prefix |
| `person_image` | file | The shopper's photo. Or use `person_base64` |
| `person_base64` | string | Base64 image, with or without a `data:` prefix |
| `customer_id` | string | Optional. Your own id for the end user, up to 128 characters. Search it in the dashboard, and erase their data with [Delete a customer's data](/docs/async#delete-a-customers-data) |

Images must be JPEG, PNG, WebP or HEIC, up to 15MB each. The file contents are checked, not just the name or declared type.

### Query parameters

| Parameter | Description |
|---|---|
| `mock=true` | Test mode: validates everything, generates nothing, charges nothing, stores nothing. Returns the person image unchanged |

## Response

**200 OK.** The body **is** the finished image, `Content-Type: image/png`, about 1 megapixel (the "1K" class). Read it as bytes; do not parse it as JSON.

| Response header | Meaning |
|---|---|
| `X-Request-Id` | Unique id of this request, on every response including errors. Quote it to support |
| `X-RateLimit-Limit` / `X-RateLimit-Remaining` | Your per-minute limit and what is left in the current minute |
| `X-Credit-Was-Free` | `1` if this try-on used your free allowance, `0` if it used purchased credits |
| `X-Result-Id` | Only when result storage is enabled on your account. Use it with [Delete a result](/docs/delete-result) |
| `X-Mock` | `1` on test-mode responses |
| `X-Costume` | Only for accounts with costume mode enabled |

Errors return JSON `{ "error": "...", "code": "..." }`. See [Errors](/docs/errors).

## Retries and idempotency

Networks drop connections. To retry safely, send an `Idempotency-Key` header with a value you generate per try-on (for example a UUID) and reuse it only for retries of that same try-on. Keys are kept for 24 hours per API key.

| What happens | Response |
|---|---|
| First request | Runs normally |
| Retry while the first is still running | `409 IDEMPOTENCY_IN_PROGRESS` with `Retry-After`, nothing charged |
| Retry after it succeeded | `409 IDEMPOTENCY_REPLAY`, nothing charged. The image was in the first response; with result storage on, `result_id` identifies it |
| Retry after it failed | Runs again (the failed attempt was refunded) |
| Same key, different images | `409 IDEMPOTENCY_MISMATCH` |

Without the header, every request is a new try-on.

## Examples

### multipart (files)

```bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -F "garment_image=@shirt.jpg" \
  -F "person_image=@person.jpg" \
  -o result.png
```

### JSON (garment URL + person base64)

```bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"garment_url\":\"https://cdn.yourstore.com/shirt.jpg\",\"person_base64\":\"$(base64 -w0 person.jpg)\"}" \
  -o result.png
```

### Node.js 18+

```js
import { readFile, writeFile } from "node:fs/promises"

const form = new FormData()
form.append("garment_image", new Blob([await readFile("shirt.jpg")]), "shirt.jpg")
form.append("person_image", new Blob([await readFile("person.jpg")]), "person.jpg")

const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
  method: "POST",
  headers: { "X-API-KEY": process.env.TRYONCLOUD_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
})
if (!res.ok) {
  const { error, code } = await res.json()
  throw new Error(`${code}: ${error}`)
}
await writeFile("result.png", Buffer.from(await res.arrayBuffer()))
```

## Billing

- If the API key has a monthly credit limit and it is reached, the request is refused with `402 KEY_LIMIT_REACHED` until the 1st (UTC). Set limits when you create a key on the **API Keys** page.

- One successful try-on uses **one credit**.
- Failed generations (`422`, `500`) are refunded automatically.
- Test mode is always free.
- Accounts that have bought credits spend purchased credits. Accounts that have not spend the free allowance.
