HeyGen MP3 → MP4 (Propósito Único)
Pegue uma narração MP3, devolva um vídeo MP4 de avatar HeyGen com sincronização labial. Nada mais.
Este skill existe porque o skill heygen-short-video existente exige um plano de produção completo + SRT + segmentos divididos — exagero quando o usuário só tem uma narração pronta e quer um vídeo de apresentador.
Por que híbrido REST + MCP (e não apenas MCP)
Versões anteriores deste skill impunham "Apenas MCP — nunca chame REST." Essa regra não é mais viável desde a reformulação do MCP do HeyGen em 2026: o servidor MCP expõe apenas create_video_from_avatar, get_video, create_lipsync, list_avatar_looks, etc. — não há mais ferramenta de upload de assets. Para sincronizar lábios a partir de um MP3 local, a API ainda exige um audioAssetId (asset carregado) ou um audioUrl (URL HTTPS pública). Hospedar uma URL pública é frágil (quebra de links, vazamento), então usamos o endpoint REST de upload documentado através de um auxiliar simples, e depois continuamos via MCP para criação de vídeo, polling e download.
Restrições rígidas
| Restrição | Valores permitidos |
|---|---|
| Upload de asset | REST POST https://upload.heygen.com/v1/asset via scripts/upload_asset.py (usa HEYGEN_API_KEY) |
| Criação / status / listagem de vídeo | Apenas MCP do HeyGen (mcp__heygen__create_video_from_avatar, mcp__heygen__get_video) |
| ID do avatar | Um dos IDs presentes na variável de ambiente HEYGEN_AVATAR_LOOKS (lista separada por vírgulas) |
| ID de voz (apenas se o caminho MCP forçar TTS) | HEYGEN_VOICE_ID do .env (nenhum outro ID de voz é permitido) |
| Duração do MP3 | ≤ 300 segundos (5 minutos). Falhe rapidamente se for maior; não divida automaticamente |
| Proporção de tela (enum MCP) | 9:16 padrão (TikTok / Reels). 16:9 apenas quando o orquestrador pai sobrescrever |
| Resolução (enum MCP) | 720p padrão (produz 720×1280 para 9:16, 1280×720 para 16:9) |
Para sincronização labial com MP3, o tipo de voz é audio e o audioAssetId é fornecido — voiceId não é enviado. A lista de voice_id permitida acima só importa se uma futura assinatura MCP exigir um.
Entradas
- Caminho do MP3 (obrigatório) — caminho absoluto para o arquivo de narração.
- ID do avatar (opcional) — um dos IDs permitidos. Se omitido, escolha aleatoriamente do conjunto permitido para gerar variedade visual entre execuções.
- Caminho de saída (opcional) — padrão:
workspace/heygen-clips/<nome-base-mp3>/<nome-base-mp3>_<AAAAMMDD-HHMMSS>.mp4relativo à raiz do projeto. - Proporção de tela (opcional) —
9:16(padrão) ou16:9.
Fluxo de trabalho
Siga estes passos em ordem. Cada passo tem uma condição de parada; não prossiga após um passo com falha.
0. Verificação de autenticação (apenas na primeira chamada)
O servidor MCP do HeyGen usa OAuth. Em uma sessão nova, apenas mcp__heygen__authenticate e mcp__heygen__complete_authentication estão expostos; as ferramentas reais (create_video_from_avatar, get_video, …) aparecem após a autenticação ser concluída. Se a sessão não tiver nenhuma dessas ferramentas carregadas, chame mcp__heygen__authenticate e exiba a URL de autorização retornada para o usuário. Eles clicam → o navegador pode mostrar "erro de conexão" no callback localhost (isso é esperado) → eles colam a URL de callback completa de volta, você chama mcp__heygen__complete_authentication. Assim que as ferramentas pós-autenticação aparecerem na lista de ferramentas diferidas, continue.
1. Validar o MP3
uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py "<mp3_path>"
Imprime OK <segundos> / TOO_LONG <segundos> / MISSING. Código de saída 0 = OK, não-zero = pare.
Se TOO_LONG: informe ao usuário a duração e que o HeyGen limita um único vídeo a ~5 min, e sugira o skill heygen-short-video existente (que divide em partes). Não prossiga.
2. Escolher o avatar
Leia HEYGEN_AVATAR_LOOKS (lista separada por vírgulas):
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]}'
Armadilha de placeholder — claudeclaw-os/.env.local vem com placeholders (avatar_look_id_1,avatar_look_id_2). Os valores reais geralmente estão em ~/Documents/GitHub/hoang-ai-marketing/.env:
grep '^HEYGEN_AVATAR_LOOKS=' ~/Documents/GitHub/hoang-ai-marketing/.env
Se o valor corresponder a ^(your_|avatar_look_id_|placeholder), trate como ausente e recorra ao .env do repositório de marketing. Se ambos forem placeholder/ausentes, pare e peça ao usuário para inserir IDs reais.
Informe ao usuário qual avatar foi escolhido antes de continuar — ele pode querer substituir.
3. Fazer upload do MP3 como asset HeyGen (REST)
uv run .claude/skills/heygen-mp3-to-mp4/scripts/upload_asset.py "<mp3_path>"
# → imprime "OK <asset_id>" em caso de sucesso
O auxiliar lida com o cabeçalho X-Api-Key, seleciona o Content-Type correto para a extensão de áudio e resolve HEYGEN_API_KEY nesta ordem: flag --key-file → env HEYGEN_API_KEY → .env.local → .env → ~/Documents/GitHub/hoang-ai-marketing/.env. Placeholders (your_*) são ignorados automaticamente.
Capture o asset_id impresso na saída padrão.
4. Gerar o vídeo do avatar (MCP)
Chame mcp__heygen__create_video_from_avatar com o novo esquema (o formato antigo dimension: {width, height} não existe mais — a ferramenta agora aceita enum aspectRatio + enum resolution):
avatarId: <escolhido da lista>
audioAssetId: <do passo 3>
aspectRatio: "9:16" # ou "16:9" quando o orquestrador pai sobrescrever
resolution: "720p" # 720p · 1080p · 4k
title: "<nome-base-mp3>-<timestamp>"
Capture o video_id retornado (o status será waiting inicialmente).
Por que áudio (e não texto): sincronização labial a partir de um MP3 existente exige que o HeyGen consuma o áudio diretamente. Enviar um script + voiceId aqui faria o HeyGen entrar no modo TTS e ignorar o MP3 carregado completamente.
5. Polling até a conclusão
Chame mcp__heygen__get_video com o video_id a cada ~10–15 segundos. Status:
waiting/processing/pending→ continue fazendo pollingcompleted→ capturevideo_urlda resposta e prossigafailed→ pare, exibafailure_messagepara o usuário
Limite a espera em ~10 minutos; se ainda estiver processando, informe o usuário e deixe que ele decida.
Peculiaridade do zsh para loops de polling — o nome de variável status é somente leitura no zsh. Se você escrever status=$(…) em um loop de polling, o script trava com read-only variable: status. Use um nome diferente (vstate, phase, ready).
6. Baixar o MP4
uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py "<video_url>" "<output_path>"
Download HTTPS simples da URL retornada pelo HeyGen — não é uma chamada de API para criar ou modificar um vídeo.
7. Relatar ao usuário
Informe ao usuário três coisas em uma resposta curta:
- caminho de saída do MP4
- qual avatar foi usado
- duração e tamanho do arquivo resultante
Exemplo
Usuário: tạo video heygen từ mp3 workspace/audio/episode-3.mp3
Você:
- Verificação de autenticação → se ferramentas HeyGen presentes, pule; senão
mcp__heygen__authenticate+ fluxo OAuth completo. check_duration.py workspace/audio/episode-3.mp3→OK 87.4- Seleção aleatória de
HEYGEN_AVATAR_LOOKS(ex.:66e75e22e6584bbdaa56a19088286dc8). Avise. 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…- Polling
mcp__heygen__get_videoa cada ~15s atécompleted→ capturevideo_url download_video.py <url> workspace/heygen-clips/episode-3/episode-3_20260510-143022.mp4- Relate caminho, ID do avatar, duração.
O que este skill NÃO faz deliberadamente
- Não escreve/transcreve SRT (isso é
mkt-ai-video-extract-srt-segment). - Não planeja visuais, b-roll, segmentos (isso é
mkt-plan-short-video-edit-16-9). - Não divide MP3 em partes (isso é
heygen-short-videocomsplit_audio.py). - Não compõe com Remotion ou HyperFrames (isso é o orquestrador pai).
Se o usuário quiser qualquer um dos itens acima, aponte para o skill correto em vez de expandir este.
Modos de falha e mensagens
| Sintoma | O que dizer ao usuário |
|---|---|
| Arquivo MP3 não encontrado | 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 não autenticado | Exiba a URL mcp__heygen__authenticate, peça ao usuário para autorizar, depois mcp__heygen__complete_authentication. |
HEYGEN_API_KEY não encontrada / 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 é placeholder (avatar_look_id_1,…) | Mesma lógica de fallback da chave de API — leia do repositório de marketing, ou peça ao usuário para inserir IDs reais de avatar. |
| HeyGen retorna falha | HeyGen render failed: <failure_message>. Có thể avatar look bị xoá hoặc audio asset không hợp lệ. |
| Sem créditos | Exiba o erro do HeyGen — não há get_remaining_credits exposto nesta versão do servidor MCP. Direcione o usuário para https://app.heygen.com/billing. |
Nome de ferramenta não encontrado (upload_asset / generate_avatar_video / get_avatar_video_status) | Nomes antigos do MCP — substituídos por upload REST + create_video_from_avatar + get_video. Atualize qualquer chamador que ainda use os nomes antigos. |