Search docs

Search the TryOnCloud API docs

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êteValeur
X-API-KEYVotre clé, tk_dev_v1_... (obligatoire)
X-Mocktrue pour le mode de test gratuit (facultatif, équivalent à ?mock=true)
Idempotency-KeyFacultatif. 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.

ChampTypeDescription
garment_imagefichierLa photo du vêtement. Vous pouvez également utiliser garment_url ou garment_base64
garment_urlchaîne de caractèresUne URL d'image publique de type https. Nous la téléchargeons côté serveur.
garment_base64chaîne de caractèresImage au format Base64, avec ou sans préfixe data:
person_imagefichierLa photo du client. Ou utilisez person_base64
person_base64chaîne de caractèresImage au format Base64, avec ou sans préfixe data:
customer_idchaîne de caractèresFacultatif. 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ètreDescription
mock=trueMode 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éponseSignification
X-Request-IdIdentifiant 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-RemainingVotre limite par minute et le temps restant dans la minute en cours
X-Credit-Was-Free1 si cet essai a utilisé votre quota gratuit, 0 s'il a utilisé des crédits achetés
X-Result-IdUniquement si la fonction de sauvegarde des résultats est activée sur votre compte. À utiliser avec Supprimer un résultat.
X-Mock1 pour les réponses en mode test
X-CostumeUniquement 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 demandeFonctionne normalement
Réessayer tant que la première opération est encore en cours d'exécution409 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 échecLa commande a été traitée à nouveau (la commande qui avait échoué a été remboursée)
Même clé, images différentes409 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.