Crear Video
Genera videos completos a partir de un prompt de texto. Describe lo que quieres y la IA se encarga automáticamente de la escritura del guion, la selección del avatar, los visuales, la voz en off, el ritmo y los subtítulos.
Autenticación
Todas las solicitudes requieren el encabezado X-Api-Key. Establece la variable de entorno 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": "Crea un video demo de producto de 60 segundos."}'
Selección de Herramientas
Si las herramientas MCP de HeyGen están disponibles (mcp__heygen__*), prefiérelas sobre las llamadas HTTP directas a la API: manejan la autenticación y el formateo de solicitudes automáticamente.
| Tarea | Herramienta MCP | Alternativa (API directa) |
|---|---|---|
| Generar video desde un prompt | mcp__heygen__generate_video_agent | POST /v1/video_agent/generate |
| Verificar estado del video / obtener URL | mcp__heygen__get_video | GET /v2/videos/{video_id} |
| Listar videos de la cuenta | mcp__heygen__list_videos | GET /v2/videos |
| Eliminar un video | mcp__heygen__delete_video | DELETE /v2/videos/{video_id} |
Si no hay herramientas MCP de HeyGen disponibles, utiliza las llamadas HTTP directas a la API según la documentación en los archivos de referencia.
Flujo de Trabajo Predeterminado
Siempre usa las guías de prompt-optimizer.md para estructurar los prompts con escenas, tiempos y estilos visuales.
Con herramientas MCP:
- Escribe un prompt optimizado usando prompt-optimizer.md → visual-styles.md
- Llama a
mcp__heygen__generate_video_agentcon el prompt y la configuración (duration_sec, orientation, avatar_id) - Llama a
mcp__heygen__get_videocon el video_id devuelto para consultar el estado y obtener la URL de descarga
Sin herramientas MCP (API directa):
- Escribe un prompt optimizado usando prompt-optimizer.md → visual-styles.md
POST /v1/video_agent/generate— consulta video-agent.mdGET /v2/videos/<id>— consulta video-status.md
Referencia Rápida
| Tarea | Herramienta MCP | Leer |
|---|---|---|
| Generar video desde un prompt | mcp__heygen__generate_video_agent | prompt-optimizer.md → visual-styles.md → video-agent.md |
| Verificar estado del video / obtener URL de descarga | mcp__heygen__get_video | video-status.md |
| Subir archivos de referencia para el prompt | — | assets.md |
Cuándo Usar Esta Habilidad vs Video de Avatar
Esta habilidad es para creación de videos basada en prompts — describe lo que quieres y la IA se encarga del resto.
Si el usuario necesita control preciso sobre avatares específicos, guiones exactos, configuración de voz/fondo por escena o composición de múltiples escenas, usa la habilidad avatar-video en su lugar.
| El usuario dice | Esta Habilidad | Habilidad Avatar Video |
|---|---|---|
| "Hazme un video sobre X" | ✓ | |
| "Crea una demo de producto" | ✓ | |
| "Quiero que el avatar Y diga exactamente Z" | ✓ | |
| "Video de múltiples escenas con diferentes fondos" | ✓ | |
| "WebM transparente para composición" | ✓ |
Archivos de Referencia
Flujo de Trabajo Principal
- references/prompt-optimizer.md - Cómo escribir prompts efectivos (flujo de trabajo principal + reglas)
- references/visual-styles.md - 20 estilos visuales nombrados con especificaciones completas
- references/prompt-examples.md - Ejemplo completo de prompt de producción + plantillas listas para usar
- references/video-agent.md - Detalles del endpoint de la API de Video Agent
Base
- references/video-status.md - Patrones de consulta y URLs de descarga
- references/webhooks.md - Endpoints y eventos de webhooks
- references/assets.md - Subida de imágenes, videos y audio como referencias
- references/dimensions.md - Resoluciones y relaciones de aspecto
- references/quota.md - Sistema de créditos y límites de uso
Mejores Prácticas
- Optimiza tu prompt — La diferencia entre resultados mediocres y profesionales depende enteramente de la calidad del prompt. Usa siempre el optimizador de prompts
- Especifica la duración — Usa
config.duration_secpara una longitud predecible - Fija el avatar si es necesario — Usa
config.avatar_idpara consistencia entre videos - Sube archivos de referencia — Ayuda al agente a entender tu marca/producto
- Itera sobre los prompts — Refina basándote en los resultados; Video Agent es excelente para iteraciones rápidas