Que fait Avatar Vidéo ?
Créez des vidéos d'avatars 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 simples ou multi-scènes avec une configuration précise en utilisant 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 d'outils
Si les outils MCP HeyGen sont disponibles (mcp__heygen__*), privilégiez-les plutôt que des appels API HTTP directs — ils gèrent automatiquement l'authentification et le formatage des requêtes.
| Tâche | Outil MCP | Alternative (API directe) |
|---|---|---|
| Vérifier l'état d'une 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 la liste des avatars/voix se font via des appels API directs — voir les fichiers de référence ci-dessous.
Flux de travail par défaut
- Lister les avatars —
GET /v2/avatars→ choisissez un avatar, prévisualisez-le, notezavatar_idetdefault_voice_id. Voir avatars.md - Lister les voix (si nécessaire) —
GET /v2/voices→ choisissez une voix correspondant au sexe/langue de l'avatar. Voir voices.md - Rédiger le script — Structurez les scènes avec un concept par scène. 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 pour completion —
GET /v2/videos/{video_id}jusqu'à ce que l'état 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 |
| Rédiger et structurer les scripts | scripts.md |
| Générer une vidéo (simple 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 templates | templates.md |
| Créer un avatar à partir d'une photo | photo-avatars.md |
| Vérifier l'état d'une vidéo / télécharger | 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 la compétence create-video à la place.
| 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 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érer des vidéos par lots avec des spécifications exactes" | ✓ |
Fichiers de référence
Création vidéo de base
- references/avatars.md - Lister les avatars, styles, sélection d'avatar_id
- references/voices.md - Lister les voix, locales, vitesse/hauteur
- references/scripts.md - Rédiger des scripts, pauses, rythme
- references/video-generation.md - POST /v2/video/generate et vidéos multi-scènes
Personnalisation vidéo
- references/backgrounds.md - Couleurs unies, images, arrière-plans vidéo
- references/text-overlays.md - Ajouter du 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 templates et remplacement de variables
- references/photo-avatars.md - Créer des avatars à partir de photos
- references/webhooks.md - Points de terminaison et événements de webhook
Intégration
- references/remotion-integration.md - Utiliser HeyGen dans des compositions Remotion
Fondamentaux
- references/video-status.md - Modèles d'interrogation et URL de téléchargement
- references/assets.md - Télécharger images, vidéos, audio
- references/dimensions.md - Résolution et rapports hauteur/largeur
- 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 - Solution de secours : faites correspondre le sexe manuellement — Si aucune voix par défaut, assurez-vous que les sexes 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) - Fixez 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 ID d'avatar et de voix existent avant de générer