API reference
Generate a try-on
POST /api/v1/generate: garment + person in, finished PNG out.
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 |
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 |
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 |
X-Mock | 1 on test-mode responses |
X-Costume | Only for accounts with costume mode enabled |
Errors return JSON { "error": "...", "code": "..." }. See 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)
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.pngJSON (garment URL + person base64)
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.pngNode.js 18+
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_REACHEDuntil 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.