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
| Kopfzeile | Wert |
|---|---|
X-API-KEY | Ihr Schlüssel: tk_dev_v1_... (erforderlich) |
X-Mock | true für den kostenlosen Testmodus (optional, entspricht ?mock=true) |
Idempotency-Key | Optional. 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.
| Feld | Typ | Beschreibung |
|---|---|---|
garment_image | Datei | Das Foto des Kleidungsstücks. Oder verwende garment_url oder garment_base64 |
garment_url | Zeichenkette | Eine öffentliche https-Bild-URL. Wir laden sie serverseitig herunter |
garment_base64 | Zeichenkette | Base64-Bild, mit oder ohne das Präfix data: |
person_image | Datei | Das Foto des Kunden. Oder verwende person_base64 |
person_base64 | Zeichenkette | Base64-Bild, mit oder ohne das Präfix data: |
customer_id | Zeichenkette | Optional. 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
| Parameter | Beschreibung |
|---|---|
mock=true | Testmodus: Ü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-Header | Bedeutung |
|---|---|
X-Request-Id | Eindeutige ID dieser Anfrage, die in jeder Antwort, auch bei Fehlern, enthalten ist. Geben Sie diese bitte im Support an. |
X-RateLimit-Limit / X-RateLimit-Remaining | Ihr Minutenlimit und wie viel davon in der aktuellen Minute noch übrig ist |
X-Credit-Was-Free | 1, wenn bei dieser Anprobe Ihr kostenloses Kontingent verbraucht wurde, 0, wenn gekaufte Credits verbraucht wurden |
X-Result-Id | Nur wenn die Speicherung von Ergebnissen in Ihrem Konto aktiviert ist. Verwenden Sie diese Funktion zusammen mit Ergebnis löschen. |
X-Mock | 1 bei Antworten im Testmodus |
X-Costume | Nur 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 Anfrage | Läuft normal |
| Erneut versuchen, solange der erste Vorgang noch läuft | 409 IDEMPOTENCY_IN_PROGRESS mit Retry-After, keine Abbuchung |
| Versuche es erneut, nachdem es geklappt hat | 409 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 versuchen | Läuft wieder (der fehlgeschlagene Versuch wurde erstattet) |
| Gleicher Schlüssel, unterschiedliche Bilder | 409 IDEMPOTENCY_MISMATCH |
Ohne den Header ist jede Anfrage ein neuer Versuch.
Beispiele
mehrteilig (Dateien)
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.pngJSON (URL des Kleidungsstücks + Person (Base64))
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.pngNode.js, ab Version 18
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_REACHEDabgelehnt, 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.