Blog

Tutoriel

Comment utiliser Google Virtual Try-On via l'API HiAPI : guide curl et Python

Nov 10, 2026
Prismes géométriques plats et abstraits, coupés en plans vert sauge et vert pin sur un fond vert profond ; illustration de couverture pour un tutoriel destiné aux développeurs.
Sur cette page

Ce qu'attend le modèle google-virtual-try-on

Avant d'écrire la moindre ligne de code, il est utile de comprendre le contrat d'entrée. Le modèle google-virtual-try-on est une tâche de composition à deux images : il reçoit une image de personne/mannequin et une image de vêtement, puis génère une image de la personne portant ce vêtement.

Cela signifie que votre étape de préparation prend toujours la même forme :

  • Une image de personne, avec un sujet clairement visible et un cadrage raisonnable — les photos en pied ou en buste donnent les meilleurs résultats, car le modèle doit comprendre la géométrie du corps.
  • Une image de vêtement, idéalement sur un fond propre ou uni, montrant l'article que vous souhaitez transférer sur la personne.

Les deux entrées sont fournies sous forme d'URL d'images, et non de données binaires brutes dans le corps de la requête. Cela permet de garder la charge utile légère et de laisser votre propre couche de stockage (S3, GCS, CDN) comme source de vérité. Votre travail consiste donc à vous assurer que chaque URL est publiquement accessible — ou signée avec une durée de validité suffisante — avant de lancer l'appel.

Quelques contraintes pratiques à anticiper :

  • La résolution et le rapport d'aspect influencent la qualité de sortie. Les vignettes minuscules ou les entrées trop recadrées produisent souvent de moins bons résultats.
  • Chaque appel ne traite qu'un seul vêtement. Si votre page produit propose plusieurs coloris, lancez plusieurs appels plutôt que d'essayer d'entasser plusieurs articles dans une seule requête.
  • L'appariement vous incombe. Le modèle ne vérifie pas si le vêtement « convient » à la personne ; il se contente de composer ce que vous fournissez. Un bon appariement (photo en pied avec une robe, photo en buste avec une veste) améliore nettement la sortie.

Considérez cette étape comme le contrat d'actifs : si vous pouvez produire de manière fiable deux URL de qualité pour chaque tâche, le reste de l'intégration n'est qu'une plomberie directe.

Configurer votre requête HiAPI

Tous les appels de modèles HiAPI suivent la même forme, donc une fois que vous en avez un qui fonctionne, les autres ne demandent que de changer les paramètres. Voici ce que nécessite google-virtual-try-on.

Point de terminaison et méthode

La requête est envoyée en POST vers le point de terminaison d'appel de modèle HiAPI de google-virtual-try-on. Vous utilisez la même URL de base et les mêmes identifiants pour tous les modèles, ce qui est la principale raison de passer par HiAPI plutôt que d'intégrer chaque fournisseur séparément.

Authentification

Authentifiez-vous avec votre clé d'API HiAPI dans l'en-tête Authorization, au format standard de jeton bearer :

Authorization: Bearer $HIAPI_API_KEY

Gardez la clé côté serveur. Ne la distribuez jamais dans un bundle navigateur ou une application mobile — passer par votre propre backend est à la fois plus sûr et vous donne un endroit pour ajouter une limitation de débit et de la journalisation.

Type de contenu

Envoyez le corps de la requête en JSON :

Content-Type: application/json

Corps de la requête

Le corps porte votre identifiant de modèle ainsi que les deux URL d'images de la section précédente — l'image de personne et l'image de vêtement — plus tout paramètre optionnel exposé par le modèle. Les noms exacts des paramètres sont ceux documentés à côté du modèle ; copiez-les à la lettre plutôt que de deviner, car une faute de frappe dans un nom de champ se manifeste généralement par une erreur de validation, et non par un message utile.

Enregistrer votre configuration

Placez l'URL de base, l'identifiant de modèle et la clé dans des variables d'environnement, afin que le même script fonctionne en préproduction et en production sans modification :

export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"

C'est tout pour la configuration. Pas de SDK, pas d'intégration fournisseur par fournisseur.

Une requête curl fonctionnelle

Le moyen le plus rapide de vérifier que la clé et la charge utile sont correctes est un simple appel curl. Voici l'anatomie d'une requête vers google-virtual-try-on :

curl -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-virtual-try-on",
    "input": {
      "model_image": "https://your-cdn.example.com/person-001.jpg",
      "garment_image": "https://your-cdn.example.com/jacket-front.jpg"
    }
  }'

Quelques points à noter :

  • Les deux champs d'image se trouvent dans l'objet input, ce qui isole l'espace de noms des paramètres spécifiques au modèle et les sépare des champs de routage.
  • Les URL doivent être accessibles depuis le serveur, et non depuis votre ordinateur portable. Une adresse localhost ou accessible uniquement par VPN échouera.
  • Cet appel ne comporte aucune étape de téléversement de fichier. Si vos actifs ne sont pas encore sur un CDN, téléversez-les d'abord et utilisez l'URL générée.

Lancez-le une fois et inspectez le JSON brut renvoyé avant de construire quoi que ce soit dessus. Faire passer la sortie dans un formateur facilite la lecture :

curl -s -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

Conserver le corps de la requête dans un fichier request.json permet aussi d'éviter les erreurs de guillemets shell lorsque la charge utile grossit.

La même requête en Python

Pour tout ce qui dépasse un test ponctuel, passez à Python. L'exemple ci-dessous n'utilise que la bibliothèque standard plus requests, il peut donc être déposé directement dans un script, une Lambda ou un petit service, sans framework supplémentaire.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")


def try_on(person_url: str, garment_url: str, timeout: int = 120) -> dict:
    payload = {
        "model": "google-virtual-try-on",
        "input": {
            "model_image": person_url,
            "garment_image": garment_url,
        },
    }
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    response = requests.post(
        f"{BASE_URL}/v1/models/google-virtual-try-on",
        json=payload,
        headers=headers,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = try_on(
        "https://your-cdn.example.com/person-001.jpg",
        "https://your-cdn.example.com/jacket-front.jpg",
    )
    print(result)

Notes sur l'adaptation :

  • Définissez un délai d'attente explicite. La génération d'images n'est pas instantanée ; le délai par défaut de requests est trop agressif pour ce type d'appel. Choisissez une valeur confortablement supérieure à votre latence p99.
  • Utilisez json=payload, et non data=json.dumps(payload). Cela définit le type de contenu pour vous et évite les bogues de double encodage.
  • Renvoyez le JSON analysé, et non l'objet réponse, afin que les appelants ne dépendent pas accidentellement des détails internes de HTTP. Si vous avez besoin des codes de statut pour vos métriques, capturez-les avant de renvoyer.
  • Séparez le client du flux de travail. Dans un vrai service, la fonction ci-dessus appartient à un module client léger ; la file d'attente, le stockage et les tentatives se situent au-dessus.

Si vous utilisez déjà httpx ou un framework asynchrone, la conversion est mécanique — la charge utile et les en-têtes sont identiques.

Lire la réponse

La réponse est du JSON. Considérez-la comme une petite enveloppe qui se concentre sur deux choses : la tâche a-t-elle réussi, et où se trouve la sortie ?

Dans les grandes lignes, vous devez vérifier :

  1. Le statut de transport. 2xx signifie que la requête a été acceptée et traitée. 4xx signifie que votre requête est incorrecte ; 5xx signifie qu'un problème est survenu côté serveur. Journalisez le code de statut à chaque appel — c'est l'observation la moins coûteuse que vous puissiez ajouter.
  2. Les champs du corps de réponse. La charge utile porte le résultat généré. Le résultat image est renvoyé sous forme d'URL pointant vers l'actif généré. Le nom exact du champ dépend du schéma de réponse du modèle ; analysez de manière défensive plutôt que de supposer qu'il s'agit d'une simple chaîne.
  3. Les métadonnées. Tout champ d'utilisation ou de durée dans la réponse mérite d'être capturé. La facturation est mesurée par la plateforme, donc persister les métadonnées par requête vous permettra de rapprocher plus tard vos journaux de votre tableau de bord.

Une analyse robuste ressemble à ceci :

data = try_on(person_url, garment_url)
outputs = data.get("output") or {}
image_url = outputs.get("image")
if not image_url:
    raise RuntimeError(f"No image in response: {data}")

Que faire du résultat

L'URL renvoyée est l'actif généré, pas un actif permanent. Ne la transmettez pas directement au frontend pour l'oublier ensuite. À la place :

  • Téléchargez et réhébergez. Récupérez immédiatement les octets et écrivez-les dans votre propre bucket avec une clé adressée par contenu. Cela découple votre produit de la politique de rétention du générateur.
  • Enregistrez la provenance. Stockez les URL d'entrée, l'identifiant de modèle et l'horodatage avec la sortie. Lorsqu'un marchand demandera pourquoi un essayage donné ressemble à cela, vous aurez besoin de reproduire la tâche exacte.
  • Normalisez le format. Redimensionnez et convertissez une fois pour toutes à l'ingestion vers le format standard de la vitrine, plutôt que de le faire à chaque vue de page.

Traiter la réponse comme une passation éphémère — analyser, télécharger, stocker, oublier — est le modèle qui passe à l'échelle.

Modes de défaillance et stratégie de tentatives

Toutes les défaillances ne méritent pas une nouvelle tentative. Réessayer aveuglément transforme un petit hoquet en amont en une file pleine de tâches dupliquées et une facture surprenante.

Classer avant de réessayer

Ne réessayez pas — corrigez la requête :

  • Erreurs de validation de type 400 : JSON mal formé, champs manquants ou mal nommés, corps de requête qui ne correspond pas à la structure attendue par le modèle.
  • 401/403 : clé d'API erronée ou absente, ou clé non autorisée pour ce modèle. Réessayer n'y changera jamais rien.
  • 404 : identifiant de modèle ou chemin de point de terminaison incorrect.
  • URL d'image inaccessibles. Si l'URL de la personne ou du vêtement renvoie 404 ou expire lors de la récupération, la génération ne peut pas continuer. Validez les URL avant de soumettre.

Réessayez avec backoff :

  • 429 : vous êtes limité en débit. Reculez et respectez ce signal.
  • 5xx : erreur transitoire de service ou en amont.
  • Défaillances réseau : réinitialisation de connexion, expiration de lecture.

Tentatives bornées avec gigue

Limitez le nombre de tentatives — trois est un plafond courant — et utilisez un backoff exponentiel avec gigue aléatoire, afin qu'une foule de workers ne réessaie pas en même temps :

import random, time

def with_retry(fn, attempts=3, base=1.0):
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status is not None and 400 <= status < 500 and status != 429:
                raise  # client error: do not retry
            if i == attempts - 1:
                raise
            time.sleep(base * (2 ** i) + random.uniform(0, 0.5))

Mesures de protection en production

  • Idempotence au niveau de la tâche. Hachez la paire d'URL d'entrée comme clé de tâche. Si la même clé est déjà en cours d'exécution ou terminée, renvoyez le résultat stocké plutôt que de soumettre à nouveau.
  • File de messages morts. Après épuisement des tentatives, parquez la tâche et son contexte complet au lieu de la supprimer silencieusement.
  • Disjoncteur. Si le taux d'erreur dépasse un seuil, arrêtez les soumissions pendant une période de refroidissement plutôt que de continuer à marteler un service en difficulté.
  • Alertez selon la forme, pas seulement selon le volume. Un pic de 4xx après un déploiement signifie généralement que quelqu'un a renommé un champ.

Validez les entrées tôt

La plupart des « pannes de modèle » sont en réalité de mauvaises entrées. Effectuez un pré-contrôle peu coûteux : envoyez une requête HEAD sur chaque URL, vérifiez le type de contenu et les dimensions approximatives, et rejetez les actifs manifestement inutilisables avant de dépenser un appel facturé. Cette seule habitude éliminera la majeure partie de votre trafic de tentatives.

L'intégrer dans un vrai pipeline

Un appel curl réussi n'est qu'une démonstration. Une fonctionnalité produit fiable demande un peu plus de structure autour.

Structurer le flux en étapes

Une décomposition viable :

  1. Ingestion. Un marchand ou un utilisateur interne soumet une image de personne et une image de vêtement. Stockez les deux dans votre stockage objet et générez des URL stables et signées.
  2. Validation. Vérifiez l'accessibilité, le format et les dimensions. Rejetez tôt avec un message clair.
  3. Soumission. Appelez google-virtual-try-on via le module client. Enregistrez la clé de tâche, l'identifiant de modèle et les URL d'entrée en base de données.
  4. Matérialisation. En cas de succès, téléchargez l'image générée, convertissez-la vers votre format standard et écrivez-la sur votre CDN avec une clé déterministe.
  5. Publication. Mettez à jour l'enregistrement de la tâche pour pointer vers l'actif que vous hébergez, et faites en sorte que la vitrine ne lise que depuis votre propre stockage.

Chaque étape peut être retentée indépendamment, ce qui rend l'ensemble du système débogable. Si l'étape 4 échoue, vous n'avez pas besoin de relancer la génération.

Garder le client léger

Placez l'appel HTTP dans un petit module et disposez la politique (tentatives, concurrence, délais d'attente, journalisation) autour. Lorsque HiAPI ajoute un paramètre à un modèle, ou que vous voulez tester en A/B différentes routes de génération d'images, vous ne modifiez qu'un seul fichier.

Habitudes opérationnelles à adopter

  • Asynchrone par défaut. La génération prend plusieurs secondes, parfois plus. Soumettez depuis un worker, pas depuis le gestionnaire de requête où l'utilisateur attend.
  • Cachez agressivement. La même paire personne + vêtement ne devrait jamais être générée deux fois. Adressez la sortie par contenu et vérifiez avant de soumettre.
  • Budgétez avec visibilité. Puisque l'utilisation est mesurée par la plateforme, journalisez les métadonnées par requête et rapprochez régulièrement avec votre tableau de bord HiAPI. Détectez les boucles de tentatives incontrôlées en quelques heures plutôt qu'en fin de mois.
  • Versionnez les prompts et les paramètres. Stockez l'objet de paramètres avec chaque tâche afin de pouvoir reproduire les résultats après un changement.
  • Échouez de manière visible pour l'utilisateur. Un indicateur de chargement qui ne disparaît jamais est pire qu'un honnête « nous n'avons pas pu générer ceci, essayez une autre photo ».

Prochaines étapes

La même forme de requête s'applique aux autres modèles d'image HiAPI, donc le client que vous construisez ici servira de modèle pour le reste de votre pipeline. Une fois l'appel à deux images stabilisé, parcourez le catalogue de modèles pour voir ce qui convient à votre flux de travail — l'authentification, la gestion des erreurs et les schémas de stockage s'appliquent tels quels.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API