Un video de avatar de HeyGen es un guion, una voz y una apariencia que articula las palabras. Puedes construir eso en AI Studio para una introducción de curso, o enviar los mismos tres elementos a POST /v3/videos. La traducción dobla el audio. No reescribe palabras pintadas en el fotograma. Este laboratorio usa el centro de ayuda y los documentos v3 como se leyeron en octubre de 2026.
Escribe el guion en AI Studio
El artículo de guion de AI Studio dice que cada escena tiene su propio guion. Add Scene, luego elige Blank o From Template, y escribe en el editor de guion. Asigna un avatar, una voz y un fondo después de que las palabras existan. El guion es lo que dice el avatar. No es una pista de subtítulos a menos que agregues subtítulos por separado.
El mismo artículo dice que puedes descargar o cargar el guion completo desde el menú superior izquierdo, incluidas las posiciones de pausa. El archivo se lee en el navegador y no se carga como el archivo de guion en sí. Límites indicados allí:
- Una línea, párrafo o celda de más de 1.000 caracteres se divide en más de un segmento.
- Un segmento se asigna a una escena, en orden. Los segmentos adicionales crean escenas adicionales.
- Las líneas vacías y las celdas vacías se omiten.
- Si el video ya tiene texto, la carga agrega escenas. No reemplaza lo que hay allí.
- Si seleccionas varios archivos, solo se usa el primero.
.docno es aceptado. Guarda archivos de Word como.docx.- Para
.txt, pon cada escena en su propia línea. Para Excel o CSV, pon cada escena en su propia celda.
Para una introducción de curso, escribe una oración por escena. La escena uno es la promesa («esta lección soluciona ImagePullBackOff»). La escena dos es el comando que ejecutará el espectador. La escena tres es donde los pasos escritos viven en tu sitio. Las escenas cortas son más fáciles de reemplazar cuando una bandera cambia.
La pronunciación de nombres de productos es un problema de glosario, no un problema de ortografía. El artículo de guion señala la corrección de pronunciación en el editor. La sección Brand Glossary a continuación es la versión durable de esa corrección.
Avatares y voces
En el producto, un Brand System tiene una pestaña Avatars. Add Brand Avatar elige los looks que pertenecen a esa marca, para que una serie de lecciones no se desvíe entre caras de stock.
En la API, avatar_id puede ser un avatar de video o un look de avatar de foto. La referencia de crear video dice que los tipos son studio avatar, digital twin y photo avatar. Si omites engine, el servidor usa Avatar IV. Configura engine.type a avatar_v solo cuando intentes Avatar V. La página de precios empresariales dice que Avatar V es para digital twins. No envíes Avatar V para un look que la referencia dice que es rechazado. Los avatares fotográficos pueden tomar un motion_prompt en cualquier motor. Los avatares de video toman motion_prompt cuando el motor es Avatar V. La referencia dice que Avatar IV rechaza ese prompt para avatares de video.
expressiveness (high, medium, low) es solo avatares fotográficos en Avatar IV. Por defecto es low cuando se omite, y se rechaza para Avatar V.
Las voces son ids, no nombres mostrados. GET /v3/voices las enumera. La página de límites de uso dice que esa lista por defecto es 20 y limita una página a 100. GET /v3/avatars por defecto es 20 y limita a 50. Ambos usan limit y next_token.
El inicio rápido también nombra dos caminos de clonación en el producto: una voz instantánea de una grabación, y un clon profesional entrenado en 20 o más minutos de audio. Pasa el voice_id resultante en la llamada de video. voice_settings opcionales en create incluyen speed, pitch, volume y locale.
Puedes omitir la síntesis y pasar audio_url o audio_asset_id en lugar de script. Esos dos se excluyen mutuamente con dejar que el guion impulse la voz. Una URL que pases debe ser pública. La nota de solución de problemas del inicio rápido dice que una download_failed de 400 significa que la URL no se pudo recuperar.
Sistema de marca y glosario
El artículo de ayuda lo llama Brand System, no una pila suelta de carga. Pestañas:
- Brand Spec: colores (incluido un valor hex) y fuentes para Body, Caption, Display, Heading y Heading 2.
- Assets: imágenes y videos, a través de Upload Brand Assets.
- Logos: Upload Brand Logos.
- Motion: piezas de movimiento guardadas de Video Agent.
- Avatars: Add Brand Avatar.
Límites de carga en ese artículo, a partir de la página leída en octubre de 2026: resolución hasta 4096 por 4096. Imágenes y logotipos JPG o PNG hasta 200 MB (también indica 4167 por 4167). MP4 o MOV hasta 200 MB. Fuentes TTF u OTF hasta 100 MB.
Aplicas un Brand System desde AI Studio con Brand en el menú derecho, o desde Video Agent por el control + junto al prompt, luego Brand System.
Brand Glossary es la segunda mitad de la marca. Abre Brand en la navegación izquierda, luego Brand Glossary.
- Las reglas de pronunciación afectan síntesis de texto a voz de AI Studio. El artículo dice que esas palabras se muestran en púrpura itálica en el editor de guion.
- Las reglas de traducción son Force Translate (usa esta redacción) o Don’t Translate (deja el término). Se aplican cuando un trabajo de Video Translation usa el glosario.
En la API, brand_glossary_id cambia cómo se pronuncia script. La referencia dice que un audio_url o audio_asset_id suministrado no se reescribe por el glosario. Los subtítulos aún muestran las palabras del guion original. La pronunciación es solo el audio. Descubre ids con GET /v3/brand-glossaries.
folder_id no es un kit de marca. La referencia dice que un id de proyecto de kit de marca se rechaza con 404 antes de crear nada. Omite folder_id, o pasa un id de carpeta real de POST /v3/folders.
Traducción y doblaje
Video Translation, en el artículo de ayuda, re-vocaliza la pista hablada en otro idioma, usando la voz del hablante original, y puede sincronizar labios. Cargas un video, eliges idiomas de destino y un motor de traducción, y ejecutas Translate.
Lo que se mueve:
- Audio hablado, en la voz del hablante original.
- Movimiento de labios, si lo activas.
- Subtítulos en pantalla, si los activas.
Lo que se mantiene:
- Texto que es parte de la imagen: títulos, terceras inferiores, subtítulos codificados.
- Música de fondo, a menos que habilites Remove Background Sound.
Los videos centrados en canto y música se llaman inconsistentes. Los idiomas de origen no compatibles fallan inmediatamente y, el artículo dice, no utilizan créditos. Si necesitas las palabras en pantalla en el nuevo idioma, construye ese video en el estudio. No esperes que la traducción repinte píxeles.
El punto final de lista de API GET /v3/video-translations está en la página de límites de uso (tamaño de página predeterminado 10, máx 100). Este laboratorio no muestra un cuerpo POST de traducción, porque ese esquema de solicitud no estaba en las páginas leídas aquí. El artículo de ayuda sí dice que la API puede ejecutar traducción. Busca la llamada de creación actual en los documentos para desarrolladores antes de automatizarla.
El uso de la API se factura por separado de los planes de la aplicación. El artículo de ayuda de precios de API dice que los créditos de API son pago por uso y no son la misma cartera que una suscripción Creator, Pro o Business. Este laboratorio no copia tasas por segundo. La página de autoservicio y la página empresarial utilizan diferentes unidades.
Genera un video desde la API
URL base https://api.heygen.com. Crea una clave en la página de claves de API y expórtala tú mismo. El inicio rápido verifica la clave con GET /v3/users/me. Un 401 significa que el encabezado falta o la clave está inactiva.
export HEYGEN_API_KEY="your-key"
Enumera un look y una voz, luego crea. El inicio rápido escribe el encabezado como X-Api-Key. La referencia REST escribe x-api-key. Los nombres de encabezado HTTP no distinguen mayúsculas de minúsculas. Usa uno de ellos, no una clave de cadena de consulta.
curl "https://api.heygen.com/v3/avatars?limit=20" \
-H "X-Api-Key: $HEYGEN_API_KEY"
curl "https://api.heygen.com/v3/voices?limit=20" \
-H "X-Api-Key: $HEYGEN_API_KEY"
curl -X POST "https://api.heygen.com/v3/videos" \
-H "X-Api-Key: $HEYGEN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4f1c0b2e-7a11-4d5e-9c31-2b6a8e0d11ab" \
-d "{\"type\":\"avatar\",\"avatar_id\":\"YOUR_AVATAR_ID\",\"voice_id\":\"YOUR_VOICE_ID\",\"script\":\"This lesson shows how to read a CrashLoopBackOff event before you change the image.\",\"title\":\"CrashLoop lesson intro\",\"aspect_ratio\":\"16:9\"}"
El cuerpo de respuesta incluye video_id y status. El estado de ejemplo del esquema es waiting. Una Idempotency-Key de 1 a 255 caracteres de letras, dígitos y _:.- hace que un reintento dentro de la ventana documentada devuelva la respuesta original en lugar de un segundo render. Un duplicado aún en vuelo devuelve 409.
Sondea hasta que el trabajo termine:
curl "https://api.heygen.com/v3/videos/VIDEO_ID" \
-H "X-Api-Key: $HEYGEN_API_KEY"
El inicio rápido trata completed y failed como los estados terminales para GET /v3/videos/{video_id}, y lee video_url de esa carga. En caso de fallo, lee failure_code y failure_message. Un 429 significa que alcanzaste un límite de tarifa o concurrencia. Honra Retry-After y retrocede. También puedes pasar callback_url en create y omitir el bucle de sondeo.
Restricciones de salida de la página de límites de uso: el video de avatar es de 25 fotogramas por segundo. La anchura y altura deben estar cada una entre 128 y 4096 píxeles. La salida predeterminada es 1080p. La referencia de crear de aspect_ratio incluye 16:9 (el predeterminado), 9:16, 4:5, 5:4, 1:1 y auto. Una escena más larga que 30 minutos falla durante el render. Una solicitud de avatar es una escena, así que 30 minutos es el video completo. Los videos de estudio y plantilla de múltiples escenas pueden ejecutarse más tiempo, siempre que cada escena se mantenga bajo ese límite. La página también limita escenas a 50. 4k en la referencia de crear es para digital twins de Avatar III y avatares de estudio, no un cambio universal.
output_format por defecto es mp4. caption opcional puede solicitar un archivo srt. background opcional toma un valor de color, una URL o un id de activo.
Existen otros dos caminos de creación, y no son la llamada de avatar de guion:
POST /v3/video-agentstoma unprompt. El inicio rápido sondea la sesión para unvideo_id, luego sondea el video. Ese es Video Agent: el servicio elabora el pedazo.POST /v3/models/videoscon modeloheygen-video-1genera una escena desde un prompt (texto, imagen o referencia). La página del modelo dice que es una herramienta diferente de los motores de avatar detrás dePOST /v3/videos.
Usa /v3/videos cuando ya escribiste las palabras. El inicio rápido dice que v1 y v2 permanecen compatibles hasta el 31 de octubre de 2026. El código nuevo debe ser v3.
Una herramienta de flujo de trabajo puede POST esta carga y sondear. El patrón para una llamada HTTP desencadenada por webhook está en n8n first workflow. Un agente que decide cuándo renderizar es un diseño diferente. Ver qué es la IA agentiva.
Introducciones de cursos y tutoriales cortos
Usa una introducción de avatar cuando la lección es una cabeza parlante más una grabación de pantalla posterior que editas tú mismo. HeyGen es un lugar pobre para demostrar una terminal en vivo. Registra la terminal por separado, y deja que el avatar maneje los 20 a 40 segundos de encuadre.
Mantén kubectl, nombres de imagen y ortografía de banderas en el Brand Glossary para que la voz no invente una pronunciación. Pon el comando escrito en pantalla en el editor si los estudiantes deben leerlo. La traducción no convertirá ese superposición.
Para una serie, bloquea un avatar, una voz, un Brand System y 16:9. Cambia a 9:16 solo para un corte, como un segundo render, no recortando la lección en una herramienta externa y esperando que la boca aún coincida.
La investigación del guion puede comenzar en Perplexity. El borrador hablado aún debe coincidir con un documento que abriste. Un pase de Gemini sobre el esquema es opcional. La hoja de trucos de herramientas de Gemini es el lado de la API de eso, no un renderizador de video.
Lista de verificación de calidad
- Lee el guion en voz alta. Una idea por escena. Divide cualquier cosa que el importador divida en 1.000 caracteres.
- Confirma
avatar_idyvoice_iddesde los puntos finales de lista, no desde una captura de pantalla. - Configura
aspect_ratioal reproductor que envías (16:9 para una página de curso). - Agrega reglas de glosario para nombres de productos y herramientas CLI antes de renderizar un lote.
- No hornees el título de la lección en los píxeles si traducirás. Agrega subtítulos como subtítulos.
- Espera a
completed. Un cuerpowaitingo en progreso no tiene archivo final. - Reproduce el mp4 con sonido. Verifica los primeros cinco segundos del movimiento de labios y cualquier palabra que agregues al glosario.
- En
failed, copiafailure_codeyfailure_messageantes de reintentar. Cambia la clave de idempotencia solo cuando tengas la intención de un nuevo video. - En 401, arregla la clave. En 429, espera
Retry-After. En 400download_failed, la URL de audio o fondo no es públicamente recuperable. - Mantén la clave fuera del repositorio. Las instrucciones del agente de inicio rápido dicen exportarla localmente y no pegarla en un chat.
Preguntas frecuentes
¿Qué punto final de la API de HeyGen crea un video de avatar a partir de un guion?
POST https://api.heygen.com/v3/videos con JSON type avatar, más avatar_id, script y voice_id. El encabezado es X-Api-Key. La llamada de creación devuelve video_id y un estado como waiting. Sondea GET /v3/videos/{video_id} hasta que el estado sea completed o failed. v1 y v2 permanecen compatibles hasta el 31 de octubre de 2026, según el inicio rápido leído en octubre de 2026.
¿La traducción de video de HeyGen reescribe texto en pantalla?
No. El artículo de ayuda de traducción de video dice que el audio hablado se re-vocaliza, y el movimiento de labios y las leyendas en pantalla son opcionales. El texto cocido en la imagen, gráficos y leyendas codificadas permanecen como están. La música de fondo se mantiene a menos que habilites Remove Background Sound. La letra cantada no es un caso confiable.
¿Qué es un sistema de marca HeyGen?
Es el nombre actual del centro de ayuda para el kit de marca: colores, fuentes, logotipos, imágenes, elementos de movimiento y avatares elegidos. Brand Glossary es separado. Contiene reglas de pronunciación para síntesis de texto a voz de AI Studio y reglas de traducción (Force Translate o Don’t Translate) utilizadas cuando ejecutas Video Translation con el glosario seleccionado.
¿Por qué POST /v3/videos devolvió 404 para mi carpeta?
La referencia de crear video dice que folder_id debe ser una carpeta en la que el llamador pueda escribir, no en la papelera. Un id de otro espacio de trabajo, o un proyecto de otro tipo como un kit de marca, se rechaza con 404 antes de que se cree un video. Enumera avatares con GET /v3/avatars y voces con GET /v3/voices en lugar de pegar un id de kit de marca en folder_id.
Cómo se verificó esta guía
Escrita a mano a partir de la documentación oficial, con cada comando comprobado de nuevo y una segunda revisión antes de publicar. Última revisión: .
Fuentes oficiales consultadas para este artículo
- help.heygen.com/en/articles/11381771-how-to-write-scripts-in-the-editing-studio
- help.heygen.com/en/articles/9889198-how-to-create-a-brand-system
- help.heygen.com/en/articles/10029081-how-to-get-started-with-video-translation
- help.heygen.com/en/articles/10060327-heygen-api-pricing-subscriptions-explained
- docs.heygen.com/docs/quick-start
- developers.heygen.com/reference/create-video
- developers.heygen.com/docs/usage-limits
- developers.heygen.com/docs/models/heygen-video
