Audiovisual & IAheygen
API HeyGen: cómo automatizar vídeos con avatares
Descubre cómo usar la API de HeyGen para crear vídeos con avatares, consultar su estado y proteger credenciales en un flujo de producción audiovisual.
- Autor: humAIns
- 8 min de lectura
índice · 7 apartados
La API HeyGen sirve para conectar la generación de vídeos con avatares a un flujo propio: por ejemplo, producir versiones de una pieza a partir de guiones aprobados y registrar cada render en el sistema del equipo. La llamada de creación no entrega necesariamente el vídeo terminado en esa misma respuesta: devuelve un identificador y un estado inicial; después se consulta el trabajo o se recibe una notificación. Esta guía muestra el recorrido con la API v3, qué debes comprobar antes de automatizar y cómo proteger las credenciales.
Qué permite la API y cuándo compensa frente al editor
El editor web es adecuado para preparar una pieza manual, probar opciones o ajustar visualmente un vídeo aislado. Una integración por API resulta más interesante cuando el equipo repite el proceso: generar vídeos desde un catálogo de productos, preparar versiones de formación para distintos departamentos o incorporar un render a una aplicación interna. La API permite que el sistema envíe datos y reciba identificadores y resultados sin que una persona tenga que iniciar cada tarea desde la interfaz.
La documentación actual separa recursos y flujos distintos. Para un avatar que habla un guion, la referencia describe POST /v3/videos, con tipo avatar, identificador de avatar y voz. También existen endpoints para traducción, Video Agent y otras funciones. No mezcles ejemplos de versiones diferentes: en particular, usa el esquema publicado para v3, no copies parámetros antiguos de tutoriales que mencionen v2.
La API no elimina las decisiones de producción. Alguien debe aprobar el texto, elegir avatar y voz, definir el formato, revisar la pronunciación y comprobar el encuadre antes de entregar. Automatizar significa hacer repetibles los pasos que ya están definidos, no asumir que todo render sirve sin control.
Preparar la cuenta y guardar la clave
La guía oficial de API Key indica que se genera desde la página de claves de HeyGen. La autenticación de la API v3 usa la cabecera X-Api-Key y la base https://api.heygen.com. La clave es una credencial: debe permanecer en el backend y fuera del código público.
En desarrollo, configura una variable de entorno en el entorno del servidor. Por ejemplo, en una terminal Unix:
export HEYGEN_API_KEY="tu_clave_de_prueba"
En una aplicación desplegada, usa el sistema de secretos de la plataforma. Añade los ficheros locales de variables a las exclusiones del control de versiones; no pegues la clave en un componente frontend, en una petición desde el navegador ni en un ejemplo que publiques. Evita también imprimir cabeceras completas en logs de depuración.
La propia documentación propone comprobar una clave mediante GET /v3/users/me, pasando X-Api-Key. La respuesta incluye información de cuenta y facturación; no la compartas en capturas ni en tickets públicos. Que una clave funcione no confirma por sí solo qué cuota, plan o capacidad concreta tiene habilitada tu cuenta: valida ese dato en el panel y en la documentación vigente.
Primer vídeo de prueba: crear, consultar y descargar
Para una prueba controlada necesitas un avatar y una voz que tu cuenta pueda utilizar. La guía Generate Avatar Video explica, para Digital Twins, cómo consultar los looks con GET /v3/avatars/looks?avatar_type=digital_twin y obtener un avatar_id, y cómo consultar las voces. Usa identificadores de prueba de tu propia cuenta; no inventes un ID ni incluyas datos personales en el guion.
La siguiente petición reproduce el patrón documentado para crear un vídeo de avatar con la API v3. Sustituye los valores de ejemplo por IDs válidos de una cuenta autorizada y guarda la clave en la variable de entorno, nunca dentro del cuerpo de la petición:
curl --request POST \
--url https://api.heygen.com/v3/videos \
--header "X-Api-Key: $HEYGEN_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"type": "avatar",
"avatar_id": "ID_DE_AVATAR_DE_PRUEBA",
"script": "Hola. Este es un vídeo de prueba con contenido ficticio.",
"voice_id": "ID_DE_VOZ_DE_PRUEBA",
"title": "Prueba de integración"
}'
La referencia de POST /v3/videos marca type y avatar_id como obligatorios. El guion y la voz se incluyen en el ejemplo oficial para generar la locución; otros tipos de vídeo tienen cuerpos con campos diferentes. Una respuesta satisfactoria contiene data.video_id y un estado inicial, como waiting. Conserva ese identificador asociado a tu registro de trabajo: será la referencia para consultar el render.
La generación es asíncrona. Consulta GET /v3/videos/{video_id} con el identificador recibido. La respuesta da el estado y, al completar, puede incluir video_url, además de miniatura, duración e información de fallo si corresponde. Descarga el archivo cuando esté disponible: la guía de generación señala que las URL de salida firmadas caducan, así que no conviene guardarlas como enlaces permanentes.
La forma mínima del sondeo en shell sería:
curl --request GET \
--url "https://api.heygen.com/v3/videos/$VIDEO_ID" \
--header "X-Api-Key: $HEYGEN_API_KEY"
En una integración real, el código debe interpretar los estados, fijar un intervalo razonable, terminar al completarse o fallar y registrar un error útil. No mantengas un bucle infinito ni consultes sin pausa. Para cargas de trabajo mayores, considera los webhooks oficiales: reciben una notificación de éxito o fallo. Verifica la firma HMAC con el cuerpo HTTP original antes de confiar en el evento y haz el procesamiento idempotente, porque una notificación puede repetirse.
Pasar del experimento a producción
Empieza con un caso pequeño y datos ficticios. Mantén una cola de trabajos con un identificador interno, el video_id externo, el estado, fecha de solicitud y referencia a los materiales aprobados. Separa los errores recuperables —por ejemplo, una limitación temporal— de los errores de validación que requieren corregir la petición. La documentación de límites describe respuestas 429 Too Many Requests con Retry-After; espera ese periodo y aplica reintentos con backoff en vez de reintentar continuamente.
Las cuotas no son universales: la guía de Usage Limits indica que los límites dependen del plan y del tipo de endpoint. Consulta también la respuesta de error y las cabeceras de rate limit para ajustar el ritmo. No presupuestes un coste por vídeo basándote solo en el nombre del plan. La página oficial de precios muestra planes y créditos, pero lo que se aplica a API y a tu espacio de trabajo debe confirmarse en la cuenta y en la documentación comercial vigente; la tarifa y los límites pueden cambiar.
Antes de entregar, revisa el vídeo completo, incluidos nombres propios, números, pronunciación, sincronía y encuadre. Comprueba que la relación de aspecto y resolución corresponden al destino. La guía de límites enumera formatos y máximos de entrada y salida, y la referencia concreta puede imponer requisitos según el modo elegido. Trata el resultado como un máster pendiente de control de calidad, no como una pieza publicada automáticamente.
Si el flujo atiende a varios clientes, añade permisos por proyecto, trazabilidad de quién aprobó cada guion y un procedimiento para borrar o retirar materiales cuando corresponda. No pongas en una cola compartida contenido identificable sin definir quién puede acceder a él y durante cuánto tiempo.
Imagen, voz, privacidad y condiciones de uso
Antes de generar un avatar basado en una persona real, confirma que tienes autorización suficiente para ese uso, canal, duración y finalidad. Aplica el mismo criterio a voces grabadas, clones de voz, fotografías y vídeos de referencia. Guarda el consentimiento y su alcance junto con el expediente de producción, pero restringe el acceso y conserva solo lo necesario.
Las condiciones de HeyGen y sus políticas pueden regir el uso del servicio y del contenido; léelas antes de utilizar la API para una campaña o una producción de terceros. Además, analiza las obligaciones de protección de datos y transparencia que correspondan a tu caso y jurisdicción. Esta guía no constituye asesoramiento jurídico. Si no puedes verificar que el permiso cubre el uso previsto, no automatices esa generación hasta aclararlo con quien aporta la imagen o la voz.
Para equipos audiovisuales, la automatización funciona mejor cuando hay un proceso de revisión definido: guion aprobado, recurso autorizado, render con parámetros registrados y validación humana de la salida. Un webhook confirma un estado técnico; no certifica que la pieza sea correcta, legal o adecuada para el público.
Preguntas frecuentes
¿Necesito una cuenta para usar la API de HeyGen?
Sí. Debes generar una clave en la página de API keys e incluirla en las solicitudes mediante la cabecera X-Api-Key. Comprueba en tu cuenta la elegibilidad, límites y modalidad de facturación antes de desplegar un flujo.
¿Cómo consulto si un vídeo ha terminado?
Usa el video_id de la respuesta de creación con GET /v3/videos/{video_id} y consulta el estado hasta que el trabajo termine o falle. Alternativamente, configura un webhook, verifica su firma y procesa el evento de forma idempotente.
¿Puedo automatizar vídeos para clientes?
Puedes integrar la generación en un proceso de trabajo, pero la viabilidad comercial depende de las condiciones del servicio, el plan aplicable, los derechos del material y los permisos obtenidos. Confirma todos esos puntos para el uso concreto antes de prometer entregas.
¿Dónde guardo la clave?
En una variable de entorno del servidor o un gestor de secretos. No la envíes al navegador ni la guardes en un repositorio; rota la credencial si pudo quedar expuesta.
Sigue aprendiendo
Si quieres comparar flujos de principio a fin, consulta la guía sobre crear vídeos con IA, el artículo de doblaje con IA y la guía de HeyGen en español, centrada en el uso de la interfaz. Para llevar estas herramientas a un proceso audiovisual profesional, conoce el curso de IA para Audiovisual.
Sigue leyendo en humAIns