Comment utiliser l'API wan2.7-image-standard sur hiapi : génération d'images à partir de texte et édition par image de référence

wan2.7-image-standard est la version standard du modèle Wan 2.7 Image de Tongyi Wanxiang. Ce qui justifie une page dédiée : un seul ID de modèle prend en charge à la fois la génération à partir de texte et l'édition d'image à partir d'une image de référence, jusqu'à 2K, facturé à un tarif fixe de 0,0345 $ par image — moins cher que la version Pro compatible 4K. Ce guide fournit une requête directement exécutable, le schéma d'entrée exact (vérifié contre l'API en ligne), le parcours d'édition par image de référence, ainsi que les comportements limites que vous devez gérer en production.

Tout ce qui suit dans les sections schéma et erreurs a été confirmé en interrogeant le point de terminaison /v1/tasks en ligne pendant la rédaction — les listes d'énumérations, les ensembles de champs acceptés et les formes de réponses d'échec proviennent de réponses réelles de l'API, et non de la mémoire.

Ce que vous allez construire et ce qu'il faut préparer

Vous allez soumettre un prompt (éventuellement accompagné d'images de référence), interroger jusqu'à ce que la tâche soit terminée, puis télécharger l'image. Il faut d'abord une chose : obtenir une clé API depuis le démarrage rapide hiapi et l'exporter dans HIAPI_API_KEY. Il n'existe pas de chemin sans clé — chaque requête est authentifiée via Authorization: Bearer sk-<your-key>.

wan2.7-image-standard s'exécute sur l'API de tâches asynchrones de hiapi : vous créez d'abord une tâche avec POST /v1/tasks, puis vous interrogez le point de terminaison de détail jusqu'à ce qu'il signale un état terminal.

Génération à partir de texte : requête minimale

Créer la tâche :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "À l'heure bleue après la pluie, un petit atelier de poterie dans une ruelle calme et déserte, lanternes de papier chaleureuses suspendues, théières émaillées en vitrine, lumières reflétées sur les pavés humides, un vélo appuyé contre un mur, photographie cinématographique 35 mm, très détaillée",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

L'ID de tâche se trouve dans data.taskId de la réponse :

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

Interrogez ensuite GET /v1/tasks/<taskId> jusqu'à ce que data.status soit success, et lisez l'URL de l'image dans data.output[0].url :

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # édition par image de référence (voir section suivante)
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # erreur de validation synchrone (par ex. valeur d'énumération invalide)
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # échec terminal — ne pas continuer à interroger
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # enregistrez immédiatement les octets — voir la note sur l'expiration ci-dessous

aspect_ratio et resolution sont tous deux facultatifs (le modèle a des valeurs par défaut), mais définissez-les explicitement — resolution n'accepte que 1K ou 2K, et les deux sont facturés au même prix, il n'y a donc aucune raison de coût de le laisser à sa valeur par défaut.

Édition à partir d'images de référence : même ID de modèle, plus image_urls

C'est ici que la version standard se distingue de la version Pro. Passez des images de référence dans image_urls (un tableau, jusqu'à 9 images de référence selon les spécifications du modèle) ; le modèle les édite ou les recompose tout en suivant votre prompt textuel :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Placez ce produit sur un plan de travail de cuisine en marbre baigné de soleil, avec des herbes fraîches à côté, lumière douce du matin, photographie de produit lifestyle",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

En Python, il s'agit simplement du paramètre image_urls=[...] transmis à la fonction utilitaire ci-dessus — rien d'autre ne change. Même avec des images de référence, prompt reste obligatoire (l'API rejette les requêtes sans prompt : missing required field "prompt").

Le nom du champ est important : c'est image_urls. Les alternatives plausibles — reference_image_urls, image_input, input_urls — sont toutes rejetées par le schéma avec additional properties '<name>' not allowed. Si vous portez du code depuis le point de terminaison d'édition d'un autre modèle, c'est la première chose à corriger.

Le schéma d'entrée exact

Le schéma est strict : tout champ absent de la liste ci-dessous renvoie 400 INVALID_REQUEST accompagné de additional properties '<name>' not allowed. Voici la totalité des champs qu'il accepte :

Champ	Type	Obligatoire	Description
prompt	string	Oui	Obligatoire pour la génération à partir de texte comme pour l'édition. Accepte l'anglais ou le chinois.
aspect_ratio	string enum	Non	L'une des valeurs : 1:1, 16:9, 4:3, 21:9, 3:4, 9:16, 8:1, 1:8. Toute autre valeur (par exemple 3:2) → 400.
resolution	string enum	Non	Uniquement 1K ou 2K. La 4K n'est pas prise en charge par cette version.
image_urls	string[]	Non	Images de référence pour l'édition (jusqu'à 9). Leur présence bascule en mode référence.
seed	integer	Non	Pour des sorties reproductibles.

Les champs auxquels vous pourriez penser mais que ce modèle n'accepte pas : negative_prompt, n, size et prompt_optimizer sont tous rejetés comme propriétés inconnues. Pas de paramètre de lot (n) — soumettez une tâche par image.

Considérations de production et comportement observé

Un 200 à la soumission ne garantit pas que l'image sera générée. wan2.7-image-standard valide les énumérations de manière synchrone (une resolution ou un aspect_ratio incorrect fait immédiatement échouer le POST avec 400 INVALID_REQUEST), mais il ne valide pas les URL de référence à la soumission. Une entrée image_urls mal formée ou inaccessible est acceptée, renvoie 200 et un taskId, puis la tâche échoue environ une seconde plus tard. Je l'ai vérifié directement : une tâche créée avec une URL de référence invalide renvoie l'état terminal suivant

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

Conséquence pratique : interrogez toujours jusqu'à l'état terminal et traitez la branche data.status == "fail" (lisez data.error). Une tâche échouée se présente comme HTTP 200 avec data.status: "fail" — l'information d'échec se trouve dans data.error, et non dans une erreur HTTP de premier niveau. Assurez-vous que vos URL de référence sont accessibles publiquement avant la soumission.

Téléchargez la sortie immédiatement. data.output[0].url est un lien temporaire avec un horodatage expireAt, pas une ressource CDN permanente. Récupérez les octets dès que la tâche réussit et transférez-les dans votre propre stockage ; une URL expirée renvoie 404. Si vous avez déjà rencontré ce problème, consultez pourquoi votre URL de sortie hiapi renvoie 404 et comment y remédier.

Interrogation vs. callback. L'exemple ci-dessus interroge toutes les cinq secondes, ce qui convient aux scripts et aux petits volumes. Pour un débit de production, ajoutez callback à la requête de création afin que hiapi vous notifie lors de l'événement terminal, au lieu que vous mainteniez une connexion — voir la documentation de création de tâche pour le mécanisme exact.

Version standard vs. Pro : laquelle appeler

hiapi héberge deux versions de Wan 2.7 Image, qui sont des ID de modèle distincts et non des paramètres :

• wan2.7-image-standard (ce guide) — génération à partir de texte et édition par image de référence, 1K/2K, facturé à un tarif fixe de 0,0345 $ par image quelle que soit la résolution.
• wan2.7-image/text-to-image — version Pro : génération à partir de texte uniquement, jusqu'à 4K, tarif fixe de 0,08 $ par image. Voir la page Wan 2.7 Image Pro et le détail sur son utilisation pour générer des images produit e-commerce en 4K.

Choisissez la version standard lorsque vous avez besoin d'édition à partir d'images de référence, ou que la 2K suffit et que vous souhaitez payer moins de la moitié du prix par image de la version Pro. N'utilisez la version Pro que si vous avez spécifiquement besoin d'une sortie 4K native — c'est la seule chose que la version standard ne peut pas faire. Consultez la page des tarifs pour les prix actuels des deux versions.

Questions fréquentes

wan2.7-image-standard prend-il en charge l'édition d'image, ou seulement la génération à partir de texte ? Les deux, à partir du même ID de modèle. Ajoutez le tableau image_urls pour basculer en édition à partir d'images de référence ; omettez-le pour une génération pure à partir de texte.

Quelle est la résolution maximale ? 2K. Le champ resolution n'accepte que 1K et 2K ; l'API en ligne rejette toute autre valeur. Si vous avez besoin de 4K, utilisez la version Pro (wan2.7-image/text-to-image).

Pourquoi ma tâche a-t-elle renvoyé 200 puis échoué ? Les URL de référence ne sont pas vérifiées à la soumission — elles ne le sont qu'à l'exécution. Une entrée image_urls inaccessible ou mal formée crée la tâche (HTTP 200), puis échoue sur un état terminal INVALID_REQUEST. Interrogez data.status et vérifiez que vos URL sont publiques.

Puis-je définir un prompt négatif ? Non. negative_prompt n'est pas un champ accepté par ce modèle (pas plus que n, size ou prompt_optimizer). Guidez plutôt via un prompt positif et seed.