API reference
Async jobs, batches and webhooks
POST /api/v1/generations and /batches, signed webhooks, customer deletion.
POST /generate is the simplest way to run a try-on: one request, the image comes back. Use async jobs when you do not want to hold a connection open, and batches for catalogue work. Both use the same engine, cost the same, and refund every try-on that fails.
Sync POST /generate | Async POST /generations | POST /batches | |
|---|---|---|---|
| Response | The PNG, in the same request | 202 with a job id | 202 with a batch id |
| Inputs | Files, base64 or garment_url | Files, base64 or URLs | garment_url and person_url per item |
| Result | Response body | GET /results/:id, kept 7 days | Same, per item |
| Notification | None needed | Poll, or webhook | Webhook per item, plus batch.completed |
| Credits | Free allowance or purchased | Purchased | Purchased, all items taken up front |
| Test mode | ?mock=true | ?mock=true | ?mock=true |
Start an async job
POST https://www.tryoncloud.com/api/v1/generations
Same headers and image fields as Generate, plus:
| Field | Description |
|---|---|
person_url | Public https URL of the shopper photo (alternative to a file or base64) |
customer_id | Your id for the end user, up to 128 characters. Used by customer deletion |
metadata | A JSON object up to 2KB, returned unchanged on the job and in webhooks |
webhook_url | Public https URL to receive generation.completed or generation.failed |
curl -X POST https://www.tryoncloud.com/api/v1/generations \
-H "X-API-KEY: $TRYONCLOUD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F "garment_image=@shirt.jpg" \
-F "person_image=@person.jpg" \
-F "customer_id=shopper_123" \
-F "webhook_url=https://example.com/hooks/tryoncloud"202 Accepted
{
"id": "6f0e3c1a-0d6a-4f7e-9a7b-2b2a1d3c4e5f",
"object": "generation",
"status": "queued",
"mock": false,
"batch_id": null,
"customer_id": "shopper_123",
"metadata": null,
"result_id": null,
"result_url": null,
"error": null,
"created_at": "2026-11-18T10:00:00.000Z",
"completed_at": null
}The job starts as soon as the response is sent. Your images are processed in memory and never stored; only the finished result is kept, for 7 days.
Check a job
GET https://www.tryoncloud.com/api/v1/generations/:id
status moves queued → processing → completed or failed. A completed job has result_url; download it with your key:
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.pngA failed job has error.code: CONTENT_FILTERED, GENERATION_FAILED or INPUT_FETCH_FAILED. The credit is refunded in every case.
Batches
POST https://www.tryoncloud.com/api/v1/batches with a JSON body of up to 500 items:
{
"items": [
{ "garment_url": "https://cdn.example.com/kurta-1.jpg", "person_url": "https://cdn.example.com/model-a.jpg", "customer_id": "sku-1001" },
{ "garment_url": "https://cdn.example.com/saree-7.jpg", "person_url": "https://cdn.example.com/model-b.jpg" }
],
"webhook_url": "https://example.com/hooks/tryoncloud"
}- One credit per item is taken when the batch is created. If your balance is too low, nothing is created (
402 NO_CREDITS). GET /batches/:idreturns counts and every item.DELETE /batches/:idcancels items that have not started and refunds them. Running items finish.- Each item sends its own webhook, and the batch sends
batch.completedonce every item has an outcome.
Webhooks
We POST JSON to your webhook_url:
{
"event": "generation.completed",
"created_at": "2026-11-18T10:00:21.000Z",
"data": { "id": "6f0e3c1a-...", "object": "generation", "status": "completed", "result_url": "https://www.tryoncloud.com/api/v1/results/...", "customer_id": "shopper_123", "metadata": null }
}Events: generation.completed, generation.failed, batch.completed, and webhook.test from the dashboard.
Headers: x-tryoncloud-event, x-tryoncloud-delivery-id (dedupe on this), x-tryoncloud-timestamp and x-tryoncloud-signature-v2.
Account endpoint. Instead of sending webhook_url with every request, save one endpoint on the dashboard (API Keys > Webhooks) and pick which events it receives. A request's own webhook_url always wins. Send test event posts a signed webhook.test event to the saved endpoint.
Verify every delivery. Your signing secret is on the same card (reveal, copy or rotate it). The signature is HMAC-SHA256 of <timestamp>.<raw body>:
import crypto from "node:crypto"
export function verifyTryOnCloud(rawBody, headers, secret) {
const ts = headers["x-tryoncloud-timestamp"]
const sig = (headers["x-tryoncloud-signature-v2"] || "").replace("sha256=", "")
if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false // reject old deliveries
const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex")
return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
}Reply with any 2xx within 8 seconds. Other responses and timeouts are retried with backoff (1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 24 hours). Webhook URLs must be public https on the standard port; private and internal addresses are refused, both when you save the URL and when we send, and redirects are not followed.
Delete a customer's data
DELETE https://www.tryoncloud.com/api/v1/customers/:customer_id
Deletes every stored result for that customer_id on your account and clears the id from your records. Use it when an end user asks to be forgotten (GDPR, DPDP).
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }Limits
| Creating jobs and batches | Counts toward the 300 requests per minute per key limit |
| Async jobs running at once | 50 per account (429 TOO_MANY_JOBS); batches are separate |
| Batch size | 500 items |
| Results | Kept 7 days |
| Metadata | JSON object, 2KB |