Intégration de l'API Google Virtual Try-On : image de personne et image de vêtement

Placer chaque image dans le bon champ donne un point de départ clair. Mettez la photo de la personne dans person_image_url et l'image du vêtement dans product_image_url ; mettre la photo de la personne dans le champ du vêtement change le sens de l'entrée de la tâche.

TL;DR

Google Virtual Try-On coûte 0,1075 $ par image ; consultez les tarifs et le budget. Utilisez l'endpoint HiAPI /v1/tasks : soumettez une tâche pour obtenir un taskId, puis interrogez le résultat. Aucun prompt n'est nécessaire.

Préparation des entrées et champs

Choisissez une photo de face d'une seule personne, avec une silhouette aussi nette que possible ; pour le vêtement, utilisez une image à plat ou suspendue, sur fond propre et aux bords complets. Les deux URL d'images permanentes de l'exemple ci-dessous correspondent respectivement à la personne A et à un T-shirt à rayures rouges et blanches ; vous pouvez les remplacer par vos propres URL d'images publiques.

Champ	Comment le remplir
person_image_url	Obligatoire ; URL HTTP(S) publique de la photo de la personne
product_image_url	Obligatoire ; URL HTTP(S) publique de l'image du vêtement
num_images	Entier ; indiquez explicitement 1, une seule image est actuellement prise en charge

Mapper les cas d'usage métier à la requête

Pour essayer différents vêtements sur une même personne, fixez person_image_url et remplacez product_image_url à chaque fois ; pour montrer un même vêtement sur différentes personnes, fixez l'image du produit et remplacez l'image de la personne. Pour obtenir plusieurs candidats à partir du même jeu d'images, conservez les deux entrées et soumettez séparément, en indiquant toujours num_images: 1. Il est recommandé d'enregistrer dans vos propres traces de tâches l'identifiant du produit et la version de l'image de la personne ; ne devinez pas la correspondance à partir du seul nom de fichier du résultat.

La personne et le vêtement doivent tous deux être fournis via une URL d'image HTTP(S) lisible publiquement ; les chemins de disque local ou les data URI ne sont pas acceptés comme URL d'image. Le fait qu'une image soit visible dans un navigateur connecté ne signifie pas qu'un autre service peut la lire ; vérifiez le lien sans dépendre d'une session authentifiée avant de soumettre. Vérifiez que le lien renvoie bien l'image elle-même, et non une page d'album ou une page d'erreur de permissions, et assurez-vous que l'image reste accessible pendant la lecture de la tâche.

Si la photo de la personne masque le bas du vêtement ou si les mains chevauchent largement le vêtement, envisagez d'abord une autre photo aux contours plus nets. Pour l'image du vêtement, privilégiez une pièce unique, à plat ou suspendue, aux bords complets, et évitez de reprendre par erreur un rendu de tenue portée comme image produit indépendante. Les champs publics ne proposent pas de réglage de protection locale, d'ajustement des poignets ou de verrouillage des chaussures ; on ne peut pas exprimer ces exigences en ajoutant des champs personnalisés.

Choisir des images nettes relève de la méthode de travail ; il faut vérifier séparément si l'API accepte l'image et si l'expression du produit est exacte. Cet article ne fait aucune promesse de taille de fichier, de limite de pixels ou de dimensions de sortie pour Try-On sans preuve ; il ne faut pas non plus transposer directement les limites d'entrée d'autres modèles d'image.

Soumettre une tâche : cURL

Voici un exemple Bash/cURL. Configurez d'abord HIAPI_API_KEY dans l'environnement d'exécution ; les URL d'images de la requête peuvent être remplacées, et la clé reste dans l'environnement côté serveur.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google-virtual-try-on",
  "input": {
    "person_image_url": "https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp",
    "product_image_url": "https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp",
    "num_images": 1
  }
}'

Une soumission réussie renvoie data.taskId. Enregistrez cette valeur pour les interrogations ultérieures.

Interroger la tâche et enregistrer le résultat

Placez l'identifiant de tâche dans TASK_ID, puis interrogez :

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Lorsque la tâche est en data.status=success, récupérez l'image via data.output[0].url et enregistrez-la. Pour un service en fonctionnement continu, vous pouvez définir callback.url et callback.when: "final" au niveau racine de la requête de soumission afin de recevoir une notification de fin, et dédupliquer par taskId ; le succès comme l'échec peuvent déclencher une notification. L'interrogation convient au débogage et aux vérifications complémentaires.

Interrogation, callback et gestion des délais

Soumettre et interroger sont deux choses distinctes. Après avoir obtenu data.taskId, enregistrez-le avec les entrées de cette requête, puis interrogez GET /v1/tasks/:id. Tant que l'état final n'est pas atteint, continuez d'attendre ; ne remplacez pas l'interrogation par un nouveau POST. L'intervalle d'interrogation et la durée d'attente maximale côté métier sont à définir dans votre application ; cet article ne peut promettre aucun temps moyen ni délai d'achèvement fixe ; les délais réseau de l'exemple ne constituent pas non plus une garantie de durée de service.

Un délai dépassé lors de la requête d'interrogation signifie seulement que cette lecture n'a pas abouti à temps. Conservez l'identifiant de tâche et vérifiez plus tard la même tâche. Si la requête de soumission elle-même expire sans renvoyer d'identifiant, le fait que le serveur l'ait déjà acceptée est incertain : conservez l'heure de soumission et le contenu de la requête, vérifiez d'abord les traces de tâches, puis décidez s'il faut resoumettre. N'interprétez pas directement une anomalie côté client comme un échec de tâche, et ne promettez pas que des requêtes répétées seront automatiquement fusionnées.

La configuration du callback se place au niveau racine du corps de la requête, au même niveau que model et input, et ne doit pas être glissée dans l'entrée du modèle. Lorsque vous configurez callback.url, utilisez aussi callback.when: "final". La notification de fin peut correspondre à un succès ou à un échec ; après réception, vérifiez donc encore l'état. L'interrogation et le callback peuvent concerner la même tâche ; votre système doit dédupliquer par taskId pour éviter les téléchargements ou déclenchements en double. Il s'agit ici de méthodes de traitement applicatif ; rien n'affirme qu'un callback arrive nécessairement dans un délai donné.

Après data.status=success, vérifiez que data.output contient bien une URL de résultat lisible, puis téléchargez l'image. Si l'état renvoyé est fail, conservez le message d'erreur et corrigez la requête en fonction de son contenu ; ne devinez pas, à partir d'un seul état, qu'il s'agit d'une image trop volumineuse, d'une panne réseau ou d'une autre cause précise. En cas d'état inattendu ou d'absence de sortie, conservez la réponse et vérifiez à nouveau ; ne considérez pas un résultat vide comme une livraison réussie.

Il faut aussi distinguer l'échec de téléchargement de l'échec de génération. Si la tâche a réussi mais que le fichier n'a pas été correctement enregistré, relisez ou téléchargez d'abord le résultat existant, plutôt que de refaire directement l'image. Lors de l'archivage, conservez l'identifiant de tâche, la correspondance des entrées et l'emplacement final du fichier, afin de pouvoir retrouver ensuite de quelle requête provient chaque image. Le message « délai d'attente dépassé » affiché à l'utilisateur doit signifier que l'interface actuelle cesse d'attendre, et non annoncer de sa propre initiative que la tâche serveur a été annulée.

Exemple de soumission en Python

L'environnement doit disposer de requests. Ici, timeout=60 est la limite d'attente réseau côté client, et non la durée de génération de l'image.

import os
import requests

payload = {'model': 'google-virtual-try-on', 'input': {'person_image_url': 'https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp', 'product_image_url': 'https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp', 'num_images': 1}}
response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
task_id = result["data"]["taskId"]
print(task_id)

Avant la soumission et vérification du résultat

L'interface ne nécessite pas de prompt. Ne mettez pas 2 ou 4 dans num_images ; si vous voulez des images candidates, lancez des requêtes séparées. Vérifiez d'abord que les deux images sont lisibles publiquement et que les champs ne sont pas intervertis, puis soumettez. En cas d'état d'échec, lisez le message renvoyé et corrigez les entrées ; ne soumettez pas à nouveau à l'identique.

Valider les images renvoyées selon l'usage produit

Comparez d'abord le résultat avec l'image de la personne côte à côte : vérifiez le visage, la coiffure, la posture, l'arrière-plan, ainsi que le pantalon et les chaussures qui ne devraient pas changer. Comparez ensuite avec l'image du vêtement la couleur, l'encolure, la longueur des manches, le motif et le bas du vêtement. Pour un T-shirt à rayures, vérifiez le raccord des rayures horizontales au niveau de la poitrine et des manches ; pour une robe, vérifiez les bretelles, l'encolure drapée et les plis près des mains ; pour une chemise, vérifiez si les poignets sont retroussés et si le bas est rentré dans le pantalon. Ces vérifications découlent des changements visibles dans les cas étudiés ; elles ne garantissent pas que d'autres entrées ne produiront que ces changements.

« Fichier téléchargé » et « image utilisable sur une page produit » doivent être consignés séparément. Même après un retour réussi, des changements hors du vêtement peuvent apparaître ; l'état de l'API ne remplace pas une validation humaine. Si le défaut provient d'un masquage dans l'entrée, changez d'abord l'entrée puis réessayez ; si le produit doit présenter une longueur de manche précise ou un accessoire fixe, jugez d'abord si le résultat actuel respecte cette contrainte, sans ignorer les détails du produit sous prétexte que la tenue globale paraît naturelle.

Lorsque vous ajoutez des candidats pour un même jeu d'entrées, conservez les résultats précédents pour comparaison, sans écraser les anciens fichiers par les nouveaux. Indiquez les raisons d'accepter ou de refuser pour faciliter le traitement ultérieur de produits similaires. Les images ne servent qu'à observer l'apparence ; la taille réelle et le ressenti au port nécessitent encore les dimensions du vêtement et des informations d'essayage sur une personne réelle.

Questions fréquentes

La photo de la personne et l'image du vêtement peuvent-elles partager un seul champ ?

Non. La photo de la personne utilise person_image_url et l'image du vêtement utilise product_image_url.

Faut-il ajouter un paramètre prompt ?

Non. L'interface n'a pas de champ prompt ; l'essayage est déterminé par les deux images d'entrée.

Pourquoi écrire explicitement num_images: 1 ?

Une seule image de résultat est actuellement prise en charge ; l'indiquer explicitement permet de faire correspondre directement le nombre d'images demandées au budget de 0,1075 $ par image.

Peut-on lire l'image dès qu'on a le taskId ?

Il faut encore interroger la tâche ou recevoir la notification ; une fois la tâche en data.status=success, récupérez l'image via data.output[0].url.

Pour aller plus loin

Tarifs et budget · Intégration de l'API · Cas et choix des images · Google Virtual Try-On

Si vous devez choisir entre l'essayage virtuel et une retouche d'image générique, consultez la comparaison entre Google Virtual Try-On et Seedream 5.0 Lite, et vérifiez point par point les vêtements, les chaussures et l'apparence de la personne.