O que Avatar Video faz?
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 Ferramenta
Se as ferramentas MCP do HeyGen estiverem disponíveis (mcp__heygen__*), prefira-as em vez de chamadas HTTP diretas — elas lidam com autenticação e formatação de requisições automaticamente.
| Tarefa | Ferramenta MCP | Fallback (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 |
| Deletar 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 — veja os arquivos de referência abaixo.
Fluxo de Trabalho Padrão
- Listar avatares —
GET /v2/avatars→ escolha um avatar, pré-visualize-o, anoteavatar_idedefault_voice_id. Veja avatars.md - Listar vozes (se necessário) —
GET /v2/voices→ escolha uma voz que corresponda ao gênero/idioma do avatar. Veja voices.md - Escrever o roteiro — Estruture cenas com um conceito cada. Veja scripts.md
- Gerar o vídeo —
POST /v2/video/generatecom avatar, voz, roteiro e fundo por cena. Veja video-generation.md - Verificar conclusão —
GET /v2/videos/{video_id}até que o status sejacompleted. Veja video-status.md
Referência Rápida
| Tarefa | Leia |
|---|---|
| Listar e pré-visualizar avatares | avatars.md |
| Listar e selecionar vozes | voices.md |
| Escrever e estruturar roteiros | scripts.md |
| Gerar vídeo (cena única ou múltipla) | 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 modelos | 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 roteiro exato e configura cada cena.
Se o usuário apenas deseja descrever uma ideia de vídeo e deixar a IA cuidar do resto (roteiro, avatar, visuais), use a skill create-video.
| O Usuário Diz | Skill Criar Vídeo | Esta Skill |
|---|---|---|
| "Faça um vídeo sobre X para mim" | ✓ | |
| "Crie uma demonstração de produto" | ✓ | |
| "Quero que o avatar Y diga exatamente Z" | ✓ | |
| "Vídeo multi-cena com fundos diferentes" | ✓ | |
| "WebM transparente para composição" | ✓ | |
| "Use esta voz específica para meu roteiro" | ✓ | |
| "Gere vídeos em lote com especificações exatas" | ✓ |
Arquivos de Referência
Criação de Vídeo Principal
- 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 roteiros, pausas, ritmo
- references/video-generation.md - POST /v2/video/generate e vídeos multi-cena
Personalização de Vídeo
- references/backgrounds.md - Cores sólidas, imagens, fundos de vídeo
- references/text-overlays.md - Adição de texto com fontes e posicionamento
- references/captions.md - Legendas e subtítulos gerados automaticamente
Recursos Avançados
- references/templates.md - Listagem de modelos 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 tela
- references/quota.md - Sistema de créditos e limites de uso
Melhores Práticas
- Pré-visualize avatares antes de gerar — Baixe
preview_image_urlpara que o usuário veja o avatar antes de confirmar - Use a voz padrão do avatar — A maioria dos avatares tem um
default_voice_idpré-combinado para resultados naturais - Fallback: combine gênero manualmente — Se não houver voz padrão, certifique-se de que os gêneros do avatar e da voz coincidam
- Use o modo de teste para desenvolvimento — Defina
test: truepara evitar consumir créditos (a saída terá marca d'água) - Defina tempos limite 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