Communitygithub.com

heygen-translate

Traduza e duble um vídeo existente em mais de 175 idiomas, com clonagem de voz e sincronização labial, alimentado pelo HeyGen Video Translation.

O que é heygen-translate?

Esta skill permite que agentes de IA (como Claude Code, Cursor ou Codex) traduzam e dublam vídeos preservando o apresentador original, com clonagem de voz e sincronização labial precisa. O fluxo de trabalho é dividido em quatro fases: Descoberta (coleta de entradas mínimas), Pré-voo (validação de idioma, classificação de conteúdo e configuração de sinalizadores), Envio + Polling (envio e monitoramento silencioso) e Entrega (publicação do resultado). A skill detecta automaticamente o modo de transporte (CLI, MCP ou plugin OpenClaw) e suporta caminhos padrão e de revisão (proofread) para edição de legendas antes da renderização final. Ela gerencia fontes de vídeo públicas ou locais, valida idiomas compatíveis, e configura perfis de conteúdo otimizados (apresentador, podcast, musical, multi-locutor, corporativo) para máxima qualidade de dublagem. Ideal para localização de vídeos, tradução de podcasts, ou criação de versões multilíngues mantendo a identidade visual e vocal do apresentador original sem gerar um novo vídeo.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Simo-Dax/claude-code-motion-video/tree/main/.claude/skills/heygen-translate

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. 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.
  2. Sem jargão interno. Não diga "polling", "video_translation_id", "asset_id", "endpoint v3". Diga "traduzindo", "quase pronto", "seu arquivo".
  3. 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.
  4. 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.
  5. 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.
  6. 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:

  1. Modo plugin OpenClaw — Se estiver rodando dentro do OpenClaw e a ferramenta video_generate expõ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 de video_generate.
  2. Modo CLI (substituição por chave de API) — Se HEYGEN_API_KEY estiver definida no ambiente E heygen --version sair 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.
  3. Modo MCP — Sem HEYGEN_API_KEY E as ferramentas MCP do HeyGen estão visíveis (mcp__heygen__*). Autenticação OAuth, executa contra os créditos do plano do usuário.
  4. Modo CLI (fallback) — Ferramentas MCP não disponíveis E heygen --version sair com código 0. Autenticação via heygen auth login.
  5. 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 | bash e depois heygen 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):
    1. 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."
    2. Assim que ele fornecer, persista: echo "<chave>" | heygen auth login (escreve em ~/.heygen/credentials, persiste entre sessões).
    3. 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 .... Execute heygen video-translate --help e heygen video-translate <subcomando> --help para descobrir argumentos. Use --request-schema para 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):

  1. 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?"
  2. 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):

  1. 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.
  2. 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.
  3. 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.
  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 como false apenas 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):

  1. 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.
  2. Tradução parcial. Se o usuário mencionar um segmento específico ("apenas a introdução", "de 1:30 a 4:00"), capture start_time e end_time em segundos.
  3. 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árioRota
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 HTMLInforme o usuário, peça uma URL pública ou arquivo local
Caminho de arquivo localFaç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 HeyGenPasse 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á).

PerfilUse quandoSinalizadores
Talking head / apresentador (padrão)Uma pessoa fala para a câmera; áudio limpomode: precision, enable_speech_enhancement: true, enable_caption: true, enable_dynamic_duration: true, keep_the_same_format: true
Podcast / apenas áudioO visual é estático, não importa ou não existemode: precision, translate_audio_only: true, enable_speech_enhancement: true, enable_caption: true
Música / trilha sonora altaMúsica de fundo interfere na falamode: precision, disable_music_track: true, enable_speech_enhancement: true, enable_dynamic_duration: true, keep_the_same_format: true
Multi-locutorDois ou mais locutores distintosPadrões de talking-head + speaker_num: <contagem>. A contagem de locutores é OBRIGATÓRIA aqui — não adivinhe.
Corporativo / com marcaVoz da marca, disciplina de glossário, alto riscoPadrõ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ão true (recomendado) — permite que a fala traduzida "respire" em vez de ser forçada no tempo exato da origem. Defina como false apenas 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: true para 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

Habilidades Relacionadas