# Asynchrone Aufgaben, Stapelverarbeitung und Webhooks

`POST /generate` ist die einfachste Möglichkeit, eine Anprobe durchzuführen: eine Anfrage, und schon wird das Bild zurückgegeben. Verwenden Sie asynchrone Jobs, wenn Sie keine Verbindung offen halten möchten, und Batches für Katalogarbeiten. Beide nutzen dieselbe Engine, kosten dasselbe und erstatten jede fehlgeschlagene Anprobe.

|  | `POST /generate` (synchron) | `POST /generations` (asynchron) | `POST /batches` |
|---|---|---|---|
| Antwort | Die PNG-Datei, in derselben Anfrage | `202` mit einer Auftrags-ID | `202` mit einer Batch-ID |
| Eingaben | Dateien, Base64 oder `garment_url` | Dateien, Base64 oder URLs | `garment_url` und `person_url` pro Artikel |
| Ergebnis | Antworttext | `GET /results/:id`, wird 7 Tage lang gespeichert | Ebenso, pro Artikel |
| Benachrichtigung | Nicht erforderlich | Poll oder Webhook | Webhook pro Element sowie `batch.completed` |
| Guthaben | Freikontingent oder gekauftes Guthaben | Gekauftes Guthaben | Gekauftes Guthaben, für alle Einträge bei der Erstellung abgebucht |
| Testmodus | `?mock=true` | `?mock=true` | `?mock=true` |

## Einen asynchronen Job starten

`POST https://www.tryoncloud.com/api/v1/generations`

Dieselben Kopfzeilen und Bildfelder wie [bei Generieren](/docs/generate), zusätzlich:

| Feld | Beschreibung |
|---|---|
| `person_url` | Öffentliche `https`-URL des Käuferfotos (Alternative zu einer Datei oder einem Base64-Code) |
| `customer_id` | Ihre ID für den Endbenutzer, maximal 128 Zeichen. Wird beim [Löschen des Kunden](#delete-a-customers-data) verwendet. |
| `metadata` | Ein JSON-Objekt mit einer Größe von bis zu 2 KB, das im Job und in Webhooks unverändert zurückgegeben wird |
| `webhook_url` | Öffentliche `https`-URL zum Empfang von `generation.completed` oder `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 Angenommen**

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

Der Vorgang beginnt, sobald die Antwort gesendet wurde. Ihre Bilder werden im Arbeitsspeicher verarbeitet und niemals gespeichert; nur das fertige Ergebnis wird 7 Tage lang aufbewahrt.

## Eine Stelle prüfen

`GET https://www.tryoncloud.com/api/v1/generations/:id`

`status` wechselt von `queued` → `processing` → `completed` oder `failed`. Ein abgeschlossener Auftrag verfügt über `result_url`; laden Sie ihn mit Ihrem Schlüssel herunter:

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

Ein fehlgeschlagener Auftrag hat den Fehlercode `error.code`: `CONTENT_FILTERED`, `GENERATION_FAILED` oder `INPUT_FETCH_FAILED`. Das Guthaben wird in jedem Fall zurückerstattet.

## Batches

`POST https://www.tryoncloud.com/api/v1/batches` mit einem JSON-Body von bis zu 500 Elementen:

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

- Bei der Erstellung des Batches wird pro Artikel ein Credit abgezogen. Ist Ihr Guthaben zu gering, wird nichts erstellt (Fehlercode `402 NO_CREDITS`).
- `GET /batches/:id` gibt die Anzahl und alle Elemente zurück.
- `DELETE /batches/:id` bricht noch nicht gestartete Aufträge ab und erstattet deren Kosten. Laufende Aufträge werden zu Ende ausgeführt.
- Jedes Element sendet einen eigenen Webhook, und der Batch sendet `batch.completed`, sobald für jedes Element ein Ergebnis vorliegt.

## Webhooks

Wir senden einen `POST`-Request mit JSON-Daten an Ihre `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 }
}
```

Ereignisse: `generation.completed`, `generation.failed`, `batch.completed` und `webhook.test` aus dem Dashboard.

Header: `x-tryoncloud-event`, `x-tryoncloud-delivery-id` (Deduplizierung anhand dieses Feldes), `x-tryoncloud-timestamp` und `x-tryoncloud-signature-v2`.

**Konto-Endpunkt.** Anstatt bei jeder Anfrage die `webhook_url` zu übermitteln, speichern Sie einen Endpunkt im Dashboard (**API-Schlüssel > Webhooks**) und legen Sie fest, welche Ereignisse dieser empfangen soll. Die in der Anfrage angegebene `webhook_url` hat stets Vorrang. **Senden Sie bei Testereignissen** ein signiertes `webhook.test`-Ereignis an den gespeicherten Endpunkt.

**Überprüfen Sie jede Zustellung.** Ihr Signaturschlüssel befindet sich auf derselben Karte (zeigen Sie ihn an, kopieren Sie ihn oder drehen Sie ihn um). Die Signatur ist ein HMAC-SHA256-Hash von `<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))
}
```

Antworten Sie innerhalb von 8 Sekunden mit einem beliebigen `2xx`-Code. Bei anderen Antworten und Zeitüberschreitungen erfolgt ein erneuter Versuch mit Backoff (1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden, 24 Stunden). Webhook-URLs müssen öffentliche `https`-Adressen auf dem Standardport sein; private und interne Adressen werden sowohl beim Speichern der URL als auch beim Versand abgelehnt, und Weiterleitungen werden nicht verfolgt.

## Kundendaten löschen

`DELETE https://www.tryoncloud.com/api/v1/customers/:customer_id`

Löscht alle gespeicherten Ergebnisse für diese `customer_id` in Ihrem Konto und entfernt die ID aus Ihren Datensätzen. Verwenden Sie diese Funktion, wenn ein Endnutzer das Recht auf Vergessenwerden geltend macht (GDPR, DPDP).

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

## Grenzen

|  |  |
|---|---|
| Aufträge und Batches erstellen | Wird auf das Limit von 300 Anfragen pro Minute und Schlüssel angerechnet |
| Gleichzeitig ausgeführte asynchrone Jobs | 50 pro Konto (`429 TOO_MANY_JOBS`); Stapel werden separat behandelt |
| Losgröße | 500 Artikel |
| Ergebnisse | 7 Tage aufbewahrt |
| Metadaten | JSON-Objekt, 2 KB |
