Search docs

Search the TryOnCloud API docs

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

HeaderValue
X-API-KEYYour key, tk_dev_v1_... (required)
X-Mocktrue for free test mode (optional, same as ?mock=true)
Idempotency-KeyOptional. 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.

FieldTypeDescription
garment_imagefileThe garment photo. Or use garment_url or garment_base64
garment_urlstringA public https image URL. We download it server-side
garment_base64stringBase64 image, with or without a data: prefix
person_imagefileThe shopper's photo. Or use person_base64
person_base64stringBase64 image, with or without a data: prefix
customer_idstringOptional. 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

ParameterDescription
mock=trueTest 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 headerMeaning
X-Request-IdUnique id of this request, on every response including errors. Quote it to support
X-RateLimit-Limit / X-RateLimit-RemainingYour per-minute limit and what is left in the current minute
X-Credit-Was-Free1 if this try-on used your free allowance, 0 if it used purchased credits
X-Result-IdOnly when result storage is enabled on your account. Use it with Delete a result
X-Mock1 on test-mode responses
X-CostumeOnly 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 happensResponse
First requestRuns normally
Retry while the first is still running409 IDEMPOTENCY_IN_PROGRESS with Retry-After, nothing charged
Retry after it succeeded409 IDEMPOTENCY_REPLAY, nothing charged. The image was in the first response; with result storage on, result_id identifies it
Retry after it failedRuns again (the failed attempt was refunded)
Same key, different images409 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.