Video con Avatar
Crea videos con avatares de IA con 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. Configura 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__*), prefijarlas sobre las llamadas HTTP directas: manejan la autenticación y el formato de solicitud 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→ elegir un avatar, obtener vista previa, anotaravatar_idydefault_voice_id. Ver avatars.md - Listar voces (si es necesario) —
GET /v2/voices→ elegir una voz que coincida con el género/idioma del avatar. Ver voices.md - Escribir el guion — Estructurar las escenas con un concepto cada una. Ver scripts.md
- Generar el video —
POST /v2/video/generatecon avatar, voz, guion y fondo por escena. Ver video-generation.md - Esperar a que termine —
GET /v2/videos/{video_id}hasta que el estado seacompleted. Ver 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 |
| Agregar fondos personalizados | backgrounds.md |
| Agregar subtítulos | captions.md |
| Agregar superposiciones de texto | text-overlays.md |
| Crear video WebM transparente | video-generation.md (sección WebM) |
| Usar plantillas | templates.md |
| Crear avatar desde foto | photo-avatars.md |
| Verificar estado del video / descargar | video-status.md |
| Subir recursos (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 y configuras cada escena.
Si el usuario solo quiere describir una idea de video y que la IA se encargue del resto (guion, avatar, visuales), usa la habilidad create-video en su lugar.
| El Usuario Dice | Habilidad Crear Video | 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 videos por lote con especificaciones exactas" | ✓ |
Archivos de Referencia
Creación de Video Principal
- references/avatars.md - Listado de avatares, estilos, selección de
avatar_id - references/voices.md - Listado de voces, configuraciones regionales, velocidad/tono
- references/scripts.md - Escritura de 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 - Agregar texto con fuentes y posicionamiento
- references/captions.md - Subtítulos y leyendas generados automáticamente
Funciones Avanzadas
- references/templates.md - Listado de plantillas y sustitución de variables
- references/photo-avatars.md - Creación de avatares a partir de fotos
- references/webhooks.md - Puntos finales y eventos de webhook
Integración
- references/remotion-integration.md - Uso de HeyGen en composiciones de Remotion
Base
- references/video-status.md - Patrones de sondeo y URLs de descarga
- references/assets.md - Carga de imágenes, videos, audio
- references/dimensions.md - Resoluciones y relaciones de aspecto
- references/quota.md - Sistema de créditos y límites de uso
Buenas Prácticas
- Previsualiza los avatares antes de generar — Descarga
preview_image_urlpara que el usuario pueda ver el avatar antes de comprometerse - Usa la voz predeterminada del avatar — La mayoría de los avatares tienen un
default_voice_idpre-coincidido para resultados naturales - Alternativa: igualar género manualmente — Si no hay voz predeterminada, asegúrate de que los géneros del avatar y la voz coincidan
- Usa el modo de prueba para desarrollo — Establece
test: truepara evitar consumir créditos (el resultado tendrá marca de agua) - Configura tiempos de espera generosos — La generación de videos suele tomar de 5 a 15 minutos, a veces más
- Valida las entradas — Verifica que los IDs de avatar y voz existan antes de generar