HeyGen Video Translation
Traduza e duble um vídeo existente em mais de 175 idiomas. O sistema clona a voz do apresentador no idioma de destino, ressincroniza os lábios com o novo áudio e retorna um vídeo totalmente dublado. Você fornece um vídeo de origem e um idioma de destino — o mecanismo cuida da transcrição, tradução, clonagem de voz, sincronização labial e (opcionalmente) legendas embutidas.
Isso não é geração de novo vídeo. O apresentador, a performance, o enquadramento e os ativos de marca do vídeo original são preservados. A tradução é aplicada sobre o que já existe.
Comportamento Voltado ao Usuário
- Seja conciso. Não despeje IDs de tradução, payloads brutos da API ou JSON de status no chat. Informe o resultado (link do vídeo, idioma), não a parte técnica.
- Sem jargão interno. Não diga "polling", "video_translation_id", "asset_id", "endpoint v3". Diga "traduzindo", "quase pronto", "seu arquivo".
- Polling é silencioso. Faça polling em segundo plano para traduções longas e só se manifeste em (a) resultado entregue, (b) parada >5 min (uma atualização), (c) falha grave.
- Um resultado, uma mensagem. Quando o vídeo estiver pronto, envie o link mais um resumo de uma linha (idioma de destino, duração, modo). Não todos os campos da API.
- Não narre a escolha de transporte. MCP vs CLI vs plugin OpenClaw é interno. Escolha silenciosamente no início da sessão; nunca mencione qual está em uso.
- Comunique-se no idioma do usuário. Detecte a partir da primeira mensagem. Respostas, confirmações e perguntas no idioma deles. Diretivas técnicas de CLI/API permanecem em inglês.
Detecção de Modo de API
Escolha um transporte no início da sessão. Nunca misture, nunca mude no meio da sessão, nunca narre a escolha.
Detecte nesta ordem:
- Modo plugin OpenClaw — Se estiver rodando dentro do OpenClaw e a ferramenta
video_generateexpõe um modelo de tradução HeyGen, prefira este. Atualmente o plugin gera vídeos, mas não expõe tradução diretamente — passe para o próximo nível até que o HeyGen ofereça tradução através devideo_generate. - Modo CLI (substituição por chave de API) — Se
HEYGEN_API_KEYestiver definida no ambiente Eheygen --versionsair com código 0, use CLI. A presença da chave de API é um sinal explícito de que o usuário quer acesso direto à API. - Modo MCP — Sem
HEYGEN_API_KEYE as ferramentas MCP do HeyGen estão visíveis (mcp__heygen__*). Autenticação OAuth, executa contra os créditos do plano do usuário. - Modo CLI (fallback) — Ferramentas MCP não disponíveis E
heygen --versionsair com código 0. Autenticação viaheygen auth login. - Nenhum — informe ao usuário uma vez: "Para usar esta skill, conecte o servidor MCP do HeyGen ou instale a CLI do HeyGen:
curl -fsSL https://static.heygen.ai/cli/install.sh | bashe depoisheygen auth login."
Verificação de autenticação (executar antes de qualquer chamada de API)
Após a detecção do modo, verifique se a autenticação realmente funciona antes de entrar na Fase 1. Isso evita perder tempo do usuário coletando entradas apenas para encontrar um erro de autenticação no envio.
- Modo MCP: a autenticação é gerenciada pelo OAuth — nenhuma verificação necessária.
- Modo CLI: execute
heygen auth status(silencioso). Se sair com código 0, prossiga. Se sair com código diferente de zero (sem chave, expirada, inválida):- Pergunte ao usuário: "Preciso da sua chave de API do HeyGen para continuar. Você pode obtê-la em https://app.heygen.com/settings?nav=API — cole aqui."
- Assim que ele fornecer, persista:
echo "<chave>" | heygen auth login(escreve em~/.heygen/credentials, persiste entre sessões). - Verifique:
heygen auth status. Se ainda falhar, exiba o erro e pare.
Esta é uma configuração única. Depois que heygen auth login persiste a chave, sessões futuras a pegam automaticamente. Não pergunte novamente se heygen auth status passar.
Regras rígidas:
- Nunca chame
curl api.heygen.com/...Toda operação nesta skill tem um comando CLI e (quando suportado) uma ferramenta MCP. Use-os. - Modo MCP: apenas ferramentas
mcp__heygen__*. Se a tradução não estiver exposta via MCP ainda, recorra ao CLI para operações de tradução especificamente. Não sintetize chamadas HTTP brutas. - Modo CLI: apenas comandos
heygen .... Executeheygen video-translate --helpeheygen video-translate <subcomando> --helppara descobrir argumentos. Use--request-schemapara ver a estrutura JSON completa de qualquer comando create. - As operações abaixo mostram MCP e CLI lado a lado — leia apenas a coluna do seu modo detectado.
Nomes de ferramentas MCP (apenas modo MCP)
create_video_translation (único idioma). Traduções multilíngues e revisões (proofreads) ainda não estão expostas via MCP — recorra ao CLI para essas. Execute a listagem de ferramentas mcp__heygen__* no início da sessão para confirmar o que está disponível; a superfície de ferramentas evolui.
Grupos de comandos CLI (apenas modo CLI)
heygen video-translate
├── languages list # idiomas de destino suportados
├── create # enviar um job de tradução (único ou em lote)
├── get <id> # verificar status / obter resultado
├── list # listar traduções anteriores
├── update # atualizar metadados do job
├── delete # excluir um job
└── proofreads
├── create # extrair legendas editáveis antes da renderização final
├── get <id> # verificar status da sessão de revisão
├── srt get <id> # baixar o SRT extraído
├── srt update <id> # enviar SRT editado
└── generate <id> # renderizar o vídeo final a partir do SRT aprovado
heygen asset create --file <caminho> # para uploads de vídeo de origem local (máx. 32 MB)
Todo comando suporta --help. Use --request-schema em qualquer create para ver o corpo JSON completo. Saída do CLI: JSON em stdout, envelope {error:{code,message,hint}} em stderr, códigos de saída 0 ok · 1 API · 2 uso · 3 autenticação · 4 timeout. Adicione --wait no create para bloquear até o job ser concluído (timeout padrão de 20min).
📖 Mapeamento detalhado de erros CLI/MCP → ação → references/troubleshooting.md
Fluxo de Trabalho Padrão
A skill executa quatro fases. A Fase 1 (Descoberta) é o único lugar onde você faz perguntas. A Fase 2 (Pré-voo) é silenciosa. A Fase 3 (Envio + Polling) é silenciosa. A Fase 4 (Entrega) é uma mensagem curta.
Fase 1 — Descoberta — colete o mínimo de entradas necessárias do usuário
Fase 2 — Pré-voo — valide idioma, classifique conteúdo, configure sinalizadores
Fase 3 — Envio + Polling — inicie, faça polling em segundo plano, notifique apenas quando pronto/erro
Fase 4 — Entrega — publique o resultado com resumo de uma linha
Fase 1 — Descoberta
Pergunte apenas o que você ainda não tem. Comunique-se no idioma do usuário. Nunca execute um formulário. Uma ou duas perguntas por vez, no máximo.
Entradas obrigatórias (bloqueie até tê-las):
- Vídeo de origem. URL pública, caminho de arquivo local ou um asset_id do HeyGen de uma etapa anterior. Se o usuário não forneceu, pergunte: "Qual é o vídeo de origem — uma URL, um caminho de arquivo ou um asset existente do HeyGen?"
- Idioma(s) de destino. Pergunte como uma pergunta aberta no idioma do usuário: "Para qual idioma devo traduzir?" NÃO apresente um seletor ou opções pré-definidas — deixe o usuário digitar livremente. Eles podem querer um idioma, vários ou uma variante regional específica. Aceite o que eles derem e valide contra a lista canônica de idiomas na Fase 2.
Entradas importantes (pergunte se não fornecidas, com padrões inteligentes):
- Número de locutores. Locutor único é o padrão e o que a maioria dos usuários tem. Pergunte uma vez quando ambíguo: "Quantos locutores distintos há no vídeo?" O número errado de locutores é o principal destruidor de qualidade — confusão de locutores cria trocas de voz no meio da tradução. Não pule isso para conteúdo com múltiplas pessoas.
- Tipo de conteúdo. Geralmente você não precisa perguntar — deduza do vídeo e confirme. Os cinco perfis abaixo cobrem ~95% dos casos. Pergunte apenas se for genuinamente ambíguo.
- Preferência de legenda. Padrão LIGADO para talking-head e corporativo; padrão DESLIGADO para podcast/somente áudio. Se você alterar o padrão, mencione brevemente na Fase 4.
- Flexibilidade de duração. Pergunte: "O vídeo traduzido precisa ter exatamente a mesma duração do original, ou pode ser um pouco mais longo/mais curto? Permitir flexibilidade geralmente soa mais natural — a fala traduzida tem espaço suficiente para ser dita em um ritmo confortável, em vez de ser acelerada ou comprimida." Recomendação padrão: flexível (
enable_dynamic_duration: true). Defina comofalseapenas quando o usuário precisar de temporização exata de quadro (por exemplo, sincronizando com uma linha do tempo, espaço de anúncio ou trilha de áudio externa).
Opcional (pergunte apenas se relevante):
- Glossário / termos a não traduzir. Para conteúdo corporativo ou técnico, pergunte: "Algum nome de produto, nome de empresa ou jargão que devo manter no idioma original?" O HeyGen atualmente não aceita um glossário rígido, então isso se torna orientação para a etapa de revisão (Fase 3-Revisão) quando o risco é alto.
- Tradução parcial. Se o usuário mencionar um segmento específico ("apenas a introdução", "de 1:30 a 4:00"), capture
start_timeeend_timeem segundos. - Revisar antes da renderização final? Padrão DESLIGADO (mais rápido, menos aprovações). Padrão LIGADO para: vídeos longos (>3 min), conteúdo corporativo/com marca, conteúdo legal/médico/educacional de alto risco, idiomas que o usuário lê nativamente (para que possa verificar). Pergunte: "Quer revisar e editar as legendas antes da renderização final? Adiciona cerca de 5 minutos, mas permite corrigir termos errados."
📖 Armadilhas de pares de localidade (registros de formalidade, idiomas RTL, compressão tonal, limite de sincronização labial) → references/language-locale-guide.md
Fase 2 — Pré-voo
Silencioso. Sem conversa com o usuário. Três verificações, em ordem.
Verificação 2a: Validação de idioma.
MCP: list_video_translation_languages() (se exposto). Caso contrário, CLI.
CLI: heygen video-translate languages list | jq -r '.data.languages[]'
A lista contém strings exatas ("Spanish (Spain)", "Chinese (Mandarin, Simplified)", "Arabic (Saudi Arabia)"). Compare a entrada do usuário de forma insensível a maiúsculas/minúsculas com essas strings exatas. Se ele disser "Spanish", use como padrão "Spanish (Spain)" e confirme na Fase 4. Se ele disser "Chinese", use como padrão "Chinese (Mandarin, Simplified)". Se ele especificar uma região ("Mexican Spanish"), mapeie ("Spanish (Mexico)"). Se não houver correspondência: peça ao usuário para escolher entre as opções mais próximas.
Verificação 2b: Roteamento do vídeo de origem.
| Origem fornecida pelo usuário | Rota |
|---|---|
URL HTTPS pública (sem autenticação, retorna MIME de vídeo no HEAD) | Passe diretamente como {type: "url", url: "..."} |
| URL protegida por autenticação, 403, 404 ou resposta HTML | Informe o usuário, peça uma URL pública ou arquivo local |
| Caminho de arquivo local | Faça upload via heygen asset create --file <caminho> (CLI) ou upload_asset (MCP). Máx. 32 MB. Use o asset_id retornado como {type: "asset_id", asset_id: "..."} |
| asset_id existente do HeyGen | Passe diretamente como {type: "asset_id", asset_id: "..."} |
📖 Casos extremos de roteamento de ativos (arquivos muito grandes, URLs pré-assinados, fontes protegidas por autenticação) → references/asset-routing.md
Verificação 2c: Perfil de conteúdo.
Escolha um perfil com base na origem. Não liste todos os cinco para o usuário — proponha silenciosamente e só pergunte se a origem for genuinamente ambígua (por exemplo, um talking-head com muita música em que você não consegue dizer se o aprimoramento de fala ajudará).
| Perfil | Use quando | Sinalizadores |
|---|---|---|
| Talking head / apresentador (padrão) | Uma pessoa fala para a câmera; áudio limpo | mode: precision, enable_speech_enhancement: true, enable_caption: true, enable_dynamic_duration: true, keep_the_same_format: true |
| Podcast / apenas áudio | O visual é estático, não importa ou não existe | mode: precision, translate_audio_only: true, enable_speech_enhancement: true, enable_caption: true |
| Música / trilha sonora alta | Música de fundo interfere na fala | mode: precision, disable_music_track: true, enable_speech_enhancement: true, enable_dynamic_duration: true, keep_the_same_format: true |
| Multi-locutor | Dois ou mais locutores distintos | Padrões de talking-head + speaker_num: <contagem>. A contagem de locutores é OBRIGATÓRIA aqui — não adivinhe. |
| Corporativo / com marca | Voz da marca, disciplina de glossário, alto risco | Padrões de talking-head + (se o usuário tiver) brand_voice_id. Considere fortemente revisões para este perfil. |
Sempre:
mode: "precision"a menos que o usuário peça explicitamente "rápido" / "veloz" / "rapidez".enable_dynamic_duration: defina com base na resposta do usuário à pergunta sobre flexibilidade de duração na Fase 1. Padrãotrue(recomendado) — permite que a fala traduzida "respire" em vez de ser forçada no tempo exato da origem. Defina comofalseapenas quando o usuário precisar explicitamente de saída de duração fixa. A compressão tonal torna a flexibilidade especialmente importante para en→zh, en→ja, en→ko (idiomas asiáticos são mais curtos); de→en, ja→en (são mais longos); ar/he/ur (RTL + mudanças de registro).keep_the_same_format: truepara traduções visuais — preserva a resolução e taxa de bits da origem para que o vídeo dublado corresponda à codificação original.enable_watermark: false(o padrão).
Fase 3 — Envio + Polling
Silencioso. Trabalho em segundo plano. Notifique apenas em (a) conclusão por idioma, (b) falha grave por idioma, (c) verificação de progresso >5 min.
Ramificação:
- Caminho padrão (revisão = DESLIGADA): envie traduções, faça polling em segundo plano, entregue.
- Caminho de revisão (revisão = LIGADA): crie sessão de revisão → baixe SRT → usuário edita ou você ajuda → envie SRT editado → gere final → faça polling em segundo plano → entregue.
Caminho padrão
Envie um job por idioma de destino usando sintaxe de lote (--output-languages aceita múltiplos).
MCP (apenas idioma único no momento):
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>, # apenas quando multi-locutor conhecido
)
CLI:
heygen video-translate create \
-d '{"video":{"type":"url","url":"https://..."},"output_languages":["Spanish (Spain)","Japanese (Japan)"]}' \
--mode precision \
--enable-speech-enhancement \
--enable-caption \
--enable-dynamic-duration \
--keep-the-same-format