Crear Video
Genera videos completos a partir de un texto. Describe lo que quieres y la IA se encarga automáticamente de la escritura del guion, la selección de avatares, los visuales, la locución, el ritmo y los subtítulos.
Autenticación
Todas las solicitudes requieren el encabezado X-Api-Key. Configura 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": "Create a 60-second product demo video."}'
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 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 |
| 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 se documenta en los archivos de referencia.
Flujo de Trabajo por Defecto
Siempre usa 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 |
| 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 la 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, utiliza la habilidad avatar-video en su lugar.
| El Usuario Dice | Esta Habilidad | Habilidad Video de Avatar |
|---|---|---|
| "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 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 del Video Agent
Fundamentos
- references/video-status.md — Patrones de sondeo y URLs de descarga
- references/webhooks.md — Endpoints y eventos de webhooks
- references/assets.md — Subir imágenes, videos, audio como referencias
- references/dimensions.md — Resolución 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 completamente 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 consistencia entre videos - Sube archivos de referencia — Ayuda al agente a entender tu marca/producto
- Itera sobre los prompts — Refina en función de los resultados; el Video Agent es excelente para iteraciones rápidas