Vidéo avatar HeyGen à partir d’un script, API v3

Une vidéo avatar HeyGen est un script, une voix et un apparence qui articule les mots. Vous pouvez construire cela dans AI Studio pour une introduction de cours, ou envoyer les mêmes trois éléments à POST /v3/videos. La traduction double le discours. Elle ne réécrit pas les mots peints dans le cadre. Cet atelier utilise le centre d’aide et les documents v3 tels qu’ils se lisent en octobre 2026.

Écrivez le script dans AI Studio

L’article de script d’AI Studio dit que chaque scène a son propre script. Add Scene, puis choisissez Blank ou From Template, et tapez dans l’éditeur de script. Attribuez un avatar, une voix et un arrière-plan après que les mots existent. Le script est ce que l’avatar dit. Ce n’est pas une piste de sous-titres à moins que vous ajoutiez des sous-titres séparément.

Le même article dit que vous pouvez télécharger ou télécharger le script complet depuis le menu en haut à gauche, y compris les positions de pause. Le fichier est lu dans le navigateur et n’est pas téléchargé en tant que fichier de script lui-même. Les limites indiquées là :

• Une ligne, un paragraphe ou une cellule de plus de 1 000 caractères est divisé en plus d’un segment.
• Un segment correspond à une scène, dans l’ordre. Les segments supplémentaires créent des scènes supplémentaires.
• Les lignes vides et les cellules vides sont ignorées.
• Si la vidéo a déjà du texte, le téléchargement ajoute des scènes. Il ne remplace pas ce qui est là.
• Si vous sélectionnez plusieurs fichiers, seul le premier est utilisé.
• .doc n’est pas accepté. Enregistrez les fichiers Word sous .docx.
• Pour .txt, mettez chaque scène sur sa propre ligne. Pour Excel ou CSV, mettez chaque scène dans sa propre cellule.

Pour une introduction de cours, écrivez une phrase par scène. Scene one est la promesse (« cette leçon corrige ImagePullBackOff »). Scene two est la commande que le spectateur exécutera. Scene three est l’endroit où les étapes écrites vivent sur votre site. Les scènes courtes sont plus faciles à remplacer quand un drapeau change.

La prononciation des noms de produits est un problème de glossaire, pas un problème d’orthographe. L’article de script pointe sur la correction de la prononciation dans l’éditeur. La section Brand Glossary ci-dessous est la version durable de cette correction.

Avatars et voix

Dans le produit, un Brand System a un onglet Avatars. Add Brand Avatar choisit les apparences qui appartiennent à cette marque, afin qu’une série de leçons ne dérive pas parmi les visages de stock.

Sur l’API, avatar_id peut être un avatar vidéo ou une apparence d’avatar photo. La référence create-video dit que les types sont studio avatar, digital twin et photo avatar. Si vous omettez engine, le serveur utilise Avatar IV. Définissez engine.type à avatar_v uniquement quand vous voulez dire Avatar V. La page de tarification entreprise dit qu’Avatar V est pour les jumeaux numériques. N’envoyez pas Avatar V pour une apparence que la référence dit être rejetée. Les avatars photo peuvent prendre un motion_prompt sur l’un ou l’autre moteur. Les avatars vidéo prennent motion_prompt quand le moteur est Avatar V. La référence dit qu’Avatar IV rejette ce prompt pour les avatars vidéo.

expressiveness (high, medium, low) est des avatars photo sur Avatar IV uniquement. Il est par défaut faible quand omis, et il est rejeté pour Avatar V.

Les voix sont des IDs, pas des noms d’affichage. GET /v3/voices les énumère. La page des limites d’utilisation dit que cette liste est par défaut 20 et plafonne une page à 100. GET /v3/avatars est par défaut 20 et plafonne à 50. Les deux utilisent une limit et une next_token.

Le démarrage rapide nomme également deux chemins de clonage dans le produit : une voix instantanée d’un enregistrement, et un clone professionnel entraîné sur 20 minutes ou plus d’audio. Passez le voice_id résultant dans l’appel vidéo. voice_settings optionnel sur create inclut speed, pitch, volume et locale.

Vous pouvez sauter la synthèse et passer audio_url ou audio_asset_id au lieu de script. Ces deux sont mutuellement exclusifs en laissant le script piloter la voix. Une URL que vous passez doit être publique. La note de dépannage du démarrage rapide dit qu’un download_failed 400 signifie que l’URL n’a pas pu être récupérée.

Brand System et glossaire

L’article d’aide l’appelle un Brand System, pas un tas vague de téléchargements. Onglets :

• Brand Spec : couleurs (y compris une valeur hexadécimale) et polices pour Body, Caption, Display, Heading et Heading 2.
• Assets : images et vidéos, via Upload Brand Assets.
• Logos : Upload Brand Logos.
• Motion : pièces de mouvement enregistrées depuis Video Agent.
• Avatars : Add Brand Avatar.

Limites de téléchargement sur cet article, selon la page lue en octobre 2026 : résolution jusqu’à 4096 par 4096. Images et logos JPG ou PNG jusqu’à 200 MB (il indique également 4167 par 4167). MP4 ou MOV jusqu’à 200 MB. Polices TTF ou OTF jusqu’à 100 MB.

Vous appliquez un Brand System depuis AI Studio avec Brand sur le menu de droite, ou depuis Video Agent par le contrôle + à côté de l’invite, puis Brand System.

Brand Glossary est la seconde moitié de la marque. Ouvrez Brand dans la navigation de gauche, puis Brand Glossary.

• Les règles de prononciation affectent la synthèse vocale AI Studio. L’article dit que ces mots s’affichent en violet italique dans l’éditeur de script.
• Les règles de traduction sont Force Translate (utilisez ce libellé) ou Don’t Translate (laissez le terme). Elles s’appliquent quand un travail Video Translation utilise le glossaire.

Sur l’API, brand_glossary_id change la façon dont script est parlé. La référence dit qu’un audio_url ou audio_asset_id fourni n’est pas réécrit par le glossaire. Les sous-titres affichent toujours les mots de script originaux. La prononciation est uniquement l’audio. Découvrez les IDs avec GET /v3/brand-glossaries.

folder_id n’est pas un kit de marque. La référence dit qu’un ID de projet de kit de marque est rejeté avec 404 avant que quoi que ce soit ne soit créé. Omettez folder_id, ou passez un vrai ID de dossier depuis POST /v3/folders.

Traduction et doublage

Video Translation, dans l’article d’aide, re-vocise la piste parlée dans une autre langue, en utilisant la voix du locuteur original, et peut synchroniser les lèvres. Vous téléchargez une vidéo, choisissez les langues cibles et un moteur de traduction, et exécutez Translate.

Ce qui bouge :

• Audio parlé, dans la voix du locuteur original.
• Mouvement des lèvres, si vous activez cela.
• Sous-titres à l’écran, si vous activez cela.

Ce qui reste :

• Texte qui fait partie de l’image : titres, lower-thirds, sous-titres codés en dur.
• Musique de fond, sauf si vous activez Remove Background Sound.

Les vidéos chantées et axées sur la musique sont appelées incohérentes. Les langues sources non supportées échouent immédiatement et, selon l’article, n’utilisent pas de crédits. Si vous avez besoin des mots à l’écran dans la nouvelle langue, construisez cette vidéo dans le studio. Ne vous attendez pas à ce que la traduction repeigne les pixels.

L’endpoint de liste de l’API GET /v3/video-translations est sur la page des limites d’utilisation (taille de page par défaut 10, max 100). Cet atelier ne montre pas un corps POST de traduction, car ce schéma de demande n’a pas été sur les pages lues ici. L’article d’aide dit que l’API peut exécuter la traduction. Recherchez l’appel de création actuel dans les documents développeur avant de l’automatiser.

L’utilisation de l’API est facturée séparément des plans d’application. L’article d’aide sur la tarification de l’API dit que les crédits API sont à l’usage et ne sont pas le même portefeuille qu’un abonnement Creator, Pro ou Business. Cet atelier ne copie pas les tarifs par seconde. La page libre-service et la page entreprise utilisent des unités différentes.

Générez une vidéo depuis l’API

URL de base https://api.heygen.com. Créez une clé dans la page API keys et exportez-la vous-même. Le démarrage rapide vérifie la clé avec GET /v3/users/me. Un 401 signifie que l’en-tête manque ou que la clé est inactive.

export HEYGEN_API_KEY="your-key"

Énumérez une apparence et une voix, puis créez. Le démarrage rapide écrit l’en-tête comme X-Api-Key. La référence REST l’écrit comme x-api-key. Les noms d’en-tête HTTP sont insensibles à la casse. Utilisez l’un d’eux, pas une clé de chaîne de requête.

curl "https://api.heygen.com/v3/avatars?limit=20" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

curl "https://api.heygen.com/v3/voices?limit=20" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

curl -X POST "https://api.heygen.com/v3/videos" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c0b2e-7a11-4d5e-9c31-2b6a8e0d11ab" \
  -d "{\"type\":\"avatar\",\"avatar_id\":\"YOUR_AVATAR_ID\",\"voice_id\":\"YOUR_VOICE_ID\",\"script\":\"This lesson shows how to read a CrashLoopBackOff event before you change the image.\",\"title\":\"CrashLoop lesson intro\",\"aspect_ratio\":\"16:9\"}"

Le corps de la réponse inclut video_id et status. Le statut d’exemple du schéma est waiting. Une Idempotency-Key de 1 à 255 caractères de lettres, chiffres et _:.- fait qu’une nouvelle tentative dans la fenêtre documentée retourne la réponse originale au lieu d’un second rendu. Un doublon encore en vol retourne 409.

Interrogez jusqu’à ce que le travail se termine :

curl "https://api.heygen.com/v3/videos/VIDEO_ID" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Le démarrage rapide traite completed et failed comme les statuts terminaux pour GET /v3/videos/{video_id}, et il lit video_url de cette charge. En cas d’échec, lisez failure_code et failure_message. Un 429 signifie que vous avez atteint une limite de taux ou de concurrence. Honorer Retry-After et reculer. Vous pouvez également passer callback_url à la création et sauter la boucle de sondage.

Les contraintes de sortie de la page des limites d’utilisation : la vidéo avatar est 25 images par seconde. La largeur et la hauteur doivent chacune se situer entre 128 et 4096 pixels. La sortie par défaut est 1080p. L’aspect_ratio de la référence create inclut 16:9 (le défaut), 9:16, 4:5, 5:4, 1:1 et auto. Une scène plus longue que 30 minutes échoue pendant le rendu. Un appel avatar est une scène, donc 30 minutes est la vidéo entière. Les vidéos studio et de modèle multi-scènes peuvent s’exécuter plus longtemps, tant que chaque scène reste sous ce plafond. La page plafonne également les scènes à 50. 4k sur la référence create est pour les jumeaux numériques et les avatars de studio Avatar III, pas un commutateur universel.

output_format est par défaut mp4. caption optionnel peut demander un fichier srt. background optionnel prend une valeur de couleur, une URL ou un ID d’asset.

Deux autres chemins de création existent, et ce ne sont pas l’appel script-to-avatar :

• POST /v3/video-agents prend un prompt. Le démarrage rapide interroge la session pour un video_id, puis interroge la vidéo. C’est Video Agent : le service rédige la pièce.
• POST /v3/models/videos avec model heygen-video-1 génère une scène à partir d’un prompt (texte, image ou référence). La page du modèle dit que c’est un outil différent des moteurs d’avatar derrière POST /v3/videos.

Utilisez /v3/videos quand vous avez déjà écrit les mots. Le démarrage rapide dit que v1 et v2 restent soutenus jusqu’au 31 octobre 2026. Le nouveau code doit être v3.

Un outil de workflow peut POST cette charge et interroger. Le modèle pour un appel HTTP déclenché par webhook est dans n8n first workflow. Un agent qui décide quand rendre est une conception différente. Voir what is agentic AI.

Introductions de cours et courts tutoriels

Utilisez une intro avatar quand la leçon est une tête parlante plus un enregistrement d’écran ultérieur que vous éditez vous-même. HeyGen est un mauvais endroit pour démontrer un terminal en direct. Enregistrez le terminal séparément et laissez l’avatar gérer les 20 à 40 secondes d’encadrage.

Gardez kubectl, les noms d’images et les orthographes de drapeaux dans Brand Glossary afin que la voix n’invente pas une prononciation. Mettez la commande tapée à l’écran dans l’éditeur si les étudiants doivent la lire. La traduction ne convertira pas cette superposition.

Pour une série, verrouillez un avatar, une voix, un Brand System et 16:9. Passez à 9:16 uniquement pour une réduction, en tant que second rendu, pas en recadrant la leçon dans un outil externe et en espérant que la bouche correspond toujours.

La recherche pour le script peut commencer dans Perplexity. Le brouillon parlé doit toujours correspondre à un document que vous avez ouvert. Un passage Gemini sur le contour est optionnel. La Gemini tools cheat sheet est le côté API de cela, pas un moteur de rendu vidéo.

Liste de contrôle de qualité

• Lisez le script à voix haute. Une idée par scène. Divisez n’importe quoi que l’importateur diviserait à 1 000 caractères.
• Confirmez avatar_id et voice_id des endpoints de liste, pas d’une capture d’écran.
• Définissez aspect_ratio au lecteur que vous expédiez (16:9 pour une page de cours).
• Ajoutez les règles de glossaire pour les noms de produits et les outils CLI avant de rendre un lot.
• Ne gravez pas le titre de la leçon dans les pixels si vous allez traduire. Ajoutez les sous-titres en tant que sous-titres.
• Attendez completed. Un corps waiting ou en progression n’a pas de fichier final.
• Lisez le mp4 avec le son. Vérifiez les cinq premières secondes du mouvement des lèvres et n’importe quel mot que vous avez ajouté au glossaire.
• Sur failed, copiez failure_code et failure_message avant de réessayer. Changez la clé d’idempotence uniquement quand vous avez l’intention d’une nouvelle vidéo.
• Sur 401, corrigez la clé. Sur 429, attendez Retry-After. Sur 400 download_failed, l’URL audio ou de fond n’est pas récupérable publiquement.
• Gardez la clé en dehors du repo. Les instructions d’agent du démarrage rapide disent de l’exporter localement et de ne pas la coller dans un chat.

FAQ

Quel endpoint API HeyGen crée une vidéo avatar à partir d’un script ?

POST https://api.heygen.com/v3/videos avec JSON type avatar, plus avatar_id, script et voice_id. L’en-tête est X-Api-Key. L’appel de création retourne video_id et un statut tel que waiting. Interrogez GET /v3/videos/{video_id} jusqu’à ce que le statut soit completed ou failed. v1 et v2 restent soutenus jusqu’au 31 octobre 2026, selon la lecture rapide lue en octobre 2026.

La traduction vidéo HeyGen réécrit-elle le texte à l’écran ?

Non. L’article d’aide sur la traduction vidéo dit que l’audio parlé est re-voicé, et le mouvement des lèvres et les sous-titres à l’écran sont optionnels. Le texte gravé dans l’image, les graphiques et les sous-titres codés en dur restent tels qu’ils sont. La musique de fond reste sauf si vous activez Remove Background Sound. Les paroles chantées ne sont pas un cas fiable.

Qu’est-ce qu’un Système de marque HeyGen ?

C’est le nom du centre d’aide actuel pour le kit de marque : couleurs, polices, logos, images, éléments de mouvement et avatars choisis. Brand Glossary est séparé. Il contient des règles de prononciation pour la synthèse vocale AI Studio et des règles de traduction (Force Translate ou Don’t Translate) utilisées lorsque vous exécutez Video Translation avec le glossaire sélectionné.

Pourquoi POST /v3/videos a-t-il retourné 404 pour mon dossier ?

La référence create-video dit que folder_id doit être un dossier dans lequel l’appelant peut écrire, non dans la corbeille. Un ID d’un autre espace de travail, ou un projet d’un autre type tel qu’un kit de marque, est rejeté avec 404 avant qu’une vidéo ne soit créée. Énumérez les avatars avec GET /v3/avatars et les voix avec GET /v3/voices au lieu de coller un ID de kit de marque dans folder_id.