Vídeo com Avatar
Crie vídeos com avatares de IA com controle total sobre avatares, vozes, scripts, cenas e fundos. Construa vídeos de cena única ou múltiplas cenas com configuração exata usando a API /v2/video/generate do HeyGen.
Autenticação
Todas as requisições exigem o cabeçalho X-Api-Key. Defina a variável de ambiente HEYGEN_API_KEY.
curl -X GET "https://api.heygen.com/v2/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Seleção de Ferramentas
Se as ferramentas MCP do HeyGen estiverem disponíveis (mcp__heygen__*), prefira-as em vez de chamadas HTTP diretas à API — elas lidam com autenticação e formatação de requisições automaticamente.
| Tarefa | Ferramenta MCP | Substituto (API Direta) |
|---|---|---|
| Verificar status do vídeo / obter URL | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| Listar vídeos da conta | mcp__heygen__list_videos | GET /v2/videos |
| Excluir um vídeo | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
A geração de vídeo (POST /v2/video/generate) e a listagem de avatares/vozes são feitas via chamadas diretas à API — consulte os arquivos de referência abaixo.
Fluxo de Trabalho Padrão
- Listar avatares —
GET /v2/avatars→ escolha um avatar, visualize-o, anoteavatar_idedefault_voice_id. Consulte avatars.md - Listar vozes (se necessário) —
GET /v2/voices→ escolha uma voz que corresponda ao gênero/idioma do avatar. Consulte voices.md - Escrever o script — Estruture cenas com um conceito cada. Consulte scripts.md
- Gerar o vídeo —
POST /v2/video/generatecom avatar, voz, script e fundo por cena. Consulte video-generation.md - Monitorar a conclusão —
GET /v2/videos/{video_id}até que o status sejacompleted. Consulte video-status.md
Referência Rápida
| Tarefa | Leia |
|---|---|
| Listar e visualizar avatares | avatars.md |
| Listar e selecionar vozes | voices.md |
| Escrever e estruturar scripts | scripts.md |
| Gerar vídeo (cena única ou múltiplas) | video-generation.md |
| Adicionar fundos personalizados | backgrounds.md |
| Adicionar legendas / subtítulos | captions.md |
| Adicionar sobreposições de texto | text-overlays.md |
| Criar vídeo WebM transparente | video-generation.md (seção WebM) |
| Usar templates | templates.md |
| Criar avatar a partir de foto | photo-avatars.md |
| Verificar status do vídeo / baixar | video-status.md |
| Enviar ativos (imagens, áudio) | assets.md |
| Usar com Remotion | remotion-integration.md |
| Configurar webhooks | webhooks.md |
Quando Usar Esta Skill vs. Criar Vídeo
Esta skill é para controle preciso — você escolhe o avatar, escreve o script exato, configura cada cena.
Se o usuário apenas deseja descrever uma ideia de vídeo e deixar a IA cuidar do resto (script, avatar, visuais), use a skill criar-video.
| O Usuário Diz | Skill Criar Vídeo | Esta Skill |
|---|---|---|
| "Crie um vídeo sobre X" | ✓ | |
| "Crie uma demonstração de produto" | ✓ | |
| "Quero que o avatar Y diga exatamente Z" | ✓ | |
| "Vídeo com múltiplas cenas e fundos diferentes" | ✓ | |
| "WebM transparente para composição" | ✓ | |
| "Use esta voz específica para meu script" | ✓ | |
| "Gere vídeos em lote com especificações exatas" | ✓ |
Arquivos de Referência
Criação Principal de Vídeo
- references/avatars.md - Listagem de avatares, estilos, seleção de avatar_id
- references/voices.md - Listagem de vozes, locais, velocidade/tom
- references/scripts.md - Escrita de scripts, pausas, ritmo
- references/video-generation.md - POST /v2/video/generate e vídeos com múltiplas cenas
Personalização de Vídeo
- references/backgrounds.md - Cores sólidas, imagens, fundos de vídeo
- references/text-overlays.md - Adicionar texto com fontes e posicionamento
- references/captions.md - Legendas e subtítulos gerados automaticamente
Recursos Avançados
- references/templates.md - Listagem de templates e substituição de variáveis
- references/photo-avatars.md - Criação de avatares a partir de fotos
- references/webhooks.md - Endpoints e eventos de webhook
Integração
- references/remotion-integration.md - Uso do HeyGen em composições Remotion
Fundamentos
- references/video-status.md - Padrões de consulta e URLs de download
- references/assets.md - Envio de imagens, vídeos, áudio
- references/dimensions.md - Resolução e proporções de aspecto
- references/quota.md - Sistema de créditos e limites de uso
Melhores Práticas
- Visualize avatares antes de gerar — Baixe
preview_image_urlpara que o usuário possa ver o avatar antes de se comprometer - Use a voz padrão do avatar — A maioria dos avatares tem um
default_voice_idpré-combinado para resultados naturais - Substituto: corresponda o gênero manualmente — Se não houver voz padrão, certifique-se de que os gêneros do avatar e da voz correspondam
- Use o modo de teste para desenvolvimento — Defina
test: truepara evitar consumir créditos (a saída terá marca d'água) - Defina timeouts generosos — A geração de vídeo geralmente leva de 5 a 15 minutos, às vezes mais
- Valide entradas — Verifique se os IDs do avatar e da voz existem antes de gerar