Traduction Vidéo HeyGen
Traduisez et doublez une vidéo existante dans plus de 175 langues. Le système clone la voix du présentateur dans la langue cible, resynchronise ses lèvres sur le nouvel audio et retourne une vidéo entièrement doublée. Vous fournissez une vidéo source et une langue cible — le moteur gère la transcription, la traduction, le clonage vocal, la synchronisation labiale et (optionnellement) les sous-titres incrustés.
Ceci n'est pas une génération de nouvelle vidéo. Le présentateur, la performance, le cadrage et les éléments de marque de la vidéo originale sont conservés. La traduction se superpose à ce qui existe déjà.
Comportement Utilisateur
- Soyez concis. Ne déversez pas d'identifiants de traduction, de payloads API bruts ou de JSON d'état dans le chat. Rapportez le résultat (lien vidéo, langue), pas la tuyauterie.
- Pas de jargon interne. Ne dites pas "polling", "video_translation_id", "asset_id", "endpoint v3". Dites "traduction en cours", "presque terminé", "votre fichier".
- Polling silencieux. Surveillez les traductions longue durée en arrière-plan et ne parlez que lorsque (a) le résultat est livré, (b) un blocage de >5 min (une mise à jour), (c) une défaillance définitive.
- Un résultat, un message. Lorsque la vidéo est terminée, envoyez le lien plus un résumé d'une ligne (langue cible, durée, mode). Pas tous les champs API.
- Ne décrivez pas le choix du transport. MCP vs CLI vs plugin OpenClaw est interne. Choisissez en silence au début de la session ; ne mentionnez jamais celui utilisé.
- Communiquez dans la langue de l'utilisateur. Détectez-la à partir de son premier message. Réponses, confirmations et questions dans sa langue. Les directives CLI/API techniques restent en anglais.
Détection du Mode API
Choisissez un transport au début de la session. Ne mélangez jamais, ne changez jamais en cours de session, ne décrivez jamais le choix.
Détectez dans cet ordre :
- Mode plugin OpenClaw — Si vous êtes dans OpenClaw et que l'outil
video_generateexpose un modèle de traduction HeyGen, privilégiez-le. Actuellement, le plugin génère des vidéos mais n'expose pas la traduction directement — passez au niveau suivant jusqu'à ce que HeyGen fournisse la traduction viavideo_generate. - Mode CLI (surcharge de clé API) — Si
HEYGEN_API_KEYest définie dans l'environnement ET queheygen --versionsort avec 0, utilisez CLI. La présence d'une clé API est un signal explicite que l'utilisateur souhaite un accès direct à l'API. - Mode MCP — Pas de
HEYGEN_API_KEYET les outils MCP HeyGen sont visibles (mcp__heygen__*). Authentification OAuth, fonctionne avec les crédits du plan de l'utilisateur. - Mode CLI (repli) — Outils MCP non disponibles ET
heygen --versionsort avec 0. Authentification viaheygen auth login. - Aucun des deux — dites-le à l'utilisateur une fois : "Pour utiliser cette compétence, connectez le serveur MCP HeyGen ou installez la CLI HeyGen :
curl -fsSL https://static.heygen.ai/cli/install.sh | bashpuisheygen auth login."
Vérification d'authentification (à exécuter avant tout appel API)
Après la détection du mode, vérifiez que l'authentification fonctionne avant d'entrer dans la Phase 1. Cela évite de perdre du temps à recueillir les entrées de l'utilisateur pour ensuite rencontrer une erreur d'authentification lors de la soumission.
- Mode MCP : l'authentification est gérée par OAuth — aucune vérification nécessaire.
- Mode CLI : exécutez
heygen auth status(en silence). S'il sort avec 0, continuez. S'il sort non nul (pas de clé, expirée, invalide) :- Demandez à l'utilisateur : "J'ai besoin de votre clé API HeyGen pour continuer. Vous pouvez en obtenir une depuis https://app.heygen.com/settings?nav=API — collez-la ici."
- Une fois fournie, persistez-la :
echo "<clé>" | heygen auth login(écrit dans~/.heygen/credentials, persiste entre les sessions). - Vérifiez :
heygen auth status. Si cela échoue toujours, affichez l'erreur et arrêtez.
Ceci est une configuration unique. Une fois que heygen auth login a persisté la clé, les sessions futures la récupéreront automatiquement. Ne demandez pas à nouveau si heygen auth status réussit.
Règles strictes :
- N'appelez jamais
curl api.heygen.com/...Chaque opération de cette compétence a une commande CLI et (lorsque pris en charge) un outil MCP. Utilisez-les. - Mode MCP : uniquement les outils
mcp__heygen__*. Si la traduction n'est pas encore exposée via MCP, passez au CLI pour les opérations de traduction spécifiquement. Ne synthétisez pas d'appels HTTP bruts. - Mode CLI : uniquement les commandes
heygen .... Exécutezheygen video-translate --helpetheygen video-translate <sous-commande> --helppour découvrir les arguments. Utilisez--request-schemapour voir la structure JSON complète de toute commande de création. - Les opérations ci-dessous montrent MCP et CLI côte à côte — lisez uniquement la colonne correspondant à votre mode détecté.
Noms des outils MCP (mode MCP uniquement)
create_video_translation (langue unique). Les traductions multi-langues et les relectures ne sont pas encore exposées via MCP — passez au CLI pour celles-ci. Exécutez la liste des outils mcp__heygen__* au début de la session pour confirmer ce qui est disponible ; la surface d'outils évolue.
Groupes de commandes CLI (mode CLI uniquement)
heygen video-translate
├── languages list # langues cibles prises en charge
├── create # soumettre un travail de traduction (simple ou par lots)
├── get <id> # vérifier l'état / obtenir le résultat
├── list # lister les traductions passées
├── update # mettre à jour les métadonnées du travail
├── delete # supprimer un travail
└── proofreads
├── create # extraire les sous-titres modifiables avant le rendu final
├── get <id> # vérifier l'état de la session de relecture
├── srt get <id> # télécharger le SRT extrait
├── srt update <id> # télécharger le SRT modifié
└── generate <id> # rendre la vidéo finale à partir du SRT approuvé
heygen asset create --file <chemin> # pour les téléversements de vidéos source locales (max 32 Mo)
Chaque commande prend en charge --help. Utilisez --request-schema sur toute commande create pour voir le corps JSON complet. Sortie CLI : JSON sur stdout, enveloppe {error:{code,message,hint}} sur stderr, codes de sortie 0 ok · 1 API · 2 utilisation · 3 auth · 4 timeout. Ajoutez --wait sur create pour bloquer jusqu'à la fin du travail (timeout par défaut 20 min).
📖 Correspondance détaillée des erreurs CLI/MCP → action → references/troubleshooting.md
Workflow par Défaut
La compétence exécute quatre phases. La Phase 1 (Découverte) est le seul endroit où vous posez des questions. La Phase 2 (Pré-vol) est silencieuse. La Phase 3 (Soumettre + Surveiller) est silencieuse. La Phase 4 (Livrer) est un message court.
Phase 1 — Découverte — recueillez le minimum d'entrées nécessaires de l'utilisateur
Phase 2 — Pré-vol — validez la langue, classez le contenu, définissez les indicateurs
Phase 3 — Soumettre + Surveiller — lancez, surveillez en arrière-plan, ne parlez qu'en cas de fin/d'échec
Phase 4 — Livrer — publiez le résultat avec un résumé d'une ligne
Phase 1 — Découverte
Ne demandez que ce que vous n'avez pas déjà. Communiquez dans la langue de l'utilisateur. N'exécutez jamais de formulaire. Une ou deux questions par tour, maximum.
Entrées obligatoires (bloquez jusqu'à les obtenir) :
- Vidéo source. URL publique, chemin de fichier local ou un asset_id HeyGen d'une étape précédente. Si l'utilisateur ne l'a pas fournie, demandez : "Quelle est la vidéo source — une URL, un chemin de fichier ou un asset HeyGen existant ?"
- Langue(s) cible(s). Demandez sous forme de question ouverte dans la langue de l'utilisateur : "Dans quelle langue dois-je la traduire ?" Ne présentez PAS un sélecteur ou des choix prédéfinis — laissez l'utilisateur taper librement. Il peut vouloir une langue, plusieurs ou une variante régionale spécifique. Acceptez ce qu'il donne et validez par rapport à la liste canonique des langues lors de la Phase 2.
Entrées importantes (demandez si non fournies, avec des valeurs par défaut intelligentes) :
- Nombre d'intervenants. Un seul intervenant est la valeur par défaut et ce que la plupart des utilisateurs ont. Demandez une fois lorsque c'est ambigu : "Combien d'intervenants distincts y a-t-il dans la vidéo ?" Un mauvais nombre d'intervenants est le facteur n°1 de dégradation de la qualité — la confusion entre intervenants crée des échanges de voix en milieu de traduction. Ne sautez pas cette étape pour le contenu multipersonne.
- Type de contenu. Vous n'avez généralement pas besoin de demander — déduisez-le de la vidéo et confirmez. Les cinq profils ci-dessous couvrent ~95% des cas. Ne demandez que si c'est vraiment ambigu.
- Préférence de sous-titres. Activé par défaut pour les têtes parlantes et le contenu d'entreprise ; désactivé par défaut pour les podcasts/audio uniquement. Si vous changez la valeur par défaut, mentionnez-le brièvement dans la Phase 4.
- Flexibilité de durée. Demandez : "La vidéo traduite doit-elle avoir exactement la même longueur que l'originale, ou peut-elle être légèrement plus longue/plus courte ? Autoriser une flexibilité semble généralement plus naturel — le discours traduit a suffisamment d'espace pour être prononcé à un rythme confortable au lieu d'être accéléré ou compressé." Recommandation par défaut : flexible (
enable_dynamic_duration: true). Ne définissez surfalseque lorsque l'utilisateur a besoin d'un timing image par image (par exemple, synchronisation avec une timeline, un emplacement publicitaire ou une piste audio externe).
Optionnel (ne demandez que si pertinent) :
- Glossaire / termes à ne pas traduire. Pour le contenu d'entreprise ou technique, demandez : "Y a-t-il des noms de produits, des noms d'entreprise ou du jargon que je dois garder dans la langue d'origine ?" HeyGen n'accepte actuellement pas de glossaire strict, cela devient donc une directive pour l'étape de relecture (Phase 3-Relecture) lorsque les enjeux sont élevés.
- Traduction partielle. Si l'utilisateur mentionne un segment spécifique ("juste l'introduction", "de 1:30 à 4:00"), capturez
start_timeetend_timeen secondes. - Relecture avant le rendu final ? Désactivée par défaut (plus rapide, moins d'approbations). Activée par défaut pour : les vidéos longues (>3 min), le contenu d'entreprise/de marque, le contenu juridique/médical/éducatif à enjeux élevés, les langues que l'utilisateur lit couramment (pour qu'il puisse vérifier). Demandez : "Voulez-vous revoir et modifier les sous-titres avant le rendu final ? Cela ajoute environ 5 minutes mais vous permet de corriger les termes incorrects."
📖 Pièges paires de langues (registres de politesse, langues RTL, compression tonale, limite de synchronisation labiale) → references/language-locale-guide.md
Phase 2 — Pré-vol
Silencieuse. Aucun bavardage destiné à l'utilisateur. Trois vérifications, dans l'ordre.
Vérification 2a : Validation de la langue.
MCP : list_video_translation_languages() (si exposé). Sinon CLI.
CLI : heygen video-translate languages list | jq -r '.data.languages[]'
La liste contient des chaînes exactes ("Spanish (Spain)", "Chinese (Mandarin, Simplified)", "Arabic (Saudi Arabia)"). Faites correspondre l'entrée de l'utilisateur sans tenir compte de la casse à ces chaînes exactes. S'il dit "Espagnol", prenez "Spanish (Spain)" par défaut et confirmez dans la Phase 4. S'il dit "Chinois", prenez "Chinese (Mandarin, Simplified)" par défaut. S'il spécifie une région ("Espagnol mexicain"), faites correspondre ("Spanish (Mexico)"). Si aucune correspondance : demandez à l'utilisateur de choisir parmi les options les plus proches.
Vérification 2b : Routage de la vidéo source.
| Source donnée par l'utilisateur | Routage |
|---|---|
URL HTTPS publique (sans authentification, retourne un MIME vidéo sur HEAD) | Transmettez directement comme {type: "url", url: "..."} |
| URL avec authentification, 403, 404 ou réponse HTML | Dites-le à l'utilisateur, demandez une URL publique ou un fichier local |
| Chemin de fichier local | Téléversez via heygen asset create --file <chemin> (CLI) ou upload_asset (MCP). Max 32 Mo. Utilisez l'asset_id retourné comme {type: "asset_id", asset_id: "..."} |
| asset_id HeyGen existant | Transmettez directement comme {type: "asset_id", asset_id: "..."} |
📖 Cas limites du routage d'assets (fichiers très volumineux, URL pré-signées, sources avec authentification) → references/asset-routing.md
Vérification 2c : Profil de contenu.
Choisissez un profil en fonction de la source. Ne listez pas les cinq à l'utilisateur — proposez en silence et ne demandez que si la source est vraiment ambiguë (par exemple, une tête parlante avec beaucoup de musique où vous ne pouvez pas dire si l'amélioration de la parole aidera).
| Profil | Utiliser lorsque | Indicateurs |
|---|---|---|
| Tête parlante / présentateur (par défaut) | Une personne parle face à la caméra ; audio clair | mode: precision, enable_speech_enhancement: true, enable_caption: true, enable_dynamic_duration: true, keep_the_same_format: true |
| Podcast / audio uniquement | Le visuel est statique, n'a pas d'importance ou n'existe pas | mode: precision, translate_audio_only: true, enable_speech_enhancement: true, enable_caption: true |
| Musique / forte bande son | La musique de fond interfère avec la parole | mode: precision, disable_music_track: true, enable_speech_enhancement: true, enable_dynamic_duration: true, keep_the_same_format: true |
| Plusieurs intervenants | Deux intervenants distincts ou plus | Valeurs par défaut de tête parlante + speaker_num: <nombre>. Le nombre d'intervenants est OBLIGATOIRE ici — ne devinez pas. |
| Entreprise / de marque | Voix de marque, discipline de glossaire, enjeux élevés | Valeurs par défaut de tête parlante + (si l'utilisateur en a une) brand_voice_id. Envisagez fortement les relectures pour ce profil. |
Toujours :
mode: "precision"sauf si l'utilisateur demande explicitement "rapide" / "vite" / "vitesse".enable_dynamic_duration: définissez en fonction de la réponse de l'utilisateur à la question sur la flexibilité de durée dans la Phase 1. Par défauttrue(recommandé) — permet au discours traduit de respirer au lieu d'être compressé dans le timing exact de la source. Définissez surfalseuniquement lorsque l'utilisateur a explicitement besoin d'une sortie de longueur fixe. La compression tonale rend la flexibilité particulièrement importante pour en→zh, en→ja, en→ko (les langues asiatiques sont plus courtes) ; de→en, ja→en (plus longues) ; ar/he/ur (RTL + changements de registre).keep_the_same_format: truepour les traductions visuelles — préserve la résolution et le débit binaire de la source afin que la vidéo doublée corresponde au codage de l'original.enable_watermark: false(la valeur par défaut).
Phase 3 — Soumettre + Surveiller
Silencieuse. Travail en arrière-plan. Ne parlez que lorsque (a) une langue est terminée, (b) une langue est en échec définitif, (c) une vérification de progression après >5 min.
Branchement :
- Chemin standard (relecture = OFF) : soumettez les traductions, surveillez en arrière-plan, livrez.
- Chemin relecture (relecture = ON) : créez une session de relecture → téléchargez le SRT → l'utilisateur modifie ou vous aidez → téléchargez le SRT modifié → générez la version finale → surveillez en arrière-plan → livrez.
Chemin standard
Soumettez un travail par langue cible en utilisant la syntaxe par lots (--output-languages accepte plusieurs).
MCP (langue unique seulement au moment de la rédaction) :
create_video_translation(
video={type, url|asset_id},
output_languages=["Spanish (Spain)"],
mode="precision",
enable_speech_enhancement=true,
enable_caption=true,
enable_dynamic_duration=true,
keep_the_same_format=true,
speaker_num=<n>, # uniquement lorsque plusieurs intervenants sont connus
)
CLI :
heygen video-translate create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
--mode precision \
--ena
[suite tronquée pour la traduction]