Search docs

Search the TryOnCloud API docs

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 /generateAsync POST /generationsPOST /batches
ResponseThe PNG, in the same request202 with a job id202 with a batch id
InputsFiles, base64 or garment_urlFiles, base64 or URLsgarment_url and person_url per item
ResultResponse bodyGET /results/:id, kept 7 daysSame, per item
NotificationNone neededPoll, or webhookWebhook per item, plus batch.completed
CreditsFree allowance or purchasedPurchasedPurchased, 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:

FieldDescription
person_urlPublic https URL of the shopper photo (alternative to a file or base64)
customer_idYour id for the end user, up to 128 characters. Used by customer deletion
metadataA JSON object up to 2KB, returned unchanged on the job and in webhooks
webhook_urlPublic https URL to receive generation.completed or generation.failed
bash
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

json
{
  "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:

bash
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.png

A 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:

json
{
  "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/:id returns counts and every item.
  • DELETE /batches/:id cancels items that have not started and refunds them. Running items finish.
  • Each item sends its own webhook, and the batch sends batch.completed once every item has an outcome.

Webhooks

We POST JSON to your webhook_url:

json
{
  "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>:

js
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).

json
{ "object": "customer_deletion", "customer_id": "shopper_123", "results_deleted": 3, "records_cleared": 4 }

Limits

Creating jobs and batchesCounts toward the 300 requests per minute per key limit
Async jobs running at once50 per account (429 TOO_MANY_JOBS); batches are separate
Batch size500 items
ResultsKept 7 days
MetadataJSON object, 2KB