# Async jobs, batches and webhooks

`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](/docs/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](#delete-a-customers-data) |
| `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` |

```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 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 |
