API-Referenz
Asynchrone Aufgaben, Stapelverarbeitung und Webhooks
POST /api/v1/generations und /batches, signierte Webhooks, Löschen von Kunden.
Code-Beispiele, Endpunkte und Fehlercodes sind in jeder Sprache identisch.
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, 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 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 |
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
{
"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:
curl https://www.tryoncloud.com/api/v1/results/RESULT_ID -H "X-API-KEY: $TRYONCLOUD_API_KEY" -o result.pngEin 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:
{
"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/:idgibt die Anzahl und alle Elemente zurück.DELETE /batches/:idbricht 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:
{
"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>:
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).
{ "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 |