![]()
La HeyGen Avatar 6 API puede crear un vídeo de presentador a partir de nada más que un guion. En el modo de avatar público indicas uno de los 1,248 looks de stock de HeyGen, envías hasta 1,000 caracteres de text, eliges una de 102 voces y heygen-avatar-6 (o heygen-avatar-6-turbo) devuelve un MP4 con sincronización labial. Sin foto, sin grabación y sin paso de texto a voz por tu parte. Esta guía explica cómo elegir un look y una voz del catálogo, dirigir los gestos con prompt, escoger la forma del encuadre y cuánto cuesta una solicitud de texto. También puedes explorar los looks en la página del modelo HeyGen Avatar 6.
La solicitud de texto a avatar
Este es el cuerpo documentado para el modo de avatar público con texto:
{
"model": "heygen-avatar-6-turbo",
"input": {
"avatar": "Abigail Office Front",
"text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
"voice": "Warm Pro Narrator",
"prompt": "Speak with calm confidence and nod slightly at the end.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
| Campo | Obligatorio | Regla |
|---|---|---|
avatar | Sí | Uno de 1,248 nombres de look |
text | Sí (en lugar de audio_url) | 1–1,000 caracteres |
voice | No | Uno de 102 nombres; por defecto Warm Pro Narrator |
prompt | No | Hasta 1,200 caracteres de dirección |
aspect_ratio | No | 16:9 (por defecto), 9:16, 1:1, 4:5, 5:4 |
resolution | No | 1080p (por defecto) o 2K |
La presencia de avatar es lo que selecciona este modo. No envíes además image_urls ni video_url; usa las entradas de un solo modo por solicitud. Envía a POST https://api.poyo.ai/api/generate/submit y consulta /api/generate/status/{task_id} como en la guía de la HeyGen Avatar 6 API.
Elige un look de avatar del catálogo
PoYo publica todos los nombres en la página Avatars and Voices y como catálogo JSON. El catálogo tiene cinco claves:
| Clave | Contenido |
|---|---|
models | heygen-avatar-6, heygen-avatar-6-turbo (los mismos nombres funcionan en ambos) |
default_voice | Warm Pro Narrator |
avatars | Los 1,248 nombres de look, en una lista plana |
avatars_by_person | Los mismos looks agrupados en 156 personas |
voices | Los 102 nombres de voz |
Cada persona tiene uno o varios looks, y cada look es un valor de avatar distinto. Abigail tiene cinco (Abigail (Upper Body), Abigail Office Front, Abigail Office Side, Abigail Sofa Front, Abigail Sofa Side); Annie tiene 54; ocho personas tienen un único look. Los nombres describen el escenario, la ropa y el ángulo de cámara, lo que normalmente basta para elegir sin previsualizar:
| Quieres | Busca nombres como | Ejemplos |
|---|---|---|
| Presentador mirando a cámara | Front | Abigail Office Front, Bryan Suit Front |
| Ángulo de tres cuartos | Side | Abigail Office Side |
| Sentado, informal | Sofa, Sitting, Lounge | Annie Sofa Sitting Front |
| Un rol o un escenario | Doctor, Nurse, Yoga, Tech Expert | Ann Doctor Standing, Adriana Nurse Front, Amelia Yoga Front, Bryan Tech Expert |
Unos 480 nombres contienen Front y unos 430 contienen Side. Para una serie de vídeos explicativos, elige una persona y quédate con sus looks Front, para que el presentador sea el mismo en todos los vídeos. Usa el look Side correspondiente para los planos de corte.
Los nombres coinciden sin importar mayúsculas/minúsculas ni espacios extra, así que abigail office front selecciona Abigail Office Front. PoYo comprueba avatar contra la lista en el envío, así que una errata devuelve un 400 inmediato en lugar de una tarea fallida. Valida antes en tu propio código:
import requests
catalog = requests.get(
"https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()
def norm(name: str) -> str:
return " ".join(name.split()).lower()
AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])
def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
if norm(avatar) not in AVATARS:
raise ValueError(f"unknown avatar: {avatar!r}")
if not 1 <= len(text) <= 1000:
raise ValueError("text must be 1-1,000 characters")
if voice is not None and voice not in VOICES:
raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
if prompt is not None and len(prompt) > 1200:
raise ValueError("prompt must be at most 1,200 characters")
body = {"avatar": AVATARS[norm(avatar)], "text": text,
"aspect_ratio": aspect_ratio, "resolution": resolution}
if voice:
body["voice"] = voice
if prompt:
body["prompt"] = prompt
return {"model": model, "input": body}
La comprobación de la voz usa nombres exactos a propósito; la siguiente sección explica por qué.
Elige una voz
voice decide quién lee text. Si lo omites, obtienes Warm Pro Narrator. Las 102 voces incluyen nombres simples (Andrew, Ivy, Jessica Anne Bogart), descriptivos (Calm Chloe, Professor Dean, Radio Rick, Chill Brian) y algunos con una etiqueta de estilo en el nombre.
Hay tres cosas que confunden a la gente:
- Los espacios finales pueden importar. La documentación señala que
HopeyHope(con un espacio final) son dos voces distintas.Archer,Cassidy,Adam Stone,Spuds OxleyyAndrew Rizztambién terminan con un espacio en el catálogo. Copia los nombres del JSON en lugar de volver a escribirlos. - Algunos nombres contienen emojis o sufijos con aspecto de archivo, como
Cute Chloe - Friendly 😊oBrenda - UGC - 1.mp4. Esos caracteres forman parte del nombre. Envía el cuerpo de la solicitud como JSON en UTF-8 y el nombre pasará sin cambios. - La voz no está ligada al avatar. Cualquiera de las 102 voces puede leer para cualquiera de los 1,248 looks. Elige una voz que encaje con la persona en pantalla; en nuestras pruebas del día del lanzamiento combinamos
Bryan Tech ExpertconAndrewyAbigail Office FrontconJessica Anne Bogart.
voice solo se aplica cuando envías text. Si envías audio_url en su lugar, el avatar dice tu grabación y voice no se usa.
Dirige los gestos con prompt
prompt acepta hasta 1,200 caracteres de dirección para gestos, expresión y postura. El informe técnico de HeyGen describe la técnica: «Escribe la acción junto a las palabras. Avatar 6 la ejecuta justo en el momento indicado». Su ejemplo: «Farmacéutico amable. Al decir "Hola", levanta el pulgar. Al decir "el mostrador de la izquierda", señala hacia un lado con el dedo índice».
Un patrón que sigue ese formato:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Bryan Tech Expert",
"text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
"voice": "Andrew",
"prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
Consejos para que los prompts sean útiles:
- Cita las palabras exactas de
texten las que debe caer cada acción, para que la indicación no sea ambigua. - Describe primero un rol o un estado de ánimo («Friendly product expert»), y después las indicaciones.
- Omite
promptcuando no tengas indicaciones concretas. La página de lanzamiento de Avatar 6 de HeyGen dice que el modelo «ajusta el gesto, la emoción y la expresión a tu guion» por sí solo.
Elige la relación de aspecto según dónde se publique
aspect_ratio solo existe en el modo de avatar público; los modos de foto y de vídeo de referencia conservan la forma de la entrada.
| Ubicación | aspect_ratio |
|---|---|
| Sitio web, YouTube, lección de LMS | 16:9 (por defecto) |
| Shorts, Reels, TikTok, stories | 9:16 |
| Publicación cuadrada en el feed, tarjeta dentro de la app | 1:1 |
| Publicación vertical en el feed | 4:5 |
| Publicación horizontal en el feed | 5:4 |
resolution es independiente: 1080p o 2K con cualquier relación. 2K cuesta más por segundo, así que genera los borradores en 1080p.
Cuánto durará el vídeo y cuánto cuesta
Con texto, el vídeo dura lo que tarde el avatar en leerlo, hasta 1,000 caracteres. Se te factura la duración del vídeo terminado, redondeada hacia arriba a segundos enteros. Los créditos se reservan al enviar y se liquidan según los segundos reales cuando termina la tarea.
Nuestras pruebas del día del lanzamiento en la API de producción, 19 de noviembre de 2026 (16:9, 1080p):
| Modelo | Avatar / voz | Guion | Salida | Coste a precios actuales | Tiempo real |
|---|---|---|---|---|---|
heygen-avatar-6-turbo | Abigail Office Front / Jessica Anne Bogart | 27 palabras | 10.16 s | 110 créditos ($0.55) | Unos 2.4 min |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21 palabras | 6.88 s | 140 créditos ($0.70) | Unos 2 min |
Eso equivale a unas 2.7 y 3.1 palabras por segundo en estas dos ejecuciones, útil para un presupuesto aproximado pero no una garantía, ya que el ritmo varía según la voz y el guion. Tarifas por segundo: Turbo 10 créditos ($0.05) en 1080p o 18 ($0.09) en 2K; Avatar 6 20 créditos ($0.10) o 29 ($0.145). Consulta Precios de la HeyGen Avatar 6 API para más detalles.
Como las tareas de texto mantienen una reserva mientras se ejecutan, lanzar muchas a la vez puede devolver HTTP 200 con code 402 en el cuerpo (insufficient_credits_error). En nuestra prueba, una tercera solicitud fue rechazada con: «esta solicitud necesita al menos 252 créditos, y ya hay 344 créditos reservados por tus tareas de texto de HeyGen Avatar 6 sin terminar». Pon en cola los trabajos de texto o mantén un saldo que cubra las reservas en curso. Usa Turbo mientras iteras; la comparativa Avatar 6 frente a Turbo muestra cuándo cambiar.
Preguntas frecuentes
¿Puede la HeyGen Avatar 6 API convertir texto en un vídeo de avatar parlante?
Sí. En el modo de avatar público, envía avatar, hasta 1,000 caracteres de text y, opcionalmente, voice. No hace falta ningún archivo de audio.
¿Dónde está la lista de avatares y voces de la HeyGen Avatar 6 API?
En la página Avatars and Voices de la documentación de PoYo, y como catálogo JSON descargable con las claves avatars, avatars_by_person y voices.
¿Cuál es la voz por defecto de la HeyGen Avatar 6 API?
Warm Pro Narrator, que se usa cuando se omite voice.
¿Puedo usar mi propia foto con texto en lugar de un avatar de stock?
No. text solo funciona en el modo de avatar público. Para tu propia foto, usa el modo de foto con image_urls y un audio_url; si hace falta, genera antes el audio con un modelo TTS.
¿Qué relaciones de aspecto admite el modo de texto a avatar de HeyGen Avatar 6?
16:9, 9:16, 1:1, 4:5 y 5:4, en 1080p o 2K.
¿Cómo se factura una solicitud de texto en la HeyGen Avatar 6 API?
Por la duración del vídeo terminado, redondeada hacia arriba a segundos enteros, a la tarifa por segundo del modelo. Los créditos se reservan en el envío y se liquidan cuando finaliza la tarea.