# Anprobe erstellen

`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](#retries-and-idempotency) |

## 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.](/docs/async#delete-a-customers-data) |

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.](/docs/delete-result) |
| `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](/docs/errors).

## 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)

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