HeyGen MP3 → MP4 (Usage Unique)
Prenez un fichier MP3 vocal, recevez une vidéo MP4 d'avatar HeyGen avec synchronisation labiale. Rien d'autre.
Ce skill existe parce que le skill existant heygen-short-video nécessite un plan de production complet + SRT + segments découpés — trop lourd quand l'utilisateur a juste un fichier vocal finalisé et veut une vidéo "talking-head".
Pourquoi hybride REST + MCP (pas seulement MCP)
Les versions antérieures de ce skill imposaient "MCP uniquement — ne jamais appeler REST." Cette règle n'est plus réalisable depuis la refonte MCP HeyGen de 2026 : le serveur MCP expose seulement create_video_from_avatar, get_video, create_lipsync, list_avatar_looks, etc. — il n'y a plus d'outil de téléversement d'actifs. Pour un lip-sync à partir d'un MP3 local, l'API nécessite toujours soit un audioAssetId (actif téléversé) soit un audioUrl (URL HTTPS publique). Héberger une URL publique est fragile (liens morts, fuite), donc nous utilisons l'endpoint REST de téléversement documenté via un helper léger, puis continuons via MCP pour la création vidéo, le polling et le téléchargement.
Contraintes strictes
| Contrainte | Valeurs autorisées |
|---|---|
| Téléversement actif | REST POST https://upload.heygen.com/v1/asset via scripts/upload_asset.py (utilise HEYGEN_API_KEY) |
| Création vidéo / statut / liste | HeyGen MCP uniquement (mcp__heygen__create_video_from_avatar, mcp__heygen__get_video) |
| ID look avatar | Un des IDs dans la variable d'environnement HEYGEN_AVATAR_LOOKS (liste blanche séparée par des virgules) |
| ID voix (uniquement si le chemin MCP force TTS) | HEYGEN_VOICE_ID depuis .env (aucun autre ID de voix n'est autorisé) |
| Durée MP3 | ≤ 300 secondes (5 minutes). Échouez rapidement si plus long ; ne pas diviser automatiquement |
| Ratio d'aspect (énumération MCP) | 9:16 par défaut (TikTok / Reels). 16:9 seulement lorsque l'orchestrateur parent le remplace |
| Résolution (énumération MCP) | 720p par défaut (donne 720×1280 pour 9:16, 1280×720 pour 16:9) |
Pour le lip-sync MP3, le type de voix est audio et audioAssetId est fourni — voiceId n'est pas envoyé. La liste blanche voice_id ci-dessus n'a d'importance que si une future signature MCP en exige un.
Entrées
- Chemin MP3 (obligatoire) — chemin absolu vers le fichier vocal.
- ID look avatar (optionnel) — un des IDs autorisés. Si omis, choisissez aléatoirement dans l'ensemble autorisé pour que la variété visuelle émerge entre les exécutions.
- Chemin de sortie (optionnel) — par défaut
workspace/heygen-clips/<nom-mp3>/<nom-mp3>_<AAAAMMJJ-HHMMSS>.mp4relatif à la racine du projet. - Ratio d'aspect (optionnel) —
9:16(par défaut) ou16:9.
Workflow
Suivez ces étapes dans l'ordre. Chaque étape a une condition d'arrêt ; ne continuez pas après une étape échouée.
0. Vérification d'authentification (premier appel uniquement)
Le serveur MCP HeyGen utilise OAuth. Lors d'une nouvelle session, seuls mcp__heygen__authenticate et mcp__heygen__complete_authentication sont exposés ; les vrais outils (create_video_from_avatar, get_video, …) apparaissent après la fin de l'authentification. Si la session n'a aucun de ces outils chargés, appelez mcp__heygen__authenticate et montrez l'URL d'autorisation retournée à l'utilisateur. Il clique → le navigateur peut afficher "erreur de connexion" sur le rappel localhost (c'est normal) → il colle l'URL de rappel complète, vous appelez mcp__heygen__complete_authentication. Une fois que les outils post-authentification apparaissent dans la liste des outils différés, continuez.
1. Validez le MP3
uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py "<chemin_mp3>"
Affiche OK <secondes> / TOO_LONG <secondes> / MISSING. Code de sortie 0 = OK, non nul = arrêt.
Si TOO_LONG : dites à l'utilisateur la durée et que HeyGen limite une seule vidéo à ~5 min, et suggérez le skill existant heygen-short-video (qui découpe). Ne continuez pas.
2. Choisissez le look avatar
Lisez HEYGEN_AVATAR_LOOKS (liste blanche séparée par des virgules) :
HEYGEN_AVATAR_LOOKS=$(
grep -h '^HEYGEN_AVATAR_LOOKS=' .env.local .env 2>/dev/null \
| head -1 | cut -d'=' -f2- | tr -d '"' | tr -d "'"
)
echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
Piège des placeholders — claudeclaw-os/.env.local contient des stubs placeholder (avatar_look_id_1,avatar_look_id_2). Les vraies valeurs se trouvent souvent dans ~/Documents/GitHub/hoang-ai-marketing/.env :
grep '^HEYGEN_AVATAR_LOOKS=' ~/Documents/GitHub/hoang-ai-marketing/.env
Si la valeur correspond à ^(your_|avatar_look_id_|placeholder), traitez-la comme manquante et retombez sur le .env du dépôt marketing. Si les deux sont placeholder/manquants, arrêtez-vous et demandez à l'utilisateur de remplir de vrais IDs.
Dites à l'utilisateur quel look avatar vous avez choisi avant de continuer — il voudra peut-être le remplacer.
3. Téléversez le MP3 en tant qu'actif HeyGen (REST)
uv run .claude/skills/heygen-mp3-to-mp4/scripts/upload_asset.py "<chemin_mp3>"
# → affiche "OK <asset_id>" en cas de succès
Le helper gère l'en-tête X-Api-Key, choisit le bon Content-Type pour l'extension audio, et résout HEYGEN_API_KEY dans cet ordre : indicateur --key-file → variable d'environnement HEYGEN_API_KEY → .env.local → .env → ~/Documents/GitHub/hoang-ai-marketing/.env. Les stubs placeholder (your_*) sont ignorés automatiquement.
Capturez l'asset_id imprimé sur la sortie standard.
4. Générez la vidéo avatar (MCP)
Appelez mcp__heygen__create_video_from_avatar avec le nouveau schéma (l'ancienne forme dimension: {width, height} a disparu — l'outil prend maintenant les énumérations aspectRatio + resolution) :
avatarId: <choisi dans la liste blanche>
audioAssetId: <de l'étape 3>
aspectRatio: "9:16" # ou "16:9" lorsque le parent remplace
resolution: "720p" # 720p · 1080p · 4k
title: "<nom-mp3>-<horodatage>"
Capturez le video_id retourné (le statut sera initialement waiting).
Pourquoi audio (pas texte) : la synchronisation labiale à partir d'un MP3 existant nécessite que HeyGen consomme l'audio directement. Envoyer un script + voiceId ici ferait passer HeyGen en mode TTS et ignorerait le MP3 téléversé.
5. Interrogez jusqu'à ce que terminé
Appelez mcp__heygen__get_video avec le video_id toutes les ~10–15 secondes. Statuts :
waiting/processing/pending→ continuez à interrogercompleted→ récupérezvideo_urldepuis la réponse et continuezfailed→ arrêtez, montrezfailure_messageà l'utilisateur
Limitez l'attente à ~10 minutes ; si toujours en traitement, dites-le à l'utilisateur et laissez-le décider.
Astuce zsh pour les boucles d'interrogation — le nom de variable status est en lecture seule dans zsh. Si vous écrivez status=$(…) dans une boucle d'interrogation, le script plante avec read-only variable: status. Utilisez un nom différent (vstate, phase, ready).
6. Téléchargez le MP4
uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py "<video_url>" "<chemin_sortie>"
Téléchargement HTTPS simple de l'URL retournée par HeyGen — pas un appel API pour créer ou modifier une vidéo.
7. Rapportez
Dites trois choses à l'utilisateur en une réponse courte :
- chemin de sortie du MP4
- quel look avatar a été utilisé
- durée et taille du fichier du résultat
Exemple
Utilisateur : tạo video heygen từ mp3 workspace/audio/episode-3.mp3
Vous :
- Vérification d'authentification → si les outils HeyGen sont présents, sautez ; sinon
mcp__heygen__authenticate+ terminez le flux OAuth. check_duration.py workspace/audio/episode-3.mp3→OK 87.4- Choix aléatoire dans
HEYGEN_AVATAR_LOOKS(ex.66e75e22e6584bbdaa56a19088286dc8). Dites-le. upload_asset.py workspace/audio/episode-3.mp3→OK 36922ca92326480f8dbb0f57fae1a144mcp__heygen__create_video_from_avatar(avatarId=…, audioAssetId=…, aspectRatio="9:16", resolution="720p", title="episode-3-…")→video_id: 874793a8…- Interrogez
mcp__heygen__get_videotoutes les ~15s jusqu'àcompleted→ récupérezvideo_url download_video.py <url> workspace/heygen-clips/episode-3/episode-3_20260510-143022.mp4- Rapportez chemin, ID look, durée.
Ce que ce skill ne fait PAS délibérément
- N'écrit/ne transcrit pas de SRT (c'est
mkt-ai-video-extract-srt-segment). - Ne planifie pas de visuels, de b-roll, de segments (c'est
mkt-plan-short-video-edit-16-9). - Ne découpe pas de MP3 (c'est
heygen-short-videoavecsplit_audio.py). - Ne compose pas avec Remotion ou HyperFrames (c'est l'orchestrateur parent).
Si l'utilisateur veut l'un des éléments ci-dessus, orientez-le vers le bon skill au lieu d'étendre celui-ci.
Modes d'échec et messages
| Symptôme | Que dire à l'utilisateur |
|---|---|
| Fichier MP3 manquant | MP3 không tìm thấy ở <path>. Kiểm tra lại đường dẫn. |
| MP3 > 300s | MP3 dài <X>s, vượt giới hạn 5 phút của HeyGen. Dùng skill heygen-short-video (có chunking) thay thế. |
| HeyGen MCP non authentifié | Montrez l'URL mcp__heygen__authenticate, demandez à l'utilisateur d'autoriser, puis mcp__heygen__complete_authentication. |
HEYGEN_API_KEY introuvable / placeholder | Không tìm thấy HEYGEN_API_KEY. Helper đã thử .env.local, .env, và ~/Documents/GitHub/hoang-ai-marketing/.env. Bạn cần thêm key thật (không phải stub your_*) vào 1 trong các file đó. |
HEYGEN_AVATAR_LOOKS est un placeholder (avatar_look_id_1,…) | Même repli que pour la clé API — lisez depuis le dépôt marketing, ou demandez à l'utilisateur de remplir de vrais IDs d'avatar. |
| HeyGen retourne échec | HeyGen render failed: <failure_message>. Có thể avatar look bị xoá hoặc audio asset không hợp lệ. |
| Crédits épuisés | Montrez l'erreur de HeyGen — il n'y a pas d'outil get_remaining_credits exposé dans cette version du serveur. Dirigez l'utilisateur vers https://app.heygen.com/billing. |
Nom d'outil introuvable (upload_asset / generate_avatar_video / get_avatar_video_status) | Anciens noms MCP — remplacés par téléversement REST + create_video_from_avatar + get_video. Mettez à jour tout appelant utilisant encore les anciens noms. |