Créer des vidéos courtes avec wan2.7-video/text-to-video@pro : un workflow API hiapi de bout en bout

Le succès d'une vidéo courte dépend de la vitesse d'itération : il vous faut beaucoup de clips candidats, au format vertical, avec du son, et rapidement. Ce guide est précisément consacré à cela, en utilisant wan2.7-video/text-to-video@pro sur hiapi — le modèle texte-vers-vidéo Tongyi Wanxiang 2.7 d'Alibaba, avec une sortie allant jusqu'à 1080P, un audio natif et des clips d'une durée maximale de 15 secondes. Chaque structure de requête, limite de paramètre et message d'erreur ci-dessous a été vérifié en exécutant réellement l'API en production au moment de la rédaction, et les deux clips de démonstration intégrés ont été générés tels quels par le code présenté.

Ce que le modèle vous offre

wan2.7-video/text-to-video@pro est servi via le point de terminaison unifié de tâches asynchrones de hiapi (/v1/tasks). Caractéristiques clés, vérifiées par rapport au schéma en production :

• Sortie : MP4 H.264, jusqu'à 1080P, avec une piste audio AAC native — le modèle génère des sons d'ambiance et des effets sonores à partir de votre prompt, sans étape audio séparée.
• Durée : 2 à 15 secondes par clip (secondes entières).
• Format d'image : 16:9, 9:16, 1:1, 4:3, 3:4 — un véritable portrait 9:16, adapté aux formats Shorts/Reels/TikTok, sans recadrage.
• Tarification : facturation à la seconde de vidéo produite, à partir de 0,167 $/s au moment de la rédaction — soit environ 0,84 $ pour un clip 1080P de 5 secondes. Vérifiez impérativement la page de tarification avant toute génération en masse.

Il n'existe pas de mode synchrone pour la vidéo : vous créez une tâche, interrogez son état jusqu'à son achèvement, puis téléchargez le résultat.

Exemple minimal fonctionnel (curl)

Création de la tâche :

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video@pro",
    "input": {
      "prompt": "Macro en studio : une goutte d'encre bleu saphir tombe dans de l'eau claire, éclosion au ralenti, les filaments d'encre se déploient en forme de nuage, fond blanc sans couture et lumineux, éclairage high-key net, léger bourdonnement ambiant",
      "ratio": "16:9",
      "resolution": "1080P",
      "duration": 4
    }
  }'

Réponse :

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

Interrogation du résultat :

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

Pendant le rendu, data.status vaut handling ; une fois terminé, il passe à success et data.output[0].url contient le MP4. Cette requête a généré ce clip tel quel :

⚠️ Les URL de sortie sont des liens temporaires avec un horodatage expireAt. Téléchargez immédiatement le fichier dans votre propre stockage dès que la tâche réussit — ne le liez pas en direct et ne le stockez pas dans une base de données.

Schéma d'entrée complet (vérifié par rapport à l'API en production)

L'API valide strictement input et rejette les champs inconnus. Voici la liste complète des champs acceptés — obtenue en sondant directement le point de terminaison, non recopiée d'ailleurs :

Champ	Type	Contrainte	Obligatoire
prompt	string	Description de la scène ; pilote aussi l'audio généré	✅
ratio	string	L'une des valeurs 16:9, 9:16, 1:1, 4:3, 3:4	facultatif
resolution	string	720P ou 1080P	facultatif
duration	integer	2–15 (secondes)	facultatif
negative_prompt	string	Contenu à réprimer (par ex. filigrane, superposition de texte)	facultatif
seed	integer	Reproductibilité entre les tentatives	facultatif
watermark	boolean	Active ou désactive le filigrane du fournisseur	facultatif

Deux pièges qui vous éviteront des 400 :

• Le nom du champ est ratio, et non aspect_ratio — les modèles d'image sur hiapi utilisent aspect_ratio, ce modèle vidéo non. Envoyer aspect_ratio renvoie additional properties 'aspect_ratio' not allowed.
• duration est validé côté serveur : duration: minimum: got 1, want 2 et maximum: got 999, want 15 sont exactement les erreurs obtenues lorsque vous sortez de la plage 2–15.

Python de bout en bout : du prompt au MP4 publiable

Voici le workflow complet — création, interrogation, téléchargement — sans SDK, uniquement avec requests :

import time
import requests

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

def make_short(prompt: str, out_path: str, duration: int = 5,
               ratio: str = "9:16", seed: int | None = None) -> str:
    payload = {
        "model": "wan2.7-video/text-to-video@pro",
        "input": {
            "prompt": prompt,
            "ratio": ratio,               # 9:16 = format vertical pour vidéo courte
            "resolution": "1080P",
            "duration": duration,          # 2..15 secondes
            "negative_prompt": "superposition de texte, filigrane, mains déformées",
        },
    }
    if seed is not None:
        payload["input"]["seed"] = seed

    task_id = requests.post(API, headers=HEADERS, json=payload).json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(10)

    video_url = task["output"][0]["url"]   # lien temporaire — téléchargez immédiatement
    with open(out_path, "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    return out_path

make_short(
    "Prise de vue verticale à la main dans un marché nocturne à l'heure dorée : un "
    "vendeur de cuisine de rue fait sauter des nouilles grésillantes dans un wok "
    "embrasé, la vapeur et des étincelles orange tourbillonnent vers la caméra, "
    "des enseignes au néon diffusent des rose et cyan doux dans un arrière-plan flou, "
    "faible profondeur de champ, sensation documentaire dynamique tournée à la main, "
    "accompagné de grésillements et de crépitements",
    "night-market.mp4",
    duration=5,
    seed=20260702,
)

Voici le clip réellement généré par cet appel — portrait 1080×1920, 5 secondes, les grésillements étant générés à partir du texte du prompt :

Lors de mes tests, un clip 16:9 de 4 secondes s'est terminé en environ 3 minutes, un clip 9:16 de 5 secondes un peu plus longtemps — prévoyez quelques minutes par clip, interrogez l'état environ toutes les 10 secondes et n'inondez pas le point de terminaison de requêtes.

Conseils de prompt pour les vidéos courtes : le mouvement et l'audio dépendent du prompt

Le schéma ne comporte ni paramètre de contrôle de caméra ni paramètre de mouvement — tout ce qui concerne le mouvement, le rythme et le son est guidé par le langage du prompt. Ce qui a fonctionné dans mes tests :

• Nommez explicitement le comportement de caméra : par exemple « handheld » (à la main), « slow push-in » (lent travelling avant), « macro » (macro), « shallow depth of field » (faible profondeur de champ). Le tremblement documentaire du clip du marché nocturne vient entièrement du mot « handheld ».
• Décrivez l'audio souhaité : le modèle génère le son à partir du prompt. « sizzling and crackling sounds » (grésillements et crépitements) et « gentle ambient hum » (léger bourdonnement ambiant) sont bien apparus dans la piste audio de sortie.
• Placez l'accroche en premier : pour une vidéo courte, la première seconde fait toute la différence. Mettez l'élément le plus dynamique (wok enflammé, goutte d'encre dans l'eau) au début de la description du prompt.
• Utilisez negative_prompt de manière défensive : « text overlay, watermark, distorted hands » (superposition de texte, filigrane, mains déformées) nettoie les défauts les plus courants sans affecter le prompt principal.
• Figez le seed lors des itérations : avec un seed fixe, modifiez une seule phrase du prompt à la fois et observez son effet réel.

Besoin de contrôler la première image ? Utilisez la variante image-vers-vidéo

Si votre workflow part d'une image clé conçue — visuel produit, première image au style de la marque — le texte-vers-vidéo n'accepte pas d'entrée image. Le modèle complémentaire wan2.7-video/image-to-video@pro le permet : il accepte un tableau media d'objets {"url": "...", "type": "image"}, avec les mêmes champs prompt / resolution / duration, et anime l'image que vous fournissez au lieu d'en générer une de toutes pièces. Même flux basé sur des tâches, même facturation à la seconde. Un pipeline pratique : générez une image fixe avec un modèle d'image, validez-la, puis animez uniquement les images approuvées — vous ne payez ainsi la génération vidéo que pour les images déjà validées.

Erreurs courantes et leur signification réelle

• invalid input: prompt: missing required field "prompt" — prompt est le seul champ obligatoire.
• invalid input: ratio: value must be one of '16:9', '9:16', '1:1', '4:3', '3:4' — vous avez fourni un format d'image non pris en charge par le modèle (ou fait une faute de frappe).
• invalid input: <root>: additional properties '...' not allowed — champ inconnu ; le schéma est strict, consultez le tableau ci-dessus.
• status: "fail" accompagné de TASK_FAILED — la tâche a échoué après sa création ; créez une nouvelle tâche (en réutilisant votre seed pour rester reproductible).
• Le fichier téléchargé est petit ou illisible — vous avez probablement récupéré une URL de sortie expirée. Vérifiez à nouveau expireAt et téléchargez immédiatement après success.

En résumé

Un POST, une boucle d'interrogation, un téléchargement — c'est tout ce qui sépare un prompt textuel d'un MP4 vertical avec son, prêt à publier. Si vous construisez un pipeline de vidéos courtes, récupérez une clé API depuis la console, partez de la fonction Python ci-dessus et parcourez le reste du catalogue de modèles — le même schéma /v1/tasks (comme le montre notre guide seedance-2.0-fast) s'applique à tous les modèles vidéo de la plateforme, si bien que changer de modèle ne demande ensuite qu'une ligne.