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 redacción del guion, la selección de avatares, las imágenes, la locución, el ritmo y los subtítulos.
Autenticación
Todas las solicitudes requieren la cabecera X-Api-Key. Define 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 de demostración de producto de 60 segundos."}'
Selección de Herramientas
Si las herramientas MCP de HeyGen están disponibles (mcp__heygen__*), es preferible usarlas en lugar de llamadas directas a la API HTTP — manejan la autenticación y el formato de las solicitudes automáticamente.
| Tarea | Herramienta MCP | Alternativa (API directa) |
|---|---|---|
| Generar video a partir de un prompt | mcp__heygen__generate_video_agent | POST /v1/video_agent/generate |
| Consultar estado / obtener URL del video | 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, usa las llamadas directas a la API HTTP como se documenta en los archivos de referencia.
Flujo de Trabajo Predeterminado
Usa siempre las pautas 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 | Lectura |
|---|---|---|
| Generar video a partir de un prompt | mcp__heygen__generate_video_agent | prompt-optimizer.md → visual-styles.md → video-agent.md |
| Consultar estado / 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 con Avatar
Esta habilidad es para creación de video 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 multi-escena, usa la habilidad avatar-video en su lugar.
| El usuario dice | Esta habilidad | Habilidad Avatar Video |
|---|---|---|
| "Créame un video sobre X" | ✓ | |
| "Crea una demo de producto" | ✓ | |
| "Quiero que el avatar Y diga exactamente Z" | ✓ | |
| "Video multi-escena con fondos diferentes" | ✓ | |
| "WebM transparente para composición" | ✓ |
Archivos de Referencia
Flujo de Trabajo Principal
- references/prompt-optimizer.md - Cómo escribir prompts efectivos (flujo principal + reglas)
- references/visual-styles.md - 20 estilos visuales 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 Video Agent API
Fundamentos
- 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 duración predecible - Fija el avatar si es necesario — Usa
config.avatar_idpara mantener la 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