Transformer un script en vidéo courte avec avatar parlant via l'API heygen-avatar-v et hiapi

Le contenu vidéo court avec avatar parlant — mises à jour de fondateurs, démonstrations produit, créations publicitaires de style UGC — implique généralement de réserver un humain, de préparer un micro et de refaire un montage. heygen-avatar-v sur hiapi réduit tout cela à un seul appel d'API : envoyez un script ou un fichier audio et récupérez une vidéo d'avatar avec synchronisation labiale, des mouvements idle naturels et une piste de sous-titres, prête à être publiée dans un fil de vidéos courtes. Cet article parcourt le flux de travail réel /v1/tasks, un extrait vidéo réellement généré, les contraintes à connaître avant de construire un pipeline autour de lui, et les tarifs récupérés en direct depuis /api/pricing de hiapi. Si vous cherchez plutôt des astuces de style au niveau du prompt pour l'avatar lui-même, heygen-avatar-v prompt recipes les couvre déjà — cet article explique comment intégrer ce modèle dans un pipeline de vidéos courtes réutilisable.

Ce que heygen-avatar-v produit réellement

heygen-avatar-v est un modèle de vidéo d'humain numérique, pas un générateur texte-vers-vidéo au sens de Sora/Kling — il pilote un avatar HeyGen prédéfini à partir d'un script texte ou d'un fichier audio téléversé, et renvoie une vidéo où la bouche de l'avatar est synchronisée avec la parole, avec de subtils mouvements continus (clignements, légers mouvements de tête, balancements d'épaules) pour qu'il ne ressemble pas à un portrait statique. Ce comportement « qui bouge même au repos » est précisément la frontière entre un extrait de vidéo courte exploitable et une photo parlante qui trahit immédiatement le faux.

Le modèle est piloté par deux types d'entrée, mutuellement exclusifs — vous envoyez l'un ou l'autre :

• prompt — un script texte ; lu par le TTS de hiapi et utilisé pour piloter la synchronisation labiale
• audio_url — une URL publique vers une piste vocale préenregistrée (votre propre doublage, une voix clonée, peu importe), qui pilote la synchronisation labiale

Il n'y a pas de champ duration. La longueur du clip dépend entièrement de la durée de lecture du script ou de l'audio — une réplique de 40 mots produira un clip plus court qu'une réplique de 200 mots. C'est important pour planifier les coûts, voir plus bas.

Des champs optionnels affinent le style : avatar (choisi dans la bibliothèque de préréglages HeyGen), voice (utilisé uniquement avec prompt, ignoré avec audio_url), aspect_ratio (9:16 pour Reels/TikTok/Shorts, 16:9, 1:1), resolution, background (couleur unie ou décor — mais voir le piège ci-dessous), caption (génère une piste de sous-titres) et output_format (mp4 ou webm, ce dernier avec fond transparent pour une composition sur vos propres décors).

Un clip réel : un script en entrée, une vidéo d'avatar sous-titrée en sortie

Voici une véritable sortie de heygen-avatar-v — l'avatar récite une réplique, avec des mouvements idle visibles entre les phrases et une piste de sous-titres synchronisée :

Remarquez ce qui ne se produit pas : l'avatar ne se fige pas entre les phrases, et les sous-titres suivent la parole au lieu d'être collés après coup. Cette combinaison — mouvement continu et sous-titres synchronisés — est toute la raison de choisir ce modèle plutôt que d'enregistrer une voix off sur une image d'avatar statique dans un éditeur.

Pièges : deux problèmes qui mordront votre première version du pipeline

caption renvoie un fichier de sous-titres annexe, pas des sous-titres incrustés. Définir caption: true renvoie un fichier .srt synchronisé en plus de la vidéo — il n'incruste pas le texte dans les images vidéo. Si vous voulez que le texte des sous-titres apparaisse à l'écran (le rendu typique de la plupart des plateformes de vidéos courtes), il faut faire une incrustation séparée avec ce fichier .srt (ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4, ou la fonction d'import de sous-titres native de votre plateforme). Traitez les « sous-titres » de l'API comme des données, pas comme une image déjà rendue.

background ne fonctionne que pour les avatars de style illustration, pas pour les avatars photoréalistes. La bibliothèque d'avatars HeyGen mêle avatars photoréalistes et avatars illustration/animation. Le paramètre background parvient à remplacer le décor derrière un avatar de style illustration, mais les avatars photoréalistes conservent leur décor d'enregistrement d'origine quoi que vous envoyiez — le modèle ne les détoure pas. Si votre pipeline suppose que chaque avatar accepte un remplacement de fond, testez d'abord l'ID avatar précis que vous comptez utiliser avant de supposer qu'il se composera comme prévu. Pour un avatar photoréaliste que vous voulez placer sur votre propre fond, la solution fiable est output_format: webm (transparent).

Coût : facturé à la seconde de sortie, pas à l'appel

Selon le /api/pricing en direct de hiapi, heygen-avatar-v est facturé 0,15 $ par seconde de sortie — tarif uniforme quelle que soit la résolution ou le rapport d'aspect. Comme il n'y a pas d'entrée de durée, votre coût réel dépend de la durée de lecture du script ou de l'audio :

Longueur du script (env.)	Durée de sortie	Coût
Accroche courte	env. 5 secondes	0,75 $
Un segment de vidéo courte	env. 10 secondes	1,50 $
Argumentaire de plusieurs phrases	env. 20 secondes	3,00 $
Publicité parlée complète de 30 secondes	env. 30 secondes	4,50 $

Comme le coût varie avec la longueur de la parole et non avec un paramètre que vous fixez à l'avance, la bonne pratique est de chronométrer le script avant de soumettre la tâche (lisez-le à voix haute, ou passez-le dans un estimateur de longueur TTS), plutôt que de découvrir la facture une fois le clip rendu.

Le pipeline : soumettre, interroger, télécharger avant expiration

heygen-avatar-v s'exécute sur le point de terminaison asynchrone /v1/tasks de hiapi — comme tous les autres modèles basés sur des tâches de la plateforme, c'est le schéma « créer puis interroger ». Un détail propre à ce flux de travail : entre handling et success, une tâche passe par une phase archiving, où la plateforme finalise la vidéo et les fichiers de sous-titres annexes, donc ne considérez pas archiving comme un état terminal dans votre boucle d'interrogation.

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

Deux notes opérationnelles à ne pas ignorer en usage à grande échelle :

• Téléchargez immédiatement. Comme pour chaque sortie de tâche hiapi, les URL renvoyées portent un expireAt et ne conviennent pas comme liens permanents — dès que la tâche réussit, récupérez les octets (vidéo et .srt) dans votre propre stockage.
• N'envoyez pas une charge utile minimale « pour vérifier le schéma ». Comme seuls prompt ou audio_url sont strictement obligatoires, les autres champs prennent silencieusement leurs valeurs par défaut, et une charge utile réduite à {"prompt": "test"} ne renverra pas de 400 — elle déclenchera un rendu réel et facturable. Validez les noms de champs en consultant la documentation ou en provoquant une réponse 4xx avec une valeur volontairement invalide, plutôt qu'en omettant des champs sur le point de terminaison réel.

FAQ

Puis-je utiliser ma propre voix au lieu du TTS de hiapi ? Oui — transmettez audio_url au lieu de prompt, en fournissant l'URL publique de votre enregistrement, et l'avatar synchronisera ses lèvres sur cette piste plutôt que de synthétiser la parole à partir du texte.

L'option caption incruste-t-elle les sous-titres dans la vidéo ? Non. caption: true renvoie un fichier .srt séparé, synchronisé avec l'audio de la vidéo de sortie. Si vous voulez le texte des sous-titres à l'écran, incrustez-le vous-même comme étape de post-traitement.

Puis-je contrôler la durée du clip ? Pas directement — il n'y a pas de paramètre duration. La longueur de sortie est déterminée par la longueur du script (avec prompt) ou par la longueur du fichier audio (avec audio_url).

Pourquoi le fond que j'ai spécifié n'apparaît-il pas ? background ne fonctionne que pour les avatars de style illustration/animation de la bibliothèque HeyGen. Les avatars photoréalistes conservent leur décor d'enregistrement d'origine ; dans ce cas, utilisez plutôt output_format: webm pour obtenir une sortie transparente et faire la composition vous-même.

Quelles résolutions et quels rapports d'aspect sont pris en charge ? Jusqu'à 4K, avec les options de rapport d'aspect 9:16, 16:9 et 1:1 — couvrant du fil vertical de vidéos courtes au format large et carré.

L'essentiel

Construire un pipeline de vidéos courtes avec avatar sur hiapi se résume à quelques faits concrets, pas à des suppositions : le coût est de 0,15 $ par seconde de sortie (donc chronométrez votre script avant de soumettre, pas après), la sortie de sous-titres est un fichier annexe .srt que vous devez incruster vous-même, le remplacement du fond ne fonctionne que pour les avatars de style illustration, et votre boucle d'interrogation doit traiter archiving comme un état non terminal, tout comme handling. Avant de coder un budget en dur, consultez les chiffres à jour sur la page de tarifs de hiapi, et référez-vous à la page du modèle pour la référence complète des champs. Si vous êtes prêt à vous lancer, obtenez une clé API depuis le tableau de bord et commencez par un script court — une sortie de 5 secondes suffit pour confirmer que votre avatar, votre rapport d'aspect et la gestion des sous-titres fonctionnent, avant de passer à l'échelle sur des lots entiers.