# Générer un essai virtuel

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

Envoyez un vêtement et une personne, et recevez en retour une photo du modèle en train de l'essayer. Une seule demande, une seule image, pas de sondage.

## En-têtes

| En-tête | Valeur |
|---|---|
| `X-API-KEY` | Votre clé, `tk_dev_v1_...` (obligatoire) |
| `X-Mock` | `true` pour le mode de test gratuit (facultatif, équivalent à `?mock=true`) |
| `Idempotency-Key` | Facultatif. Une valeur unique que vous définissez pour chaque essai (1 à 255 caractères imprimables). Une nouvelle tentative avec la même clé n’est jamais facturée deux fois. Voir [Nouvelles tentatives et idempotence](#retries-and-idempotency) |

## Corps

Envoyez `multipart/form-data` **ou** `application/json`. Deux images sont obligatoires.

| Champ | Type | Description |
|---|---|---|
| `garment_image` | fichier | La photo du vêtement. Vous pouvez également utiliser `garment_url` ou `garment_base64` |
| `garment_url` | chaîne de caractères | Une URL d'image publique de type `https`. Nous la téléchargeons côté serveur. |
| `garment_base64` | chaîne de caractères | Image au format Base64, avec ou sans préfixe `data:` |
| `person_image` | fichier | La photo du client. Ou utilisez `person_base64` |
| `person_base64` | chaîne de caractères | Image au format Base64, avec ou sans préfixe `data:` |
| `customer_id` | chaîne de caractères | Facultatif. Identifiant que vous attribuez à l'utilisateur final, comprenant jusqu'à 128 caractères. Recherchez-le dans le tableau de bord, puis effacez ses données à l'aide de la fonction [Supprimer les données d'un client.](/docs/async#delete-a-customers-data) |

Les images doivent être au format JPEG, PNG, WebP ou HEIC, avec une taille maximale de 15 Mo chacune. C'est le contenu du fichier qui est vérifié, et pas seulement son nom ou le type déclaré.

### Paramètres de requête

| Paramètre | Description |
|---|---|
| `mock=true` | Mode test : valide tout, ne génère rien, ne facture rien, ne stocke rien. Renvoie l'image de la personne telle quelle. |

## Réponse

**200 OK.** Le corps du message **correspond à** l'image finale, `Content-Type: image/png`, d'environ 1 mégapixel (catégorie « 1K »). Lisez-la en octets ; ne l'analysez pas au format JSON.

| En-tête de réponse | Signification |
|---|---|
| `X-Request-Id` | Identifiant unique de cette requête, présent dans chaque réponse, y compris en cas d'erreur. Veuillez le mentionner lorsque vous contactez le service d'assistance. |
| `X-RateLimit-Limit` / `X-RateLimit-Remaining` | Votre limite par minute et le temps restant dans la minute en cours |
| `X-Credit-Was-Free` | `1` si cet essai a utilisé votre quota gratuit, `0` s'il a utilisé des crédits achetés |
| `X-Result-Id` | Uniquement si la fonction de sauvegarde des résultats est activée sur votre compte. À utiliser avec [Supprimer un résultat.](/docs/delete-result) |
| `X-Mock` | `1` pour les réponses en mode test |
| `X-Costume` | Uniquement pour les comptes sur lesquels le mode « costume » est activé |

Les erreurs renvoient un objet JSON de type `{ "error": "...", "code": "..." }`. Voir la section [Erreurs](/docs/errors).

## Nouvelles tentatives et idempotence

Les réseaux peuvent interrompre les connexions. Pour effectuer une nouvelle tentative en toute sécurité, envoyez un en-tête `Idempotency-Key` avec une valeur que vous générez à chaque tentative (par exemple un UUID) et ne réutilisez-la que pour les nouvelles tentatives liées à cette même opération. Les clés sont conservées pendant 24 heures par clé API.

| Que se passe-t-il ? | Réponse |
|---|---|
| Première demande | Fonctionne normalement |
| Réessayer tant que la première opération est encore en cours d'exécution | `409 IDEMPOTENCY_IN_PROGRESS` avec `Retry-After`, aucun prélèvement effectué |
| Réessayer une fois que cela a fonctionné | `409 IDEMPOTENCY_REPLAY`, rien n'a été facturé. L'image figurait dans la première réponse ; lorsque la fonction de stockage des résultats est activée, l'`result_id` permet de l'identifier |
| Réessayer après un échec | La commande a été traitée à nouveau (la commande qui avait échoué a été remboursée) |
| Même clé, images différentes | `409 IDEMPOTENCY_MISMATCH` |

Sans cet en-tête, chaque requête correspond à un nouvel essai.

## Exemples

### en plusieurs parties (fichiers)

```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 du vêtement + personne en 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, version 18 et plus

```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()))
```

## Facturation

- Si la clé API dispose d'une limite de crédit mensuelle et que celle-ci est atteinte, la requête est refusée avec le code d'erreur `402 KEY_LIMIT_REACHED` jusqu'au 1er du mois (UTC). Définissez ces limites lors de la création d'une clé sur la page **Clés API**.

- Chaque essai réussi coûte **un crédit**.
- Les générations ayant échoué (`422`, `500`) sont automatiquement remboursées.
- Le mode d'essai est toujours gratuit.
- Les comptes ayant acheté des crédits utilisent les crédits achetés. Les comptes n'ayant pas utilisé leur quota gratuit.
