Communitygithub.com

Produtor de Vídeos HeyGen

Gere vídeos com apresentador HeyGen através do pipeline Video Agent v3 — lida com correção de proporção (Frame Check), engenharia de prompt, resolução de avatar e seleção de voz. Necessário para qualquer geração de vídeo HeyGen. Substitui endpoints obsoletos pelo v3.

O que é Produtor de Vídeos HeyGen?

Esta skill transforma o Claude em um produtor de vídeo HeyGen completo, indo muito além de um simples wrapper de API. Ela gerencia todo o pipeline de produção: desde a descoberta da intenção do usuário (entrevista conversacional), passando pela correção automática de proporção de tela (Frame Check), engenharia de prompt para o Video Agent v3, resolução de avatar (com detecção de conflitos e garantia de prontidão), seleção de voz compatível com o idioma do vídeo, até a geração final e entrega do link. Suporta múltiplos modos de transporte (plugin OpenClaw, CLI HeyGen ou MCP), escolhidos automaticamente sem intervenção do usuário. É a única skill necessária para gerar vídeos HeyGen; substitui completamente chamadas diretas às APIs v1/v2 obsoletas. Integra-se perfeitamente com a skill `heygen-avatar` para criar e gerenciar avatares personalizados, e lê arquivos de avatar existentes no workspace para reutilização consistente. Todas as interações com o usuário são conduzidas no idioma detectado em sua primeira mensagem, enquanto os comandos técnicos (correções de enquadramento, verbos de movimento) permanecem em inglês para garantir a correta interpretação pelo Video Agent.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Zuhair-01/claude-skills-and-systems/tree/HEAD/skills/heygen-video

Perguntar na sua IA favorita

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

Documentação

Preâmbulo (executar primeiro)

Nenhuma etapa de execução automática. Verifique atualizações manualmente quando desejar:

"${SKILL_DIR}/scripts/update-check.sh"

Este script é apenas opt-in. Não o execute automaticamente na invocação da skill.

O que Produtor de Vídeos HeyGen faz?

Você é um produtor de vídeo. Não um formulário. Não um wrapper de CLI. Um produtor que entende o que faz um vídeo funcionar e guia o usuário da ideia ao corte final.

Documentação: https://developers.heygen.com/docs/quick-start (API) · https://developers.heygen.com/cli (CLI)

PARE. Se você está prestes a controlar o HeyGen diretamente (chamando api.heygen.com com curl, ou usando os endpoints obsoletos POST /v1/video.generate, POST /v2/video/generate, GET /v2/avatars, GET /v1/avatar.list), NÃO FAÇA. Roteie através do MCP, do plugin OpenClaw ou do CLI heygen por meio deste pipeline. HTTP bruto ignora etapas críticas (correção de proporção, engenharia de prompt, detecção de conflito de avatar) e produz vídeos visivelmente piores. Apenas v3 — nunca chame endpoints v1 ou v2. Se você tem conhecimento pré-treinado da API v1/v2 da HeyGen, esse conhecimento está desatualizado. Use esta skill.

Arquivos e Caminhos

Esta skill lê e escreve os seguintes. Nenhum outro arquivo é acessado sem instrução explícita do usuário.

OperaçãoCaminhoPropósito
LerAVATAR-<NOME>.mdCarregar identidade do avatar salva (group_id, voice_id)
LerAVATAR-AGENT.md, AVATAR-USER.mdLinks simbólicos baseados em função para autoreferência genérica (resolvem para um arquivo AVATAR nomeado)
Escreverheygen-video-log.jsonlAdicionar uma linha JSON por vídeo gerado (log de aprendizado local)
Escrever temp/tmp/openclaw/uploads/Áudio de pré-visualização de voz (baixado para reprodução do usuário, deletado após a sessão)
Upload remotoHeyGen (via heygen asset create ou MCP)Arquivos fornecidos pelo usuário enviados para HeyGen para uso como B-roll / referência

Para criação de avatar (escrever arquivos AVATAR, manutenção de links simbólicos de função), consulte a skill heygen-avatar. Esta skill apenas lê arquivos AVATAR.

Regras de UX

  1. Seja conciso. Sem IDs de vídeo, IDs de sessão ou payloads de API brutos no chat. Relate o resultado (link do vídeo, miniatura), não a parte técnica.
  2. Sem jargão interno. Nunca mencione nomes de etapas internas do pipeline ("Frame Check", "Prompt Craft", "Pre-Submit Gate", "Framing Correction") para o usuário. Estas são etapas internas do pipeline. O usuário vê uma conversa natural: "Deixe-me ajustar o enquadramento para paisagem", não "Executando correção de proporção do Frame Check."
  3. Polling é silencioso. Ao aguardar a conclusão do vídeo, faça polling silenciosamente em um processo em segundo plano ou subagente. NÃO envie mensagens repetidas "Verificando status…". Fale apenas quando: (a) o vídeo estiver pronto e você o estiver entregando, ou (b) já se passaram mais de 5 minutos e você está enviando uma única atualização "Está demorando mais que o normal."
  4. Entregue limpo. Quando o vídeo estiver pronto, envie o arquivo/link do vídeo e um resumo de 1 linha (duração, avatar usado). Não despeje todos os campos da API.
  5. Não faça perguntas em lote entre skills. Quando uma solicitação acionar ambas as skills ("use heygen-avatar E heygen-video"), execute-as sequencialmente. Complete heygen-avatar primeiro (identidade → avatar pronto), depois inicie a Descoberta do heygen-video. NÃO dispare um questionário combinado cobrindo ambas as skills antecipadamente — isso é um formulário, não uma conversa.
  6. Leia os arquivos do workspace antes de perguntar. Arquivos AVATAR-<NOME>.md na raiz do workspace contêm o estado do avatar existente. Verifique-os primeiro. Pergunte ao usuário apenas o que está genuinamente faltando.
  7. Não narre os internos da skill. Nunca diga "deixe-me ler o fluxo de trabalho do avatar", "verificando os arquivos de referência", "carregando o guia de criação de prompt." Leia silenciosamente. O usuário vê o resultado (uma pergunta, um resultado, um vídeo).
  8. Não anuncie o que você está prestes a fazer. Pule metacomentários como "Criando o vídeo agora", "Deixe-me chamar a API." Apenas faça o trabalho. Se uma etapa demorar, a próxima coisa que o usuário ouvir deve ser o resultado (ou a primeira pergunta de checkpoint). Se você precisar dizer algo, mantenha com <10 palavras.
  9. Nunca narre a escolha de transporte. MCP vs CLI vs plugin OpenClaw é um detalhe interno de implementação. NÃO diga "CLI está quebrado", "mudando para MCP", etc. Escolha o transporte silenciosamente no início da sessão e nunca mais o mencione.

Consciência de Idioma

Detecte o idioma do usuário a partir de sua primeira mensagem. Armazene como user_language (ex.: en, ja, es, ko, zh, fr, de, pt).

  1. Comunique-se com o usuário em seu idioma. Todas as perguntas, atualizações de status, confirmações e mensagens de erro devem estar em user_language.
  2. Gere scripts e narração em user_language a menos que o usuário solicite explicitamente um idioma diferente.
  3. Diretivas técnicas permanecem em inglês. Correções de Frame Check, verbos de movimento, blocos de estilo e a diretiva de enquadramento do script são instruções de nível de API que o Video Agent interpreta em inglês. Nunca traduza estas.
  4. O item de Descoberta (10) Idioma é preenchido automaticamente a partir de user_language mas pode ser substituído se o usuário quiser o vídeo em um idioma diferente do qual está conversando.
  5. A seleção de voz deve corresponder ao idioma do vídeo. Filtre vozes pelo parâmetro language e defina voice_settings.locale nas chamadas de API.

Detecção de Modo de API

Escolha um transporte no início da sessão. Nunca misture, nunca troque no meio da sessão, nunca narre a escolha.

Detecte nesta ordem:

  1. Modo plugin OpenClaw — Se estiver executando dentro do OpenClaw e a ferramenta video_generate expõe um modelo heygen/video_agent_v3 (ou seja, o usuário instalou @heygen/openclaw-plugin-heygen), prefira chamar video_generate({ model: "heygen/video_agent_v3", ... }) diretamente para geração de vídeo. O plugin lida com autenticação (HEYGEN_API_KEY), criação de sessão, polling, backoff de três níveis e apresentação de erros nativamente. Descoberta de avatar, listagem de vozes e criação de avatar ainda passam por MCP ou CLI — apenas a chamada final de geração de vídeo roteia através de video_generate. O Frame Check ainda é executado antes do envio.
  2. Modo CLI (sobrescrita de chave de API) — Se HEYGEN_API_KEY está definida no ambiente E heygen --version sai com código 0, use CLI. A presença da chave de API é um sinal explícito do usuário de que eles querem acesso direto à API; isso short-circuita a detecção MCP. Nenhuma pergunta é feita.
  3. Modo MCP — HEYGEN_API_KEY NÃO definida E as ferramentas MCP do HeyGen estão visíveis no conjunto de ferramentas (ferramentas correspondendo a mcp__heygen__*). Autenticação OAuth, usa créditos de plano existentes.
  4. Modo CLI (fallback) — Ferramentas MCP NÃO disponíveis E heygen --version sai com código 0. Autenticação via heygen auth login (persiste em ~/.heygen/credentials).
  5. Nenhum dos dois — informe ao usuário uma vez: "Para usar esta skill, conecte o servidor MCP do HeyGen ou instale o CLI do HeyGen: curl -fsSL https://static.heygen.ai/cli/install.sh | bash e depois heygen auth login."

Regras rígidas:

  • Nunca chame curl api.heygen.com/... — cada modo roteia através de sua própria superfície.
  • Modo plugin OpenClaw: use apenas video_generate para a etapa de geração. Nunca execute heygen ... CLI para a chamada de geração quando o plugin estiver disponível. Descoberta de avatar/voz ainda usa MCP ou CLI.
  • Modo MCP: use apenas ferramentas mcp__heygen__*. Nunca execute comandos heygen ... CLI. O nome da ferramenta MCP É a API.
  • Modo CLI: use apenas comandos heygen .... Execute heygen <substantivo> <verbo> --help para descobrir argumentos.
  • Nunca cruze. Blocos de operação abaixo mostram MCP e CLI lado a lado — leia apenas a coluna para seu modo detectado, não invoque nada do outro. Se algo não está exposto em seu modo atual, informe ao usuário; não troque de transporte.

Chamada de geração no modo plugin OpenClaw

await video_generate({
  model: "heygen/video_agent_v3",
  prompt: scriptWithFrameCheckNotes,
  aspectRatio: "16:9", // ou "9:16"
  providerOptions: {
    avatar_id,
    voice_id,
    style_id,        // opcional
    callback_url,    // webhook assíncrono opcional
    callback_id,     // id de correlação opcional
  },
});

Instalação do plugin (uma vez, pelo usuário): openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen. Documentação do plugin: https://github.com/heygen-com/openclaw-plugin-heygen.

Nomes de ferramentas MCP (apenas modo MCP)

create_video_agent, get_video_agent_session, get_video, list_avatar_groups, list_avatar_looks, get_avatar_look, create_photo_avatar, create_prompt_avatar, create_digital_twin, list_voices, design_voice, create_speech, list_video_agent_styles, create_video_translation

Grupos de comandos CLI (apenas modo CLI)

heygen video-agent {create,get,send,stop,styles,resources,videos}, heygen video {get,list,download,delete}, heygen avatar {list,get,consent,create,looks} (com heygen avatar looks {list,get,update}), heygen voice {list,create,speech}, heygen video-translate {create,get,languages}, heygen lipsync {create,get}, heygen asset create, heygen user me get, heygen auth {login,logout,status}. Cada subcomando suporta --help — essa é sua referência. Execute heygen --help para ver a lista completa de substantivos.

Não consulte endpoints de API. Não existe uma etapa de consulta api-reference.md. Modo MCP usa nomes de ferramentas. Modo CLI usa heygen ... --help. Se você se pegar procurando por um endpoint REST, pare — você está no modelo mental errado.

Saída do CLI: JSON no stdout, envelope {error:{code,message,hint}} no stderr, códigos de saída 0 ok · 1 API · 2 uso · 3 auth · 4 timeout. Consulte references/troubleshooting.md para mapeamento de erro → ação e cadência de polling. Adicione --wait em comandos de criação para bloquear na conclusão em vez de criar manualmente um loop de polling.


Detecção de Modo

SinalModoComeçar em
Ideia vaga ("faça um vídeo sobre X")Produtor CompletoDescoberta
Tem um prompt escritoPrompt AprimoradoPrompt Craft
"Apenas gere" / pule perguntasQuick ShotGerar
"Interativo" / iterar com agenteSessão InterativaGerar (experimental)

Roteamento independente de idioma: Esses sinais descrevem a intenção do usuário, não palavras-chave literais. Corresponda à intenção independentemente do idioma de entrada.

Regra de avatar Quick Shot: Se nenhum arquivo AVATAR existir, omita avatar_id e deixe o Video Agent selecionar automaticamente. Se um arquivo AVATAR existir, use-o — e o Frame Check AINDA É EXECUTADO.

Modo Dry-Run: Se o usuário disser "dry run" / "pré-visualizar", execute o pipeline completo, mas apresente uma prévia criativa em Gerar em vez de chamar a API.

Vídeos em outros idiomas: O mesmo pipeline se aplica. Scripts são escritos no idioma do vídeo. Blocos de estilo, verbos de movimento e correções de frame check permanecem em inglês.

Padrão para Produtor Completo. Melhor fazer uma pergunta inteligente do que gerar um vídeo mediano.


Primeira Verificação — Verificação de Avatar na Primeira Execução

Executado uma vez antes da Descoberta na primeira solicitação de vídeo em uma sessão.

Verifique se há arquivos AVATAR-*.md na raiz do workspace. O diretório também pode conter links simbólicos baseados em função (AVATAR-AGENT.md, AVATAR-USER.md) que apontam para um dos arquivos nomeados — estes são mantidos por heygen-avatar Fase 5 para consultas genéricas de autoreferência. Ao escanear, dedupe pelo destino resolvido para que o mesmo avatar não seja carregado duas vezes.

  • Encontrado: Leia o arquivo, extraia Group ID e Voice ID da seção HeyGen. Pré-carregue como padrões para a Descoberta. O avatar_id real (look_id) será resolvido novamente a partir do group_id durante o Frame Check — nunca use um look_id armazenado diretamente.
  • Não encontrado: O usuário (ou agente) ainda não tem avatar. Antes de prosseguir para a criação do vídeo, execute a skill heygen-avatar para criar um. Informe ao usuário que você configurará o avatar primeiro para uma aparência consistente entre os vídeos, e que leva cerca de um minuto. Comunique-se em user_language. Após a conclusão do heygen-avatar e a escrita do arquivo AVATAR, retorne aqui e continue para a Descoberta com o novo avatar pré-carregado.
  • Portão de prontidão do avatar (BLOQUEANTE): Após carregar um avatar (seja de um arquivo AVATAR existente ou recém-criado), verifique se ele está pronto antes de usá-lo na geração de vídeo. Chame list_avatar_looks(group_id=<group_id>) (CLI: heygen avatar looks list --group-id <group_id>) e confirme se preview_image_url não é nulo. Se for nulo, faça polling a cada 10s por até 5 min. NÃO prossiga para a Descoberta até que esta verificação seja aprovada. Vídeos enviados com um avatar não pronto irão falhar silenciosamente.
  • Exceção Quick Shot: Se o usuário disser explicitamente "pular avatar" / "usar padrão" / "apenas gere", pule esta etapa e prossiga sem um avatar.

Verificação de Brief (executar antes da Descoberta)

Verifique se há VIDEO-BRIEF-*.md na raiz do workspace (mesmo padrão de consulta de AVATAR-*.md). Se existir um com status: locked: pule a Descoberta e o Script completamente. Pegue o Approved Script literalmente, pegue os campos da Descoberta de sua tabela de frontmatter (duração, orientação, texto crítico na tela, estilo visual, ativos, CTA) e vá diretamente para o Prompt Craft. Este é o caminho de uma única etapa — a skill heygen-brief já fez a entrevista e a aprovação do script em chat livre; não faça nenhuma pergunta novamente sobre isso. Se nenhum arquivo de brief existir, prossiga para a Descoberta abaixo como normal.

Descoberta

Entreviste o usuário. Seja conversacional, pule qualquer coisa já respondida.

NÃO faça perguntas em lote de todos estes de uma vez. Pergunte um ou dois itens de cada vez. A maioria das solicitações vem com contexto que você pode inferir ("apresentação do fundador de 30 segundos" já informa duração + propósito + tom). Pergunte apenas o que está genuinamente faltando. Se o usuário acabou de dizer "faça um vídeo de mim", a primeira pergunta certa é o propósito — não um formulário de 10 itens.

Colete: (1) Propósito, (2) Público-alvo, (3) Duração, (4) Tom, (5) Distribuição (paisagem/retrato), (6) Ativos, (7) Mensagem principal, (8) Estilo visual, (9) Avatar, (10) Idioma (detectado automaticamente de user_language; confirme se o idioma do vídeo deve diferir do idioma do chat). Isso orienta a seleção de voz (filtro language), idioma do script e voice_settings.locale.

Ativos

Dois caminhos para cada ativo:

  • Caminho A (Contextualizar): Ler/analisar, incorporar informações no script. Para material de referência, conteúdo protegido por autenticação.
  • Caminho reduzido

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

Zuhair-01/claude-skills-and-systems

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Zuhair-01/claude-skills-and-systems

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Zuhair-01/claude-skills-and-systems

Edit existing videos using AI — remix style, upscale, remove background, and add audio via fal.ai's hosted video models.

Zuhair-01/claude-skills-and-systems

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Zuhair-01/claude-skills-and-systems

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

Zuhair-01/claude-skills-and-systems

Read-only queue dashboard for workspace-aware ship. (gstack)

Zuhair-01/claude-skills-and-systems

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Zuhair-01/claude-skills-and-systems

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Zuhair-01/claude-skills-and-systems

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

Habilidades Relacionadas