Appeler le modèle wan2.7-video/text-to-video via l'API HiAPI : un workflow pratique pour les vidéos courtes

Pourquoi la génération de vidéo à partir de texte doit s'intégrer dans un pipeline, et non être un appel unique

L'erreur la plus courante avec un modèle de génération de vidéo à partir de texte est de le considérer comme un générateur d'images animées : on saisit un prompt, on obtient une vidéo finie. Une vidéo courte fonctionne rarement ainsi. Un clip de quinze secondes qui fonctionne bien est généralement le résultat de plusieurs clips générés, d'une passe de sélection et d'un montage, et non d'un rendu chanceux.

Un modèle mental plus utile consiste à considérer le modèle comme un générateur de clips au sein d'un pipeline. Ce pipeline se présente approximativement ainsi :

1. Saisie du prompt — vous écrivez un prompt décrivant un instant clair : le sujet, l'action, la scène, et comment la caméra se déplace.
2. Génération du clip — le modèle wan2.7-video/text-to-video génère un court clip à partir de ce prompt.
3. Sélection — vous examinez les clips générés et conservez ceux qui tiennent debout en eux-mêmes.
4. Montage — les clips conservés sont assemblés, découpés et organisés pour former l'œuvre vidéo courte finale.

Cette perspective a deux conséquences. Premièrement, chaque clip généré doit pouvoir tenir seul : si un segment n'a de sens qu'en tant que partie d'une séquence plus longue, il est difficile à sélectionner et à réordonner. Deuxièmement, le prompt devient la variable principale du workflow, et non le code d'intégration. Vous écrivez la requête une fois, puis vous changez plusieurs fois le texte du prompt.

C'est aussi l'avantage d'adopter dès le départ une approche en pipeline. Si vous concevez votre premier appel comme un rendu unique, il faudra tout réécrire pour intégrer la sélection ou le montage. Si vous le concevez dès le début comme un générateur de clips, le reste du workflow se développera naturellement autour de lui.

Ce que couvre cet article

Nous allons délimiter ce que ce modèle peut faire dans une stack basée sur HiAPI, comment organiser les prompts autour d'un clip utilisable, comment formuler le langage de caméra et de mouvement, une écriture de requête fonctionnelle, et comment, par une boucle d'itération, transformer un appel exploitable en processus reproductible.

Ce que fait le modèle wan2.7-video/text-to-video dans votre stack

Le modèle wan2.7-video/text-to-video reçoit un prompt textuel et renvoie un clip vidéo généré. C'est ce contrat dont votre pipeline doit dépendre : entrée textuelle, sortie de clip.

Dans une stack basée sur HiAPI, le modèle se situe derrière une interface API unifiée unique. Votre application ne communique pas directement avec le modèle — elle envoie une requête à HiAPI, qui gère l'appel au modèle et renvoie la ressource du clip généré. Cela a plusieurs implications pratiques pour délimiter votre intégration :

• Une intégration, plusieurs itérations. Quand le prompt change, l'interface API reste stable. La requête n'est à construire qu'une seule fois.
• Le modèle est une unité réutilisable. Le texte du prompt est la variable que vous ajustez ; la structure de l'appel est la constante.
• Tout ce qui entoure l'appel relève de votre stack. Le téléversement, le stockage, la logique de sélection, le montage et la publication sont de votre responsabilité — le modèle ne fait que générer le clip.

Ce qui doit rester hors périmètre

Veillez à ne pas spéculer sur des détails précis que le modèle ne garantit pas. Ne codez pas en dur dans la logique du pipeline des hypothèses sur la fréquence d'images, les préréglages de résolution, la durée maximale d'un clip ou le comportement temporel exact, sur la base de suppositions. Considérez plutôt le clip renvoyé comme une ressource opaque : lisez ses métadonnées dans la réponse, validez-les, et laissez l'étape de montage s'adapter à la durée réelle de chaque clip.

Cette discipline est particulièrement importante pour le travail sur les vidéos courtes. Une sortie vidéo courte est assemblée à partir de plusieurs clips, et un pipeline qui s'adapte à la durée réelle des clips est bien plus robuste qu'un pipeline qui suppose une longueur de clip fixe.

Répartition des rôles

La répartition claire est la suivante :

• Côté modèle : interprétation du prompt, mouvement et génération du clip vidéo.
• Côté HiAPI : accès authentifié au modèle via une API unifiée.
• Votre côté : conception des prompts, traitement des requêtes, validation des réponses, stockage des clips, sélection, montage et livraison.

Une fois cette frontière tenue, le reste du workflow — structure des prompts, formulation de la caméra, itération — se met en place.

Organiser les prompts pour les clips de vidéos courtes

Comme chaque clip doit pouvoir être utilisé seul, chaque prompt doit décrire un instant unique et autonome. La méthode fiable consiste à construire le prompt avec des modules explicites, plutôt qu'à écrire un long paragraphe et à espérer.

Les quatre modules

Une structure exploitable est sujet, action, scène, style :

• Sujet — qui ou quoi apparaît à l'image. Soyez précis : « un cycliste en imperméable rouge » est meilleur que « une personne ».
• Action — la chose unique que fait le sujet dans le clip. Gardez une action unique et continue.
• Scène — où cela se passe, y compris la lumière et la météo si c'est important.
• Style — le traitement visuel : réaliste, animation, caméra à l'épaule granuleuse, cinématographique, etc.

Par exemple, un prompt structuré par modules : un cycliste en imperméable rouge, roulant régulièrement au crépuscule dans des rues urbaines humides, reflets néon dans les flaques, rendu réaliste caméra à l'épaule.

Une seule action par clip

Un clip court n'a pas la place pour un arc narratif. Si vous décrivez un sujet qui entre, s'assoit, commande un café puis repart, le modèle devra compresser ou abandonner une partie de ces éléments, avec un résultat imprévisible. Séparez : un clip pour l'entrée, un pour s'asseoir, un pour le comptoir. Chaque clip est sélectionnable, réordonnable, découpable au montage — et si l'un échoue, il est facile à régénérer individuellement.

Recombiner les modules pour générer des variantes

Traiter les modules comme des champs indépendants offre une méthode peu coûteuse pour générer des variantes. Fixez le sujet et la scène, faites varier l'action. Fixez l'action, changez le style. Cela produit des groupes de clips apparentés qui se montent bien ensemble, exactement ce dont le montage de vidéos courtes a besoin. Vous pouvez générer ces variantes en boucle à partir de petites structures de données dans le code, au lieu d'écrire chaque prompt à la main.

Garder les prompts concis

Chaque clause supplémentaire dans un prompt se dispute l'influence. Si un détail ne change pas ce qui apparaît à l'image dans ce clip, supprimez-le. Un prompt ciblé avec quatre modules clairs vaut généralement mieux qu'une longue description atmosphérique empilant cinq idées.

Écrire des formulations de caméra et de mouvement réellement lisibles

Des verbes de mouvement vagues produisent des mouvements vagues. Si votre prompt dit « mouvement dynamique de la scène » ou « un plan palpitant », le modèle ne reçoit aucune instruction spatiale et ne peut qu'improviser — et un comportement de caméra improvisé est la cause la plus fréquente de rejet d'un clip à l'étape de sélection.

Décrire le comportement de la caméra de façon littérale

Décrivez la caméra avec la précision d'une instruction donnée à un cadreur. Les formulations utiles incluent :

• « la caméra avance lentement vers le sujet »
• « la caméra fait un panoramique vers la gauche en suivant le sujet »
• « un plan fixe verrouillé »
• « la caméra s'élève de la hauteur du sol à la hauteur des yeux »
• « un lent mouvement orbital autour du sujet »

Ces formulations précisent à la fois la direction et l'amplitude (lentement, verrouillé, s'élevant), ce qui les rend lisibles. En comparaison, « caméra dynamique » ne précise ni l'une ni l'autre.

Séparer le mouvement du sujet du mouvement de la caméra

Ce sont deux instructions différentes, et elles doivent être écrites en deux phrases distinctes. Le sujet fait quelque chose ; la caméra fait quelque chose ; les deux se décrivent indépendamment. Les mélanger dans une même clause — « la caméra suit le coureur qui traverse » — rend ambigu quel élément pilote le mouvement.

Faire correspondre le mouvement à la durée du clip

Un clip court ne peut pas contenir un mouvement de caméra complexe. Avancer, panoramiquer et tourner en même temps dans un même clip de deux secondes sera soit compressé en un flou, soit entièrement abandonné. Choisissez un seul comportement de caméra par clip et gardez une amplitude modérée. Si vous avez besoin d'un long mouvement de caméra évolutif, c'est le travail de l'étape de montage : générez plusieurs clips avec des positions de caméra progressives, puis montez-les ensemble.

Utiliser des ancrages spatiaux

Le modèle comprend bien les positions relatives. Des phrases comme « au premier plan », « derrière le sujet », « depuis la gauche », « vers le coin supérieur droit du cadre » lui fournissent des points de référence. Ajouter un ancrage au sujet et un ancrage à la caméra stabilise généralement mieux le plan que d'empiler des adjectifs.

Relire après avoir écrit

Une vérification simple avant d'envoyer la requête : relisez la phrase de mouvement comme si vous donniez une instruction à quelqu'un tenant une caméra. Si cette personne poserait une question de suivi, le prompt a besoin d'une réponse plus précise.

Une requête HiAPI fonctionnelle pour générer un clip à partir de texte

Cette section explique l'écriture de la requête de bout en bout. L'objectif est d'obtenir un modèle que vous conservez et réutilisez, en ne changeant que le texte du prompt à chaque exécution.

Étape 1 : Authentification

Tous les appels passent par HiAPI avec vos identifiants API. Placez la clé dans une variable d'environnement, pas dans le code source :

export HIAPI_API_KEY="your_key_here"

Étape 2 : Envoyer la requête de génération

La requête spécifie le modèle et transmet le prompt. Voici l'écriture minimale avec curl :

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "prompt": "Un cycliste en imperméable rouge, roulant régulièrement au crépuscule dans des rues urbaines humides, reflets néon dans les flaques, la caméra avance lentement, rendu réaliste caméra à l'épaule"
  }'

Remarquez comment le prompt porte les quatre modules plus une instruction de caméra explicite. C'est la structure décrite plus haut, simplement sérialisée.

Étape 3 : Traiter la réponse

La réponse renvoie une référence à la ressource du clip généré. Avant de vous y fier, traitez-la comme des données à valider :

• Analysez le corps de la réponse en JSON et vérifiez la présence de champs d'erreur avant de lire un quelconque résultat.
• Confirmez la présence d'une référence de clip ; si elle est absente, journalisez la réponse complète et arrêtez-vous, au lieu de continuer avec une valeur vide.
• Lisez les métadonnées du clip dans la réponse et journalisez-les avec le prompt qui l'a produit — c'est la base de la boucle d'itération ultérieure.
• Téléchargez ou diffusez le clip vers votre propre stockage, car la persistance relève de votre pipeline.

Étape 4 : Encapsuler dans une fonction

Pour tout workflow réel, déplacez la requête dans une petite fonction qui reçoit une chaîne de prompt et renvoie la référence du clip ainsi que ses métadonnées. Laissez le nom du modèle, les en-têtes et la gestion des erreurs à l'intérieur de la fonction. Dès lors, chaque expérience ne consiste plus qu'à changer une ligne de prompt, plutôt qu'à faire une tâche d'intégration.

import os, requests

def generate_clip(prompt: str) -> dict:
    resp = requests.post(
        "https://api.hiapi.ai/v1/video/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": "wan2.7-video/text-to-video", "prompt": prompt},
        timeout=120,
    )
    resp.raise_for_status()
    data = resp.json()
    if not data.get("clip"):
        raise ValueError(f"No clip in response: {data}")
    return data

Cette fonction est l'unité réutilisable de votre pipeline. Tout le reste se construit au-dessus d'elle.

Étape 5 : Valider avant de monter

Avant qu'un clip n'entre dans l'étape de montage, vérifiez que le fichier se télécharge proprement et que sa durée reste dans la plage que l'étape de montage peut traiter. Rejetez tôt, plutôt que de découvrir un clip corrompu au moment de la publication.

Itération : d'un bon clip à un workflow de vidéos courtes reproductible

Une fois la requête opérationnelle, le travail intéressant commence : transformer un seul bon clip en un processus qui produit de manière fiable des sorties vidéo courtes.

La boucle d'itération

Cette boucle comporte trois phases et se répète :

1. Faire varier le prompt. Ne changez qu'un module à la fois — action, phrase de caméra, style. En changeant plusieurs à la fois, vous ne pouvez pas déterminer quel changement a eu un effet.
2. Sélectionner les clips. Examinez le lot généré et conservez ce qui est utilisable. Notez vos décisions de sélection ; des notes comme « l'avance fonctionne, l'orbite est trop rapide » ont plus de valeur que le clip lui-même.
3. Monter. Assemblez les clips conservés, découpez à la durée voulue et vérifiez que les segments se montent proprement ensemble.

La sortie du montage alimente la prochaine itération de variation du prompt. Si deux clips ne se montent pas ensemble, cela fournit une information sur ce sur quoi vos prompts doivent rester cohérents — le cadrage du sujet, la lumière ou la direction du mouvement.

Constituer une bibliothèque de prompts

Conservez chaque prompt ayant produit un clip retenu, avec sa référence de clip et vos notes. Après quelques cycles, cela devient une petite bibliothèque de motifs à recombiner : descriptions de sujets validées, phrases de caméra validées, modules de style validés. Les nouvelles vidéos peuvent ainsi être assemblées à partir de composants connus pour bien fonctionner, plutôt que de partir d'un prompt vide.

Générer par lots à partir de structures de données

Comme votre fonction de requête reçoit une chaîne de prompt, générer des variantes revient à parcourir en boucle une liste ou un petit objet de configuration. Définissez une fois le sujet et la scène, puis parcourez une liste d'actions et une liste de phrases de caméra pour produire un ensemble de candidats. C'est là que la perspective en pipeline se révèle payante : le modèle est la constante, le prompt est la variable, votre code n'a qu'à énumérer les variations.

Garder la sélection peu coûteuse

Tous les clips générés n'ont pas besoin d'être visionnés intégralement. Définissez à l'avance des critères de rejet simples — mauvais sujet, absence de mouvement, cadrage inutilisable — et rejetez rapidement. Consacrez le temps de visionnage aux cas limites, c'est-à-dire aux clips qui pourraient être utilisables après découpe.

Versionner le workflow

Pour chaque clip que vous conservez, stockez ensemble le prompt, le nom du modèle et les métadonnées de réponse. Lorsque le style visuel de votre chaîne évolue, vous pouvez retracer exactement quels motifs de prompts ont produit le style actuel, et ajuster à partir d'une base de référence connue, plutôt que de deviner.

Pièges courants et comment les éviter

Dans les pipelines de génération de vidéo à partir de texte, plusieurs modes d'échec reviennent régulièrement. Chacun a un correctif direct.

Verbes de mouvement vagues

Symptôme : le mouvement de caméra des clips renvoyés semble aléatoire, ou le sujet ne bouge presque pas. Correctif : remplacez chaque terme de mouvement abstrait par une instruction littérale et directionnelle. Spécifiez un comportement de caméra et une action de sujet par clip, chacun avec une amplitude — lentement, régulièrement, verrouillé.

Prompts surchargés

Symptôme : une partie de la description manque dans la sortie, ou le résultat semble un compromis entre plusieurs idées. Correctif : imposez une seule action par clip et supprimez les détails qui ne changent pas ce qui apparaît à l'image. Séparez une idée multi-plans en clips distincts et laissez l'étape de montage faire le séquençage.

Sauter la validation des réponses

Symptôme : des réponses en échec ou mal formées entrent dans le stockage et l'étape de montage, et ne sont découvertes qu'à la publication. Correctif : après chaque appel, vérifiez immédiatement la présence d'erreurs et de la référence de clip, journalisez la réponse complète en cas d'échec, et validez les ressources avant qu'elles n'entrent dans la sélection.

Supposer des attributs de clip fixes

Symptôme : la logique de montage échoue lorsque la durée ou le format du clip renvoyé diffère de l'attendu. Correctif : lisez les métadonnées de la réponse et adaptez-vous au montage. Ne codez pas en dur la durée des clips dans le pipeline.

Changer trop de variables à la fois

Symptôme : vous ne pouvez pas déterminer quel changement de prompt a amélioré ou cassé la sortie. Correctif : ne changez qu'un module par itération et conservez des notes. L'ingénierie de prompts ici est une boucle expérimentale, pas une réécriture.

Prendre l'appel API pour le produit entier

Symptôme : la requête fonctionne mais n'offre pas de sortie fiable, car la sélection et le montage n'ont jamais été construits. Correctif : rappelez-vous que la génération n'est qu'une étape. Réservez un véritable effort au visionnage, au stockage et au montage des clips — c'est là que se décide réellement la qualité d'une vidéo courte.

Si vous conservez la requête dans une fonction réutilisable et itérez sur le texte du prompt, la plupart des pièges ci-dessus disparaissent d'eux-mêmes.