how-tos

HeyGen Avatar 6 API de texto a avatar: vídeos de presentador a partir de un guion, sin archivo de audio

Poyo.ai Team
10 min read
Share:

HeyGen Avatar 6 API de texto a avatar: un vídeo de presentador a partir de un guion

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"
  }
}
CampoObligatorioRegla
avatarSíUno de 1,248 nombres de look
textSí (en lugar de audio_url)1–1,000 caracteres
voiceNoUno de 102 nombres; por defecto Warm Pro Narrator
promptNoHasta 1,200 caracteres de dirección
aspect_ratioNo16:9 (por defecto), 9:16, 1:1, 4:5, 5:4
resolutionNo1080p (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.

PoYo publica todos los nombres en la página Avatars and Voices y como catálogo JSON. El catálogo tiene cinco claves:

ClaveContenido
modelsheygen-avatar-6, heygen-avatar-6-turbo (los mismos nombres funcionan en ambos)
default_voiceWarm Pro Narrator
avatarsLos 1,248 nombres de look, en una lista plana
avatars_by_personLos mismos looks agrupados en 156 personas
voicesLos 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:

QuieresBusca nombres comoEjemplos
Presentador mirando a cámaraFrontAbigail Office Front, Bryan Suit Front
Ángulo de tres cuartosSideAbigail Office Side
Sentado, informalSofa, Sitting, LoungeAnnie Sofa Sitting Front
Un rol o un escenarioDoctor, Nurse, Yoga, Tech ExpertAnn 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 Hope y Hope (con un espacio final) son dos voces distintas. Archer , Cassidy , Adam Stone , Spuds Oxley y Andrew Rizz tambié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 😊 o Brenda - 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 Expert con Andrew y Abigail Office Front con Jessica 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 text en 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 prompt cuando 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ónaspect_ratio
Sitio web, YouTube, lección de LMS16:9 (por defecto)
Shorts, Reels, TikTok, stories9:16
Publicación cuadrada en el feed, tarjeta dentro de la app1:1
Publicación vertical en el feed4:5
Publicación horizontal en el feed5: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):

ModeloAvatar / vozGuionSalidaCoste a precios actualesTiempo real
heygen-avatar-6-turboAbigail Office Front / Jessica Anne Bogart27 palabras10.16 s110 créditos ($0.55)Unos 2.4 min
heygen-avatar-6Bryan Tech Expert / Andrew21 palabras6.88 s140 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.

Share: