Avatar Video
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 exacte via 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__*), 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 / 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→ 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 genre/langue de l'avatar. Voir voices.md - Écrire le script — Structurez 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 jusqu'à 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 (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 modèles | templates.md |
| Créer un avatar à partir d'une photo | photo-avatars.md |
| Vérifier le statut / télécharger | video-status.md |
| Télécharger des ressources (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, écrivez 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 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 en lot 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 de
avatar_id - references/voices.md - Lister les voix, locales, vitesse/tonalité
- references/scripts.md - Écrire 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 - Listage des modèles et remplacement de variables
- references/photo-avatars.md - Créer des avatars à partir de photos
- references/webhooks.md - Points de terminaison et événements 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 d'aspect
- references/quota.md - Système de crédits et limites d'utilisation
Bonnes pratiques
- Prévisualiser les avatars avant de générer — Téléchargez
preview_image_urlpour que l'utilisateur puisse voir l'avatar avant de s'engager - Utiliser la voix par défaut de l'avatar — La plupart des avatars ont un
default_voice_idpré-correspondant pour des résultats naturels - Repli : faire correspondre le genre manuellement — Si aucune voix par défaut, assurez-vous que les genres de l'avatar et de la voix correspondent
- Utiliser le mode test pour le développement — Définissez
test: truepour éviter de consommer des crédits (la sortie sera filigranée) - Définir des délais d'attente généreux — La génération vidéo prend souvent 5 à 15 minutes, parfois plus
- Valider les entrées — Vérifiez que les identifiants d'avatar et de voix existent avant de générer