Accueil › HeyGen › API

HeyGen API : guide complet pour développeurs

L’API HeyGen permet de générer programmatiquement des vidéos avec avatars IA, de traduire des vidéos dans 175+ langues avec lip-sync, de cloner des voix et de déployer des avatars interactifs en temps réel (LiveAvatar). Facturation pay-as-you-go à partir de 5 $, avec un système de crédits distinct des plans web.

Architecture et concepts clés

L’API HeyGen est un service indépendant du produit web. Vous pouvez souscrire un plan API sans avoir de plan web payant, et inversement. Les crédits API et les Premium Credits du plan web sont deux pools séparés : consommer des crédits API ne touche pas votre solde web, et vice versa.

L’API est RESTful et utilise des appels asynchrones pour la génération vidéo. Vous soumettez une requête de création, recevez un identifiant de job, puis interrogez le statut ou configurez un webhook pour être notifié quand la vidéo est prête. Le temps de génération typique est de 1 à 5 minutes pour les vidéos courtes, plus pour les vidéos longues ou en haute résolution.

Trois voies d’intégration

HeyGen propose trois chemins d’intégration distincts, chacun avec son propre mode d’authentification et de facturation :

API directe (Direct API). Authentification par clé API (X-Api-Key), générée depuis Settings → API dans votre dashboard HeyGen. L’usage est déduit de votre solde API, séparé du plan web. C’est le chemin standard pour les intégrations custom, les SaaS et les workflows automatisés.

MCP (Model Context Protocol). Intégration via le protocole MCP, utilisé pour connecter HeyGen à des agents IA comme Claude, Manus ou OpenAI. L’authentification se fait par écran de consentement (pas de clé API nécessaire). L’usage est déduit de vos Premium Credits web, pas du solde API. C’est le chemin le plus simple pour connecter HeyGen à un assistant IA conversationnel.

Skills. Modules pré-construits qui étendent les agents IA avec les capacités de génération vidéo HeyGen. Authentification par clé API, usage déduit du solde API. Les Skills sont des composants prêts à l’emploi pour des cas d’usage spécifiques (générer une vidéo depuis un prompt, traduire un contenu existant).

Tarification de l’API

Depuis début 2026, HeyGen a simplifié sa tarification API en adoptant un modèle pay-as-you-go. Vous rechargez votre portefeuille API avec le montant de votre choix (à partir de 5 $), et les crédits sont consommés à chaque usage. Des plans legacy (Pro à 99 $/mois, Scale à 330 $/mois) existent encore pour les utilisateurs qui y étaient abonnés, mais ne sont plus proposés aux nouveaux clients.

Coût par type d’opération

Les crédits API expirent 30 jours après leur émission. C’est un point critique à surveiller : si vous rechargez un gros montant sans l’utiliser dans le mois, vous perdez les crédits. HeyGen recommande de commencer avec un petit montant pour calibrer votre consommation avant de charger en volume.

La durée maximale par vidéo générée via API est de 30 minutes (sauf plan Enterprise). La résolution est de 1080p par défaut ; le 4K n’est disponible que pour les plans Enterprise API.

Plans legacy (encore actifs pour les abonnés existants)

Les anciens plans structurés sont dépréciés mais toujours actifs pour les utilisateurs qui maintiennent leurs paiements. Si un paiement échoue, le plan est annulé définitivement et ne peut plus être réactivé.

Principaux endpoints

L’API HeyGen couvre l’ensemble des fonctionnalités de la plateforme. Voici les catégories d’endpoints et leurs cas d’usage :

Génération de vidéos avatar

L’endpoint Generate Video est le point d’entrée principal. Vous spécifiez l’avatar (stock, Photo Avatar ou Digital Twin), le script, la voix, l’arrière-plan et les paramètres de mise en page. L’API retourne un identifiant de job que vous utilisez ensuite pour vérifier le statut et récupérer l’URL de la vidéo générée.

Le endpoint Generate Studio Video offre un contrôle plus granulaire : vous définissez les scènes individuellement, avec la possibilité de changer d’avatar, de voix ou d’arrière-plan entre les scènes.

Le endpoint Video Agent est la version automatisée : vous décrivez la vidéo souhaitée en langage naturel, et l’API génère automatiquement le script, la mise en page, le choix d’avatar et le rendu.

Traduction et doublage

L’endpoint Translate Video accepte un fichier vidéo ou une URL, une langue source, une langue cible, et retourne une vidéo traduite avec lip-sync et clonage vocal. Le coût est de 3 crédits par minute de vidéo source.

Des endpoints complémentaires permettent de vérifier le statut de la traduction, de générer un script de relecture (Proofread), de télécharger et uploader des fichiers SRT pour affiner la traduction, et de récupérer les sous-titres générés.

La fonctionnalité Proofread (relecture avant rendu final) est réservée aux plans Enterprise API. C’est une limitation importante : sur les plans standard, vous ne pouvez pas corriger la traduction avant le rendu.

Gestion des avatars

L’API permet de lister tous les avatars disponibles (stock et personnalisés), de créer des Photo Avatars (upload de photos, entraînement du modèle, génération de Looks), et de gérer les Digital Twins (création, vérification du statut, suppression).

La création de Digital Twins via API est réservée aux plans Enterprise. Sur les plans standard, les Digital Twins doivent être créés via l’interface web.

Text-to-Speech et voix

L’endpoint Text-to-Speech (nommé « Starfish ») génère de l’audio à partir de texte, avec accès aux 1 000+ voix IA de HeyGen. Vous pouvez aussi lister les voix compatibles, gérer le Brand Glossary (termes protégés, prononciations personnalisées) et lister les locales disponibles.

LiveAvatar (streaming temps réel)

LiveAvatar est une API de streaming en temps réel qui permet de déployer des avatars interactifs connectés à un LLM. L’avatar répond en temps réel aux inputs de l’utilisateur, avec lip-sync, gestes et expressions faciales synchronisés. C’est construit sur WebRTC pour une latence minimale.

Les endpoints couvrent la gestion de session (création, démarrage, fermeture), l’envoi de tâches (texte à prononcer), l’interruption, et le keep-alive. Les avatars LiveAvatar ont leur propre système de tarification, séparé des crédits API standard, avec des plans dédiés à partir de 49 $/mois par slot d’avatar.

Webhooks

L’API supporte les webhooks pour recevoir des notifications asynchrones quand une vidéo est prête, quand une traduction est terminée, ou quand un avatar a été créé. Vous pouvez lister, ajouter, modifier et supprimer des endpoints webhook, ainsi que lister les événements disponibles.

Guide de démarrage rapide

1. Créer un compte et générer une clé API

Créez un compte sur heygen.com. Allez dans Settings → API → Generate New Key. Votre clé API est un token que vous inclurez dans le header X-Api-Key de chaque requête. Gardez cette clé confidentielle : elle donne accès à votre portefeuille de crédits.

2. Recharger votre portefeuille

Depuis votre dashboard API, rechargez votre portefeuille avec le montant souhaité (minimum 5 $). Chaque dollar vous donne environ 1 crédit (le taux exact dépend de votre plan et des éventuelles promotions). Les crédits expirent après 30 jours.

3. Première génération de vidéo

Voici un exemple simplifié en Python pour générer une vidéo avatar :

import requests

url = "https://api.heygen.com/v2/video/generate"
headers = {
    "X-Api-Key": "VOTRE_CLE_API",
    "Content-Type": "application/json"
}
payload = {
    "video_inputs": [{
        "character": {
            "type": "avatar",
            "avatar_id": "AVATAR_ID",
            "avatar_style": "normal"
        },
        "voice": {
            "type": "text",
            "input_text": "Bonjour, bienvenue sur notre plateforme.",
            "voice_id": "VOICE_ID"
        }
    }],
    "dimension": {"width": 1920, "height": 1080}
}

response = requests.post(url, json=payload, headers=headers)
video_id = response.json()["data"]["video_id"]
print(f"Vidéo en cours de génération : {video_id}")

Vous vérifiez ensuite le statut avec l’endpoint GET /v1/video_status.get?video_id={video_id}. Quand le statut passe à « completed », l’URL de téléchargement est incluse dans la réponse. Alternativement, configurez un webhook pour être notifié automatiquement.

4. Configurer un webhook

Enregistrez votre endpoint webhook via l’API (POST /v1/webhook/endpoint.add), et HeyGen enverra une requête POST à votre URL chaque fois qu’une vidéo est prête. C’est la méthode recommandée pour les workflows de production, car elle évite le polling répétitif.

Cas d’usage API typiques

Vidéos de prospection personnalisées

L’usage le plus courant de l’API HeyGen : générer automatiquement des vidéos personnalisées pour la prospection commerciale. Votre CRM déclenche un appel API pour chaque prospect, en injectant le nom du prospect, le nom de son entreprise et un message adapté dans le script. L’avatar du commercial livre un message personnalisé en vidéo, ce qui génère des taux d’ouverture et de réponse nettement supérieurs à un email textuel.

Localisation de contenu à grande échelle

L’endpoint de traduction vidéo permet d’automatiser la localisation. Un pipeline typique : une vidéo marketing est créée manuellement, puis l’API la traduit automatiquement dans 10, 20 ou 30 langues. Chaque version est routée vers le canal approprié (site web localisé, réseaux sociaux régionaux, LMS).

Agents conversationnels vidéo

Via LiveAvatar, les entreprises déploient des agents de support ou de vente vidéo qui interagissent en temps réel. L’avatar est connecté à un LLM (par exemple Claude ou GPT) qui gère la conversation, et LiveAvatar se charge du rendu visuel. C’est utilisé pour du support client 24/7, des kiosques interactifs en point de vente, ou des assistants virtuels sur des sites e-commerce.

Intégration SaaS

Les plateformes SaaS intègrent l’API HeyGen pour offrir de la génération vidéo en tant que fonctionnalité native. Par exemple, un outil de formation en ligne peut permettre à ses utilisateurs de créer des vidéos de cours avec un avatar IA directement depuis l’interface de la plateforme, sans jamais visiter HeyGen.

Limites et contraintes techniques

Expiration des crédits. Les crédits API expirent 30 jours après leur émission. Pas de report. C’est la contrainte la plus importante à anticiper : rechargez en fonction de votre consommation réelle, pas en prévision.

Durée maximale. 30 minutes par vidéo générée (sauf Enterprise). Pour des contenus plus longs, vous devez découper le script en segments et assembler les vidéos en post-production.

Résolution. 1080p maximum sur les plans standard. Le 4K est réservé à Enterprise.

Digital Twin via API. La création de Digital Twins (clones vidéo personnalisés) via API est uniquement disponible sur le plan Enterprise. Sur les plans standard, vous créez les Digital Twins via l’interface web, puis vous les utilisez via l’API.

Proofread via API. La relecture de traduction (Proofread) est aussi réservée à Enterprise. Sur les plans standard, les traductions sont générées sans possibilité de correction programmatique.

Rate limiting. L’API applique des limites de débit qui varient selon votre plan. Les requêtes excessives retournent un code 429. Implémentez un backoff exponentiel dans votre code.

Pas de SDKs communautaires maintenus. HeyGen fournit des SDKs officiels pour Python et Node.js, et l’API REST est accessible depuis n’importe quel langage. Mais il n’y a pas d’écosystème de SDKs communautaires aussi riche que pour des API comme celles des grands LLM.

LiveAvatar : avatars interactifs en temps réel

LiveAvatar mérite une section dédiée car c’est une fonctionnalité unique sur le marché. C’est une API de streaming qui rend un avatar IA en temps réel, avec un délai de latence suffisamment bas pour soutenir une conversation naturelle.

L’architecture repose sur WebRTC : le flux vidéo de l’avatar est streamé directement vers le navigateur ou l’application de l’utilisateur final. Le développeur connecte LiveAvatar à un LLM backend (pour la logique conversationnelle) et à un moteur TTS (HeyGen fournit le sien, ou vous pouvez utiliser un moteur tiers comme ElevenLabs).

Les cas d’usage concrets incluent les agents de service client vidéo 24/7, les tuteurs éducatifs interactifs, les hôtes virtuels pour événements en ligne, et les kiosques de vente interactifs en magasin.

La tarification LiveAvatar est séparée : des plans dédiés commencent à 49 $/mois par slot d’avatar, avec une facturation à la minute de streaming (1 crédit LiveAvatar = 30 secondes à 1 minute de streaming selon la méthode d’intégration).

Intégration MCP : connecter HeyGen aux agents IA

Le protocole MCP (Model Context Protocol) permet de connecter HeyGen à des agents IA comme Claude, Manus ou les assistants OpenAI. L’utilisateur autorise l’accès via un écran de consentement, et l’agent peut ensuite générer des vidéos, traduire du contenu et gérer des avatars de manière conversationnelle.

L’usage MCP est facturé sur les Premium Credits de votre plan web HeyGen (pas sur le solde API). Cela signifie que si vous avez un plan Creator avec 200 Premium Credits, les vidéos générées via MCP puisent dans ce même pool.

C’est le chemin d’intégration le plus simple pour les équipes qui utilisent déjà des agents IA et qui veulent ajouter la génération vidéo comme capacité sans développer d’intégration custom. Vous pouvez par exemple demander à un agent Claude : « Crée une vidéo de 60 secondes avec l’avatar professionnel, en français, expliquant notre nouveau produit », et l’agent orchestre l’appel HeyGen en arrière-plan.

Optimiser les coûts API

Rechargez par petits montants. Puisque les crédits expirent à 30 jours, rechargez en fonction de votre consommation mensuelle réelle. Mieux vaut recharger 50 $ par mois que 200 $ en une fois si vous n’utilisez que 50 crédits.

Utilisez Avatar III pour le volume. Avatar III coûte 1 crédit/minute contre 6 crédits/minute pour Avatar IV. Pour du contenu interne, de la formation ou des vidéos à rotation rapide, Avatar III offre un rapport qualité-prix imbattable.

Mettez en cache les vidéos récurrentes. Si vous générez des vidéos d’onboarding ou des explainers produit qui changent rarement, stockez les vidéos générées et servez-les depuis votre propre CDN plutôt que de les régénérer.

Scripts courts et optimisés. Les crédits sont facturés à la minute d’output. Un script concis de 45 secondes coûte moins qu’un script de 2 minutes avec le même message. Travaillez vos scripts pour maximiser l’impact par seconde.

Batch intelligemment. Pour les campagnes de personnalisation, regroupez vos requêtes et gérez la file d’attente avec des webhooks plutôt que de poller le statut en boucle (ce qui peut déclencher du rate limiting).

Testez avec des Photo Avatars. Les Photo Avatars consomment moins de crédits que les Digital Twins ou Avatar IV pour la génération. Utilisez-les en phase de prototypage et de test.

Questions fréquentes sur l’API HeyGen