Video con Avatar
Crea videos con avatares de IA teniendo control total sobre avatares, voces, guiones, escenas y fondos. Construye videos de una o múltiples escenas con configuración exacta usando la API /v2/video/generate de HeyGen.
Autenticación
Todas las solicitudes requieren el encabezado X-Api-Key. Establece la variable de entorno HEYGEN_API_KEY.
curl -X GET "https://api.heygen.com/v2/avatars" \
-H "X-Api-Key: $HEYGEN_API_KEY"
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: ellas manejan la autenticación y el formato de las solicitudes automáticamente.
| Tarea | Herramienta MCP | Alternativa (API Directa) |
|---|---|---|
| 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} |
La generación de video (POST /v2/video/generate) y el listado de avatares/voces se realizan mediante llamadas directas a la API — consulta los archivos de referencia a continuación.
Flujo de Trabajo Predeterminado
- Listar avatares —
GET /v2/avatars→ elige un avatar, previsualízalo, anotaavatar_idydefault_voice_id. Consulta avatars.md - Listar voces (si es necesario) —
GET /v2/voices→ elige una voz que coincida con el género/idioma del avatar. Consulta voices.md - Escribir el guion — Estructura escenas con un concepto cada una. Consulta scripts.md
- Generar el video —
POST /v2/video/generatecon avatar, voz, guion y fondo por escena. Consulta video-generation.md - Sondear hasta completar —
GET /v2/videos/{video_id}hasta que el estado seacompleted. Consulta video-status.md
Referencia Rápida
| Tarea | Leer |
|---|---|
| Listar y previsualizar avatares | avatars.md |
| Listar y seleccionar voces | voices.md |
| Escribir y estructurar guiones | scripts.md |
| Generar video (una o múltiples escenas) | video-generation.md |
| Añadir fondos personalizados | backgrounds.md |
| Añadir subtítulos | captions.md |
| Añadir superposiciones de texto | text-overlays.md |
| Crear video WebM transparente | video-generation.md (sección WebM) |
| Usar plantillas | templates.md |
| Crear avatar a partir de foto | photo-avatars.md |
| Verificar estado del video / descargar | video-status.md |
| Subir activos (imágenes, audio) | assets.md |
| Usar con Remotion | remotion-integration.md |
| Configurar webhooks | webhooks.md |
Cuándo Usar Esta Habilidad vs. Crear Video
Esta habilidad es para control preciso — tú eliges el avatar, escribes el guion exacto, configuras cada escena.
Si el usuario solo quiere describir una idea de video y dejar que la IA haga el resto (guion, avatar, imágenes), usa la habilidad create-video en su lugar.
| El usuario dice | Create Video Skill | Esta Habilidad |
|---|---|---|
| "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" | ✓ | |
| "Usa esta voz específica para mi guion" | ✓ | |
| "Genera lotes de videos con especificaciones exactas" | ✓ |
Archivos de Referencia
Creación de Video Principal
- references/avatars.md - Listar avatares, estilos, selección de avatar_id
- references/voices.md - Listar voces, locales, velocidad/tono
- references/scripts.md - Escribir guiones, pausas, ritmo
- references/video-generation.md - POST /v2/video/generate y videos de múltiples escenas
Personalización de Video
- references/backgrounds.md - Colores sólidos, imágenes, fondos de video
- references/text-overlays.md - Añadir texto con fuentes y posicionamiento
- references/captions.md - Subtítulos y leyendas generados automáticamente
Funciones Avanzadas
- references/templates.md - Listado de plantillas y reemplazo de variables
- references/photo-avatars.md - Crear avatares a partir de fotos
- references/webhooks.md - Endpoints y eventos de webhooks
Integración
- references/remotion-integration.md - Usar HeyGen en composiciones de Remotion
Base
- references/video-status.md - Patrones de sondeo y URLs de descarga
- references/assets.md - Subir imágenes, videos, audio
- references/dimensions.md - Resolución y relaciones de aspecto
- references/quota.md - Sistema de créditos y límites de uso
Mejores Prácticas
- Previsualizar avatares antes de generar — Descarga
preview_image_urlpara que el usuario pueda ver el avatar antes de comprometerse - Usar la voz predeterminada del avatar — La mayoría de los avatares tienen un
default_voice_idpreasignado para resultados naturales - Alternativa: emparejar género manualmente — Si no hay voz predeterminada, asegúrate de que los géneros del avatar y la voz coincidan
- Usar modo de prueba para desarrollo — Establece
test: truepara evitar consumir créditos (la salida tendrá marca de agua) - Establecer tiempos de espera generosos — La generación de video a menudo toma de 5 a 15 minutos, a veces más
- Validar entradas — Verifica que los IDs de avatar y voz existan antes de generar