Search docs

Search the TryOnCloud API docs

API-Referenz

Anprobe erstellen

POST /api/v1/generate: Kleidungsstück + Person als Eingabe, fertiges PNG als Ausgabe.

Code-Beispiele, Endpunkte und Fehlercodes sind in jeder Sprache identisch.

POST https://www.tryoncloud.com/api/v1/generate

Senden Sie ein Kleidungsstück und eine Person, und Sie erhalten das fertige Anprobe-Ergebnis als Antwort. Eine Anfrage, ein Bild, keine Abfrage.

Überschriften

KopfzeileWert
X-API-KEYIhr Schlüssel: tk_dev_v1_... (erforderlich)
X-Mocktrue für den kostenlosen Testmodus (optional, entspricht ?mock=true)
Idempotency-KeyOptional. Ihr eigener, eindeutiger Wert pro Anprobe (1 bis 255 druckbare Zeichen). Ein erneuter Versuch mit demselben Schlüssel wird niemals doppelt berechnet. Siehe Wiederholversuche und Idempotenz

Hauptteil

Senden Sie multipart/form-data oder application/json. Es sind zwei Bilder erforderlich.

FeldTypBeschreibung
garment_imageDateiDas Foto des Kleidungsstücks. Oder verwende garment_url oder garment_base64
garment_urlZeichenketteEine öffentliche https-Bild-URL. Wir laden sie serverseitig herunter
garment_base64ZeichenketteBase64-Bild, mit oder ohne das Präfix data:
person_imageDateiDas Foto des Kunden. Oder verwende person_base64
person_base64ZeichenketteBase64-Bild, mit oder ohne das Präfix data:
customer_idZeichenketteOptional. Ihre eigene ID für den Endnutzer, maximal 128 Zeichen. Suchen Sie diese im Dashboard und löschen Sie die Daten des Nutzers über Kundendaten löschen.

Bilder müssen im JPEG-, PNG-, WebP- oder HEIC-Format vorliegen und dürfen jeweils maximal 15 MB groß sein. Es wird der Dateiinhalt überprüft, nicht nur der Name oder der angegebene Dateityp.

Abfrageparameter

ParameterBeschreibung
mock=trueTestmodus: Überprüft alles, generiert nichts, berechnet nichts, speichert nichts. Gibt das Personenbild unverändert zurück.

Antwort

200 OK. Der Textkörper enthält das fertige Bild, Content-Type: image/png, mit einer Größe von etwa 1 Megapixel (die „1K“-Klasse). Lesen Sie es als Bytes ein; analysieren Sie es nicht als JSON.

Antwort-HeaderBedeutung
X-Request-IdEindeutige ID dieser Anfrage, die in jeder Antwort, auch bei Fehlern, enthalten ist. Geben Sie diese bitte im Support an.
X-RateLimit-Limit / X-RateLimit-RemainingIhr Minutenlimit und wie viel davon in der aktuellen Minute noch übrig ist
X-Credit-Was-Free1, wenn bei dieser Anprobe Ihr kostenloses Kontingent verbraucht wurde, 0, wenn gekaufte Credits verbraucht wurden
X-Result-IdNur wenn die Speicherung von Ergebnissen in Ihrem Konto aktiviert ist. Verwenden Sie diese Funktion zusammen mit Ergebnis löschen.
X-Mock1 bei Antworten im Testmodus
X-CostumeNur für Konten, bei denen der Kostüm-Modus aktiviert ist

Fehler werden als JSON-{ "error": "...", "code": "..." } zurückgegeben. Siehe Fehler.

Wiederholungsversuche und Idempotenz

Netzwerke unterbrechen Verbindungen. Um einen sicheren Wiederholungsversuch durchzuführen, senden Sie einen Idempotency-Key-Header mit einem Wert, den Sie pro „Try-on“ generieren (z. B. eine UUID), und verwenden Sie diesen nur für Wiederholungsversuche desselben „Try-on“. Die Schlüssel werden pro API-Schlüssel 24 Stunden lang gespeichert.

Was passiert?Antwort
Erste AnfrageLäuft normal
Erneut versuchen, solange der erste Vorgang noch läuft409 IDEMPOTENCY_IN_PROGRESS mit Retry-After, keine Abbuchung
Versuche es erneut, nachdem es geklappt hat409 IDEMPOTENCY_REPLAY, keine Kosten. Das Bild war in der ersten Antwort enthalten; bei aktivierter Ergebnis-Speicherung wird es durch result_id identifiziert.
Nach einem Fehlversuch erneut versuchenLäuft wieder (der fehlgeschlagene Versuch wurde erstattet)
Gleicher Schlüssel, unterschiedliche Bilder409 IDEMPOTENCY_MISMATCH

Ohne den Header ist jede Anfrage ein neuer Versuch.

Beispiele

mehrteilig (Dateien)

bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -F "garment_image=@shirt.jpg" \
  -F "person_image=@person.jpg" \
  -o result.png

JSON (URL des Kleidungsstücks + Person (Base64))

bash
curl -X POST https://www.tryoncloud.com/api/v1/generate \
  -H "X-API-KEY: $TRYONCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"garment_url\":\"https://cdn.yourstore.com/shirt.jpg\",\"person_base64\":\"$(base64 -w0 person.jpg)\"}" \
  -o result.png

Node.js, ab Version 18

js
import { readFile, writeFile } from "node:fs/promises"

const form = new FormData()
form.append("garment_image", new Blob([await readFile("shirt.jpg")]), "shirt.jpg")
form.append("person_image", new Blob([await readFile("person.jpg")]), "person.jpg")

const res = await fetch("https://www.tryoncloud.com/api/v1/generate", {
  method: "POST",
  headers: { "X-API-KEY": process.env.TRYONCLOUD_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
})
if (!res.ok) {
  const { error, code } = await res.json()
  throw new Error(`${code}: ${error}`)
}
await writeFile("result.png", Buffer.from(await res.arrayBuffer()))

Rechnungsstellung

  • Wenn für den API-Schlüssel ein monatliches Kreditlimit gilt und dieses erreicht ist, wird die Anfrage mit dem Status 402 KEY_LIMIT_REACHED abgelehnt, bis zum 1. des Monats (UTC). Legen Sie die Limits fest, wenn Sie einen Schlüssel auf der Seite API-Schlüssel erstellen.
  • Für jede erfolgreiche Anprobe wird ein Credit abgezogen.
  • Fehlgeschlagene Generierungen (422, 500) werden automatisch erstattet.
  • Der Testmodus ist immer kostenlos.
  • Konten, die Guthaben gekauft haben, verbrauchen das gekaufte Guthaben. Konten, die kein Guthaben gekauft haben, verbrauchen das kostenlose Guthaben.