Blog

Tutoriel

Comment appeler wan2.7-video en génération de texte vers vidéo via l'API HiAPI : curl et Python

Nov 12, 2026
Image de couverture du blog HiAPI : sur un fond bleu pétrole profond, une forme géométrique de section minérale composée de plans facettés, dans des tons vert cyan et malachite, sans brillance.
Sur cette page

Ce que vous allez construire dans ce tutoriel

À la fin de ce guide, vous disposerez d'un petit pipeline fonctionnel : soumettre une tâche de génération de texte vers vidéo à wan2.7-video/text-to-video via l'API HiAPI — d'abord avec curl, puis en Python — puis attendre que la vidéo soit générée.

Les deux appels sont volontairement équivalents. La version curl est l'implémentation de référence, que vous pouvez coller dans un terminal pour vérifier vos identifiants et votre corps de requête. La version Python encapsule la même requête dans une fonction, facile à intégrer dans un script ou un service, avec interrogation répétée, gestion des erreurs et valeurs par défaut raisonnables.

La génération vidéo étant bien plus lente qu'une complétion de chat, tout le flux est asynchrone : soumettez la tâche, récupérez un identifiant, puis interrogez jusqu'à ce que la tâche rapporte un état terminal. La suite s'articule autour de ce cycle de vie, de sorte que si vous passez plus tard à la génération image vers vidéo ou à un autre modèle vidéo de la même famille d'endpoints, la structure globale reste valable.

Avant d'envoyer la première requête

Trois conditions doivent être remplies pour que le premier appel réussisse.

Identifiants

Vous avez besoin d'une clé API HiAPI, envoyée en tant que bearer token via l'en-tête Authorization. Placez-la dans une variable d'environnement plutôt que dans le code source :

export HIAPI_API_KEY="your-key-here"

L'identifiant de modèle connu

L'identifiant de modèle est une chaîne exacte. Dans ce tutoriel, la valeur est wan2.7-video/text-to-video — suffixe de tâche inclus. Des écritures approximatives comme wan2.7-video ou wan2.7/text-to-video seront rejetées ; copiez donc l'identifiant depuis la liste des modèles, ne le tapez pas de mémoire.

Un prompt à évaluer

Itérer à l'aveugle sur la génération vidéo coûte cher. Rédigez à l'avance un prompt précis (sujet, action, comportement de caméra, éclairage, style), afin que lorsque le résultat revient, vous puissiez juger si ce sont ces réglages qu'il faut ajuster, et non la formulation.

Vous aurez aussi besoin d'un client HTTP et d'un moyen de lire le JSON. Côté shell, curl plus jq ; côté script, Python plus requests.

Analyse de la structure du corps de requête

Une requête de génération de texte vers vidéo est un objet JSON dont les champs se répartissent en trois groupes.

Identité

  • model — l'identifiant exact du modèle, soit wan2.7-video/text-to-video.

Contenu

  • prompt — le texte décrivant la vidéo souhaitée. C'est le champ déterminant ; précisez le mouvement, la composition et le style plutôt que d'empiler les adjectifs.
  • negative_prompt — facultatif. Décrit ce qui ne doit pas apparaître. Utile pour réprimer les défauts courants, mais ne remplace pas un prompt bien rédigé.

Réglages de génération

  • duration — la durée du clip produit.
  • resolution — le palier de taille/résolution de la sortie.
  • seed — facultatif. Fixez-le lorsque vous voulez comparer deux prompts ou deux modifications de réglages à partir d'un point de départ stable.

Un corps minimal ne nécessite que model et prompt ; la plateforme applique des valeurs par défaut aux autres champs. Mais une valeur par défaut n'est pas un choix de votre part — voir la section durée et résolution ci-dessous pour savoir pourquoi il faut les définir explicitement en production.

Gardez le corps plat et peu profond. Ne nicher que les champs appartenant réellement à un sous-objet rend la requête plus lisible et les erreurs de schéma plus faciles à repérer.

Soumettre une tâche avec curl

Voici un exemple complet de soumission. L'endpoint reçoit du JSON et renvoie un identifiant de tâche plutôt que la vidéo elle-même.

curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "prompt": "Travelling avant lent dans une ruelle néon détrempée par la pluie la nuit, flaques réfléchissantes au sol, faible profondeur de champ, étalonnage cinématographique",
    "duration": 5,
    "resolution": "720p"
  }'

Une soumission réussie renvoie un objet contenant l'identifiant de tâche ou de job ainsi qu'un statut. La structure ressemble à ceci :

{
  "id": "job_abc123",
  "status": "queued",
  "model": "wan2.7-video/text-to-video"
}

Deux points à noter. Premièrement, status n'est pas succeeded — rien n'a encore été rendu. Deuxièmement, la réponse ne contient aucune URL de vidéo. Cette URL n'apparaît qu'une fois la tâche dans un état terminal.

Si vous voulez conserver l'identifiant dans la session shell pour l'étape d'interrogation :

JOB_ID=$(curl -s -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq -r '.id')
echo "$JOB_ID"

Déplacer le corps de requête dans payload.json garde la commande courte et facilite l'ajustement du prompt entre plusieurs exécutions.

Soumettre une tâche en Python

La version Python est la même requête, simplement plus agréable à utiliser. Ce qui était un en-tête ou une clé JSON avec curl devient ici un argument nommé.

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "wan2.7-video/text-to-video",
    "prompt": (
        "Travelling avant lent dans une ruelle néon détrempée par la pluie la nuit, "
        "flaques réfléchissantes au sol, faible profondeur de champ, étalonnage cinématographique"
    ),
    "duration": 5,
    "resolution": "720p",
}

resp = requests.post(
    f"{BASE_URL}/v1/video/generations",
    headers=HEADERS,
    json=payload,
    timeout=30,
)
resp.raise_for_status()
job = resp.json()
print(job["id"], job["status"])

La correspondance avec la version shell est univoque :

  • -H "Authorization: ..." → le dictionnaire HEADERS.
  • -d '<json>' → json=payload. Passer un dictionnaire plutôt qu'une chaîne signifie que requests se charge de la sérialisation, ce qui évite d'envoyer du JSON mal formé par erreur.
  • .id extrait avec jq → job["id"].

Deux habitudes propres à Python méritent d'être adoptées dès maintenant. Définissez toujours un timeout pour l'appel de soumission — la requête est petite et devrait revenir vite ; un blocage prolongé signale un problème de connexion, pas de rendu. Et appelez raise_for_status() avant de lire le corps de la réponse, ainsi une défaillance de la couche HTTP donne une trace claire au lieu d'un KeyError déroutant sur job["id"].

Gérer les tâches asynchrones et l'interrogation répétée

L'interrogation répétée est l'étape où la plupart des intégrations deviennent robustes ou instables. Une tâche a un cycle de vie — généralement en file d'attente, en traitement, puis un état terminal de succès ou d'échec — et votre boucle doit gérer ces trois cas.

def wait_for_job(job_id, interval=5, max_attempts=120):
    url = f"{BASE_URL}/v1/video/generations/{job_id}"
    for attempt in range(max_attempts):
        r = requests.get(url, headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "succeeded":
            return data
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"La tâche {job_id} s'est terminée en {status} : {data.get('error')}")
        time.sleep(interval)
    raise TimeoutError(f"La tâche {job_id} n'est toujours pas terminée après {max_attempts} interrogations")

Cette boucle comporte plusieurs choix de conception plus importants qu'il n'y paraît :

Vérifier explicitement les états terminaux. Traiter tout état autre que succeeded comme « continuer d'attendre » signifie qu'une tâche échouée épuisera silencieusement tout votre budget d'interrogation. Faites correspondre les états d'échec et levez une exception.

Choisir l'intervalle d'interrogation consciemment. Le rendu vidéo prend de dizaines de secondes à plusieurs minutes. Interroger toutes les 200 ms ne fait qu'ajouter de la charge sans vous apprendre quoi que ce soit de nouveau. Commencez autour de 5 secondes ; si les tâches durent souvent longtemps, augmentez l'intervalle plutôt que le nombre de tentatives.

Bornez toujours la boucle. Une limite max_attempts transforme un blocage infini en un TimeoutError diagnostiquable. Consignez aussi l'identifiant de tâche — c'est la valeur dont vous aurez besoin pour le dépannage.

Respectez les limites de débit. En cas de soumission par lots, n'envoyez pas toutes les requêtes d'interrogation simultanément. Un interrogateur partagé fonctionnant à intervalle fixe, ou une simple limitation côté client, vous maintient dans les limites.

En cas de succès, la réponse contient l'emplacement de l'asset terminé. Téléchargez-le immédiatement ; ne considérez pas l'enregistrement de la tâche comme un stockage permanent.

Choisir la durée et la résolution

Ces deux réglages influencent la sortie plus que tout autre paramètre, et tous deux affectent la durée d'exécution et le coût. La facturation se fait en secondes de sortie et la résolution détermine le travail par seconde — considérez donc les deux comme des choix délibérés pour votre cas d'usage, et non comme des champs à laisser par défaut.

Durée

Un clip plus long laisse à l'action le temps de se développer, mais chaque seconde supplémentaire implique plus de rendu et un coût plus élevé, et les générations longues souffrent plus facilement de problèmes de cohérence. Conseil pratique :

  • Court (quelques secondes) — boucles pour les réseaux sociaux, visuels produits, B-roll. C'est le moins coûteux à itérer et le plus facile à juger.
  • Moyen — temps narratifs, plans d'ensemble.
  • Long — uniquement lorsque l'histoire l'exige vraiment. Si vous avez besoin d'une vidéo longue, envisagez de générer plusieurs clips courts puis de les monter ; c'est souvent moins cher qu'un long rendu et cela vous donne plus de contrôle.

Lors de l'itération sur le prompt, générez le clip le plus court autorisé par le modèle. Jugez la composition et le mouvement à cette longueur, puis allongez une fois satisfait.

Résolution

Une résolution plus élevée signifie plus de pixels par image, un rendu plus long et un coût plus élevé. Mais sur petit écran, son importance est moindre qu'on ne le croit. Un master 1080p convient à la livraison client ; un brouillon 720p (ou inférieur) convient pour juger si le prompt fonctionne.

Le schéma efficace est un flux de travail en deux étapes : verrouillez le prompt et la durée en basse résolution, puis relancez la tâche finale à la résolution de livraison. N'itérez pas à réglage maximal — vous dépenseriez l'essentiel du budget sur des versions jetées.

Diagnostiquer les erreurs courantes

La plupart des échecs proviennent de l'organisation de la requête, pas du modèle lui-même. Avant de conclure quoi que ce soit sur les capacités du modèle, examinez dans l'ordre les catégories suivantes.

401 / 403 — problèmes d'identifiants

Vérifiez que la clé est définie dans l'environnement réellement visible par le processus (une clé exportée dans un shell n'est pas visible pour un service systemd), que l'en-tête est bien Authorization: Bearer <key>, et qu'il n'y a pas d'espace en fin de variable. Pour le débogage, n'affichez que les premiers caractères de la clé, jamais la clé complète.

404 — chemin ou modèle incorrect

Le chemin de l'endpoint et l'identifiant de modèle sont deux choses distinctes, et les deux doivent être exacts. Vérifiez l'URL sur laquelle vous faites un POST, et assurez-vous que wan2.7-video/text-to-video est copié caractère par caractère depuis la liste des modèles. Une clé valide avec une chaîne de modèle incorrecte renvoie tout de même une erreur de type not-found.

400 — corps de requête mal formé

C'est la catégorie la plus fréquente. Causes courantes : un champ numérique comme duration envoyé comme chaîne "5", un prompt envoyé comme liste plutôt que chaîne, ou un corps accidentellement doublement encodé. La méthode de triage la plus rapide consiste à renvoyer exactement la même commande curl — si l'appel shell réussit et l'appel Python échoue, le problème vient de la façon dont le script construit le dictionnaire, pas de la requête elle-même.

422 / erreurs de validation

Syntaxe valide mais sémantique incorrecte : durée hors plage prise en charge, palier de résolution inconnu, ou champ obligatoire manquant. Lisez le message d'erreur — il indique généralement le champ en cause.

Échec de la tâche après soumission

L'appel de soumission a réussi, mais le rendu n'a pas abouti. Cela peut être un refus pour politique de contenu ou un échec de rendu temporaire. Consignez l'identifiant de tâche et la charge d'erreur ; s'il s'agit d'un problème temporaire, resoumettre la même charge est une première étape raisonnable. Si le même prompt échoue de façon répétée, modifiez la formulation du prompt ou les réglages de génération plutôt que de réessayer indéfiniment la même requête.

L'interrogation ne se termine jamais

Si une tâche reste en traitement bien plus longtemps que des tâches similaires, arrêtez l'interrogation, consignez l'identifiant de tâche et traitez-la comme une tâche échouée. Les cas de longue traîne sont suffisamment rares pour qu'un délai borné avec un message d'erreur explicite soit préférable à une boucle ouverte.

Pour chaque nouveau problème, commencez par l'implémentation de référence en curl : elle écarte votre code du problème et isole ainsi si l'anomalie vient de la requête ou du client.

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