Criar Vídeo
Gere vídeos completos a partir de um prompt de texto. Descreva o que deseja e a IA cuida automaticamente da escrita do roteiro, seleção de avatar, visuais, narração, ritmo e legendas.
Autenticação
Todas as requisições exigem o cabeçalho X-Api-Key. Defina a variável de ambiente HEYGEN_API_KEY.
curl -X POST "https://api.heygen.com/v1/video_agent/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Crie um vídeo de demonstração do produto de 60 segundos."}'
Seleção de Ferramenta
Se as ferramentas MCP da HeyGen estiverem disponíveis (mcp__heygen__*), prefira-as em vez de chamadas diretas à API HTTP — elas lidam automaticamente com autenticação e formatação de requisições.
| Tarefa | Ferramenta MCP | Alternativa (API Direta) |
|---|---|---|
| Gerar vídeo a partir de prompt | mcp__heygen__generate_video_agent | POST /v1/video_agent/generate |
| 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} |
Se não houver ferramentas MCP da HeyGen disponíveis, use chamadas diretas à API HTTP conforme documentado nos arquivos de referência.
Fluxo de Trabalho Padrão
Sempre use as diretrizes de prompt-optimizer.md para estruturar prompts com cenas, temporização e estilos visuais.
Com ferramentas MCP:
- Escreva um prompt otimizado usando prompt-optimizer.md → visual-styles.md
- Chame
mcp__heygen__generate_video_agentcom prompt e configuração (duration_sec, orientation, avatar_id) - Chame
mcp__heygen__get_videocom o video_id retornado para verificar o status e obter a URL de download
Sem ferramentas MCP (API direta):
- Escreva um prompt otimizado usando prompt-optimizer.md → visual-styles.md
POST /v1/video_agent/generate— veja video-agent.mdGET /v2/videos/<id>— veja video-status.md
Referência Rápida
| Tarefa | Ferramenta MCP | Leia |
|---|---|---|
| Gerar vídeo a partir de prompt | mcp__heygen__generate_video_agent | prompt-optimizer.md → visual-styles.md → video-agent.md |
| Verificar status do vídeo / obter URL de download | mcp__heygen__get_video | video-status.md |
| Enviar arquivos de referência para o prompt | — | assets.md |
Quando Usar Esta Skill vs. Vídeo com Avatar
Esta skill é para criação de vídeo baseada em prompt — descreva o que deseja e a IA cuida do resto.
Se o usuário precisar de controle preciso sobre avatares específicos, scripts exatos, configuração de voz/fundo por cena ou composição de várias cenas, use a skill avatar-video.
| O Que o Usuário Diz | Esta Skill | Skill de Vídeo com Avatar |
|---|---|---|
| "Faça um vídeo sobre X" | ✓ | |
| "Crie uma demonstração do produto" | ✓ | |
| "Quero que o avatar Y diga exatamente Z" | ✓ | |
| "Vídeo com várias cenas e fundos diferentes" | ✓ | |
| "WebM transparente para composição" | ✓ |
Arquivos de Referência
Fluxo de Trabalho Principal
- references/prompt-optimizer.md - Escrevendo prompts eficazes (fluxo de trabalho principal + regras)
- references/visual-styles.md - 20 estilos visuais nomeados com especificações completas
- references/prompt-examples.md - Exemplo completo de prompt de produção + modelos prontos para uso
- references/video-agent.md - Detalhes do endpoint da API do Video Agent
Fundamentos
- references/video-status.md - Padrões de consulta e URLs de download
- references/webhooks.md - Endpoints e eventos de webhook
- references/assets.md - Envio de imagens, vídeos, áudio como referências
- references/dimensions.md - Resolução e proporções de aspecto
- references/quota.md - Sistema de créditos e limites de uso
Melhores Práticas
- Otimize seu prompt — A diferença entre resultados medianos e profissionais depende inteiramente da qualidade do prompt. Sempre use o otimizador de prompt
- Especifique a duração — Use
config.duration_secpara um comprimento previsível - Trave o avatar se necessário — Use
config.avatar_idpara consistência entre vídeos - Envie arquivos de referência — Ajude o agente a entender sua marca/produto
- Itere sobre os prompts — Refine com base nos resultados; o Video Agent é ótimo para iterações rápidas