Référence de l'API
Générer un essai virtuel
POST /api/v1/generate : entrée « vêtement + personne », sortie PNG finalisée.
Les exemples de code, les points de terminaison et les codes d'erreur sont identiques dans tous les langages.
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 |
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. |
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. |
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.
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)
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 du vêtement + personne en 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, version 18 et plus
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_REACHEDjusqu'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.