Search docs

Search the TryOnCloud API docs

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
AntwortDie PNG-Datei, in derselben Anfrage202 mit einer Auftrags-ID202 mit einer Batch-ID
EingabenDateien, Base64 oder garment_urlDateien, Base64 oder URLsgarment_url und person_url pro Artikel
ErgebnisAntworttextGET /results/:id, wird 7 Tage lang gespeichertEbenso, pro Artikel
BenachrichtigungNicht erforderlichPoll oder WebhookWebhook pro Element sowie batch.completed
GuthabenFreikontingent oder gekauftes GuthabenGekauftes GuthabenGekauftes 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:

FeldBeschreibung
person_urlÖffentliche https-URL des Käuferfotos (Alternative zu einer Datei oder einem Base64-Code)
customer_idIhre ID für den Endbenutzer, maximal 128 Zeichen. Wird beim Löschen des Kunden verwendet.
metadataEin 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 erstellenWird auf das Limit von 300 Anfragen pro Minute und Schlüssel angerechnet
Gleichzeitig ausgeführte asynchrone Jobs50 pro Konto (429 TOO_MANY_JOBS); Stapel werden separat behandelt
Losgröße500 Artikel
Ergebnisse7 Tage aufbewahrt
MetadatenJSON-Objekt, 2 KB