FASHN Try-On v1.6 API : exemples de requêtes curl et Python fonctionnelles

FASHN Try-On v1.6 est un modèle d'essayage virtuel (image-to-image) disponible sur hiapi. Fournissez-lui deux images — une photo de personne et une photo de vêtement — et il renvoie une image composite montrant le vêtement porté. Cet article est un guide pratique fashn try-on api destiné aux développeurs : il contient une véritable requête /v1/tasks que j'ai exécutée de bout en bout, le schéma d'entrée complet vérifié auprès du validateur de paramètres en ligne, ainsi que des détails de production absents du tableau des paramètres.

Page du modèle et démo en ligne : FASHN Try-On v1.6.

1. Ce que vous allez construire + prérequis

Le flux entier suit le schéma standard des tâches asynchrones : un POST pour créer la tâche, puis un polling jusqu'à ce que la tâche atteigne un état terminal, puis le téléchargement de l'image de sortie.

Vous avez besoin de :

• Une clé API (sk-...), disponible dans le guide de démarrage rapide hiapi.
• Deux URL d'images accessibles publiquement : une photo de personne pour model_image, et une photo de vêtement pour garment_image.

2. Exemple minimal fonctionnel

Créer une tâche (curl)

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fashn-tryon-v1.6",
    "input": {
      "model_image": "https://cdn.example.com/person.jpg",
      "garment_image": "https://cdn.example.com/shirt.png"
    }
  }'

Réponse — il s'agit d'une tâche acceptée, et non d'une image finale :

{"code":200,"data":{"taskId":"tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ"},"message":"success"}

model_image et garment_image sont les seuls champs obligatoires ; les autres ont des valeurs par défaut.

Récupérer le résultat par polling (curl)

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01M5D3JTGD12PFF3SFM9JRNPAZ \
  -H "Authorization: Bearer sk-YOUR_KEY"

Une fois la tâche terminée, vous obtenez data.status: "success", et l'image se trouve dans data.output[0].url :

{
  "code": 200,
  "data": {
    "status": "success",
    "model": "fashn-tryon-v1.6",
    "storage": "temp",
    "output": [
      { "type": "image", "url": "https://temp.hiapi.ai/.../...-0.png", "expireAt": 1793119887 }
    ]
  },
  "message": "success"
}

Le champ expireAt est important : la sortie est stockée temporairement (TTL d'environ 7 jours). Téléchargez ou recopiez ces octets immédiatement — ne les liez pas directement en hotlink.

Exécution de bout en bout en Python

import time, requests

API = "https://api.hiapi.ai"
KEY = "sk-YOUR_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def try_on(model_image, garment_image, **opts):
    payload = {
        "model": "fashn-tryon-v1.6",
        "input": {"model_image": model_image, "garment_image": garment_image, **opts},
    }
    r = requests.post(f"{API}/v1/tasks", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]

    while True:                     # poll until terminal
        time.sleep(3)
        d = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        if d.get("status") == "success":
            return d["output"][0]["url"]
        if d.get("status") in ("fail", "error"):
            raise RuntimeError(f"task failed: {d}")

url = try_on(
    "https://cdn.example.com/person.jpg",
    "https://cdn.example.com/shirt.png",
    category="tops", mode="quality",
)
print(url)

3. Schéma d'entrée (vérifié auprès du validateur en ligne)

fashn-tryon-v1.6 utilise un schéma fermé — tout champ non listé ci-dessous est rejeté, vous ne pouvez donc pas glisser d'autres paramètres natifs FASHN que hiapi n'expose pas.

Champ	Obligatoire	Type	Valeurs acceptées
model_image	Oui	string (URL)	Photo de personne
garment_image	Oui	string (URL)	Photo de vêtement
category	Non	enum	tops, bottoms, one-pieces, auto
mode	Non	enum	performance, balanced, quality
garment_photo_type	Non	enum	auto, model, flat-lay
output_format	Non	enum	png, jpeg
seed	Non	integer	Pour la reproductibilité
segmentation_free	Non	boolean	—

Comment je l'ai confirmé : envoyer {"model":"fashn-tryon-v1.6","input":{}} renvoie

invalid input: model_image: missing required field "model_image"; garment_image: missing required field "garment_image"

Chaque valeur d'énumération ci-dessus a été confirmée en envoyant une valeur invalide, par exemple mode: value must be one of 'performance', 'balanced', 'quality'. Passer num_samples, num_images ou tout champ hors du tableau renvoie additional properties '...' not allowed — il n'y a aucune option multi-échantillons. Une requête renvoie une image ; pour obtenir des résultats différents, modifiez seed entre plusieurs appels.

4. Pratiques de production

• La validation a lieu avant la facturation. Une entrée invalide renvoie un HTTP 400 avec le corps {"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}, et aucune tâche n'est créée — une requête mal formée ne génère pas de frais. Une requête valide renvoie code:200 accompagné d'un taskId.
• Réinterrogez plutôt que de resoumettre. Chaque POST /v1/tasks crée une nouvelle tâche (facturable). Si une requête de polling expire, continuez d'interroger le taskId que vous avez déjà ; une réponse perdue ne signifie pas que la tâche a échoué.
• Préférez les callbacks au polling. Pour les scénarios par lots, vous pouvez enregistrer un callback afin que hiapi vous notifie lorsque la tâche atteint son état final, sans avoir à interroger vous-même — voir les champs concernés dans la documentation de référence de l'API asynchrone unifiée. Les exemples ci-dessus utilisent le polling.

5. Déroulement d'une exécution réelle

J'ai exécuté la requête minimale ci-dessus — une photo de personne en 768×1152 et une image de vêtement en 768×1152, en omettant mode et category :

• Latence : environ 13 secondes entre created et completed sur l'objet tâche.
• Sortie : un seul PNG, de dimensions 768×1152, soit une image au format portrait. La page du modèle indique que la taille de sortie suit la photo de personne (ses exécutions validées mesurent 972×1296 et 768×1152), ce qui concorde avec cette exécution — il n'y a pas de champs width/height/aspect_ratio, donc les dimensions de la photo de personne déterminent celles de la sortie.
• Parcours des états : le polling affiche d'abord archiving, puis passe à success ; storage vaut temp.
• Les valeurs par défaut fonctionnent réellement. Omettre mode et category réussit quand même, donc ces deux URL d'images sont bien les seules entrées indispensables — le modèle identifie automatiquement le type de vêtement.

La facturation est calculée sur le nombre d'images de sortie et ne varie pas selon le mode choisi ; consultez la page de tarification pour les tarifs actuels.

Liens utiles

• Page du modèle FASHN Try-On v1.6 et démo en ligne
• Documentation de référence de l'API asynchrone unifiée (tâches)
• Guide de démarrage rapide — obtenir une clé API
• Tarification

FAQ

Quels champs sont obligatoires ? Uniquement model_image et garment_image, tous deux devant être des URL accessibles publiquement.

Peut-on générer plusieurs variantes en un seul appel ? Non — num_samples et num_images sont rejetés par le schéma. Une requête renvoie une image ; modifiez seed entre plusieurs appels pour obtenir des résultats différents.

Comment contrôler la taille de sortie ? Vous ne pouvez pas la définir directement. Le résultat suit les dimensions de la photo de personne — mon entrée en 768×1152 a produit une sortie en 768×1152.

Quelle est la durée de validité de l'URL du résultat ? La sortie est stockée temporairement avec un expireAt (environ 7 jours). Téléchargez ces octets immédiatement.

Le mode qualité change-t-il le prix ? Non — que ce soit performance, balanced ou quality, la facturation se fait sur le nombre d'images de sortie.