Vidéo Avatar
Créez des vidéos d'avatar IA avec un contrôle total sur les avatars, les voix, les scripts, les scènes et les arrière-plans. Construisez des vidéos mono ou multi-scènes avec une configuration précise à l'aide de l'API /v2/video/generate de HeyGen.
Authentification
Toutes les requêtes nécessitent l'en-tête X-Api-Key. Définissez la variable d'environnement HEYGEN_API_KEY.
curl -X GET "https://api.heygen.com/v2/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Sélection des outils
Si les outils MCP HeyGen sont disponibles (mcp__heygen__*), préférez-les aux appels API HTTP directs — ils gèrent automatiquement l'authentification et le formatage des requêtes.
| Tâche | Outil MCP | Repli (API directe) |
|---|---|---|
| Vérifier le statut de la vidéo / obtenir l'URL | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| Lister les vidéos du compte | mcp__heygen__list_videos | GET /v2/videos |
| Supprimer une vidéo | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
La génération de vidéo (POST /v2/video/generate) et le listage des avatars/voix se font via des appels API directs — voir les fichiers de référence ci-dessous.
Workflow par défaut
- Lister les avatars —
GET /v2/avatars→ choisir un avatar, le prévisualiser, noteravatar_idetdefault_voice_id. Voir avatars.md - Lister les voix (si nécessaire) —
GET /v2/voices→ choisir une voix correspondant au genre/à la langue de l'avatar. Voir voices.md - Écrire le script — Structurer les scènes avec un concept chacune. Voir scripts.md
- Générer la vidéo —
POST /v2/video/generateavec avatar, voix, script et arrière-plan par scène. Voir video-generation.md - Interroger la complétion —
GET /v2/videos/{video_id}jusqu'à ce que le statut soitcompleted. Voir video-status.md
Référence rapide
| Tâche | Lire |
|---|---|
| Lister et prévisualiser les avatars | avatars.md |
| Lister et sélectionner les voix | voices.md |
| Écrire et structurer les scripts | scripts.md |
| Générer une vidéo (mono ou multi-scène) | video-generation.md |
| Ajouter des arrière-plans personnalisés | backgrounds.md |
| Ajouter des légendes / sous-titres | captions.md |
| Ajouter des superpositions de texte | text-overlays.md |
| Créer une vidéo WebM transparente | video-generation.md (section WebM) |
| Utiliser des modèles | templates.md |
| Créer un avatar à partir d'une photo | photo-avatars.md |
| Vérifier le statut / télécharger la vidéo | video-status.md |
| Télécharger des actifs (images, audio) | assets.md |
| Utiliser avec Remotion | remotion-integration.md |
| Configurer des webhooks | webhooks.md |
Quand utiliser cette compétence vs Créer une vidéo
Cette compétence est destinée à un contrôle précis — vous choisissez l'avatar, rédigez le script exact, configurez chaque scène.
Si l'utilisateur souhaite simplement décrire une idée de vidéo et laisser l'IA gérer le reste (script, avatar, visuels), utilisez plutôt la compétence create-video.
| L'utilisateur dit | Compétence Créer une Vidéo | Cette Compétence |
|---|---|---|
| "Fais-moi une vidéo sur X" | ✓ | |
| "Crée une démo de produit" | ✓ | |
| "Je veux que l'avatar Y dise exactement Z" | ✓ | |
| "Vidéo multi-scènes avec différents arrière-plans" | ✓ | |
| "WebM transparent pour compositing" | ✓ | |
| "Utilise cette voix spécifique pour mon script" | ✓ | |
| "Génère des vidéos par lots avec des spécifications précises" | ✓ |
Fichiers de référence
Création de vidéo de base
- references/avatars.md - Liste des avatars, styles, sélection d'avatar_id
- references/voices.md - Liste des voix, locales, vitesse/hauteur
- references/scripts.md - Rédaction de scripts, pauses, rythme
- references/video-generation.md - POST /v2/video/generate et vidéos multi-scènes
Personnalisation de la vidéo
- references/backgrounds.md - Couleurs unies, images, arrière-plans vidéo
- references/text-overlays.md - Ajout de texte avec polices et positionnement
- references/captions.md - Légendes et sous-titres générés automatiquement
Fonctionnalités avancées
- references/templates.md - Liste des modèles et remplacement de variables
- references/photo-avatars.md - Création d'avatars à partir de photos
- references/webhooks.md - Points de terminaison et événements webhook
Intégration
- references/remotion-integration.md - Utilisation de HeyGen dans des compositions Remotion
Fondamentaux
- references/video-status.md - Modèles d'interrogation et URLs de téléchargement
- references/assets.md - Téléchargement d'images, vidéos, audio
- references/dimensions.md - Résolution et ratios d'aspect
- references/quota.md - Système de crédits et limites d'utilisation
Bonnes pratiques
- Prévisualisez les avatars avant de générer — Téléchargez
preview_image_urlpour que l'utilisateur puisse voir l'avatar avant de s'engager - Utilisez la voix par défaut de l'avatar — La plupart des avatars ont un
default_voice_idpré-associé pour des résultats naturels - Repli : faites correspondre le genre manuellement — S'il n'y a pas de voix par défaut, assurez-vous que les genres de l'avatar et de la voix correspondent
- Utilisez le mode test pour le développement — Définissez
test: truepour éviter de consommer des crédits (la sortie sera filigranée) - Définissez des délais d'attente généreux — La génération vidéo prend souvent 5 à 15 minutes, parfois plus
- Validez les entrées — Vérifiez que les IDs d'avatar et de voix existent avant de générer