Convierte guiones en videos cortos de presentación con heygen-avatar-v y la API de hiapi

El contenido de presentación en video corto —actualizaciones de los fundadores, demostraciones de producto, anuncios estilo UGC— normalmente implica reservar a una persona real, preparar un micrófono y hacer otra ronda de edición. heygen-avatar-v en hiapi lo reduce todo a una sola llamada a la API: envías un guion o un archivo de audio y recibes un video de avatar con sincronización labial, movimiento natural de reposo y una pista de subtítulos, listo para el feed de video corto. Este artículo recorre el flujo de trabajo real de /v1/tasks, un clip generado de verdad, las restricciones que conviene conocer antes de construir una canalización alrededor de él, y los precios obtenidos en vivo de /api/pricing de hiapi. Si lo que buscas son trucos de estilo a nivel de prompt para el avatar en sí, heygen-avatar-v prompt recipes ya lo cubre — este artículo trata de cómo integrar el modelo en una canalización de video corto reutilizable.

Qué produce realmente heygen-avatar-v

heygen-avatar-v es un modelo de video de humano digital, no un generador de texto a video en el sentido de Sora/Kling — usa un guion de texto o un archivo de audio subido para impulsar un avatar predefinido de HeyGen y devuelve un video donde la boca del avatar está sincronizada con el habla y con un movimiento continuo sutil (parpadeos, ligeros movimientos de cabeza, balanceo de hombros), de modo que no parece un retrato estático. Ese comportamiento de «moverse incluso en reposo» es justo la línea divisoria entre un clip de video corto utilizable y una foto que habla que se nota falsa.

El modelo se impulsa con dos tipos de entrada, mutuamente excluyentes — envías uno u otro:

• prompt — un guion de texto; lo lee el TTS de hiapi y se usa para impulsar la sincronización labial
• audio_url — una URL pública que apunta a una pista de voz pregrabada (tu propia locución, una voz clonada, lo que sea) que impulsa la sincronización labial

No hay campo duration. La duración del clip depende por completo de cuánto dure el guion o el audio — una línea de 40 palabras produce un clip más corto que una de 200. Esto es importante para planificar costos, como se explica más abajo.

Hay campos opcionales para afinar el estilo: avatar (elegido de la biblioteca predefinida de HeyGen), voice (solo se usa con prompt; se ignora cuando se usa con audio_url), aspect_ratio (9:16 para Reels/TikTok/Shorts, 16:9, 1:1), resolution, background (color sólido o escena — pero mira el escollo de abajo), caption (genera una pista de subtítulos) y output_format (mp4 o webm, este último con fondo transparente para componerlo sobre tus propias escenas).

Clip real: guion de entrada, video de avatar con subtítulos de salida

Aquí hay una salida real de heygen-avatar-v — el avatar pronuncia una línea de guion, con movimiento de reposo visible entre frases y una pista de subtítulos sincronizada:

Fíjate en lo que no ocurre: el avatar no se queda rígido entre frases, y los subtítulos siguen al habla en lugar de añadirse después. Esa combinación —movimiento continuo más subtítulos temporizados— es la razón completa para elegir este modelo en vez de poner una locución en un editor sobre una imagen estática del avatar.

Escollos: dos problemas que morderán tu primera canalización

caption devuelve un archivo adjunto de subtítulos, no subtítulos quemados. Poner caption: true devuelve un archivo .srt sincronizado junto con la salida de video — no quema el texto en los fotogramas del video. Si quieres que el texto aparezca en pantalla (el aspecto que tienen la mayoría de las plataformas de video corto), necesitas hacer un quemado aparte con ese archivo .srt (ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4, o usar la función nativa de importación de subtítulos de tu plataforma). Trata los «subtítulos» de la API como datos, no como imagen ya renderizada.

background solo funciona con avatares de estilo ilustración, no con los de estilo realista. La biblioteca de avatares de HeyGen mezcla avatares fotorrealistas con avatares de estilo ilustración/animación. El parámetro background sustituye con éxito la escena detrás de los avatares de estilo ilustración, pero los avatares realistas conservan su fondo de grabación original sin importar lo que envíes — el modelo no lo recorta. Si tu canalización da por hecho que todos los avatares aceptan una sustitución de fondo, prueba primero el ID de avatar concreto que vas a usar antes de suponer que se compondrá como esperas. Para los avatares realistas que quieras poner sobre tu propio fondo, la vía fiable es output_format: webm (transparente).

Costos: se cobra por segundos de salida, no por número de llamadas

Según el /api/pricing en vivo de hiapi, heygen-avatar-v se cobra a $0.15 por cada segundo de salida — tarifa plana sin importar la resolución ni la relación de aspecto. Como no hay entrada de duración, tu costo real depende de cuánto dure el guion o el audio:

Longitud del guion (aprox.)	Duración de salida	Costo
Frase de gancho corta	Aprox. 5 segundos	$0.75
Un fragmento de video corto	Aprox. 10 segundos	$1.50
Discurso de venta de varias frases	Aprox. 20 segundos	$3.00
Un anuncio completo de 30 segundos	Aprox. 30 segundos	$4.50

Como el costo escala con la duración de la voz y no con un parámetro que fijes de antemano, lo práctico es cronometrar el guion antes de enviar la tarea (léelo en voz alta o pásalo por un estimador de duración de TTS) en vez de descubrir la factura después de que el clip se haya renderizado.

La canalización: enviar, consultar, descargar antes de que caduque

heygen-avatar-v funciona sobre el endpoint asíncrono /v1/tasks de hiapi — igual que todos los modelos basados en tareas de la plataforma, con la forma «crear primero, consultar después». Un detalle específico de este flujo de trabajo: entre handling y success, la tarea pasa por una fase archiving, en la que la plataforma está terminando el video y el archivo adjunto de subtítulos, así que no trates archiving como estado terminal en tu bucle de consulta.

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

Dos notas operativas que no puedes saltarte al usar esto a escala:

• Descarga de inmediato. Como toda salida de tarea de hiapi, la URL devuelta lleva expireAt y no sirve como enlace permanente — en cuanto la tarea tenga éxito, trae los bytes (video y .srt) a tu propio almacenamiento.
• No envíes una carga útil mínima «para comprobar el esquema». Como estrictamente solo prompt o audio_url son obligatorios y los demás campos toman valores por defecto en silencio, una carga útil con solo {"prompt": "test"} no devolverá un 400 — lanzará un renderizado real y facturable. Valida los nombres de campo contra la documentación o con un valor deliberadamente inválido para obtener una respuesta 4xx, en lugar de omitir campos contra el endpoint real.

FAQ

¿Puedo usar mi propia voz en lugar del TTS de hiapi? Sí — pasa audio_url en lugar de prompt, con la URL pública de tu grabación, y el avatar sincronizará los labios con esa pista de audio en lugar de sintetizar voz a partir del texto.

¿La opción caption quema los subtítulos en el video? No. caption: true devuelve un archivo .srt aparte, sincronizado con el audio del video de salida. Si quieres el texto de los subtítulos en pantalla, quémalo tú mismo como paso de posprocesamiento.

¿Puedo controlar la duración del clip? No directamente — no hay parámetro duration. La duración de salida la determina la longitud del guion (cuando usas prompt) o la del archivo de audio (cuando usas audio_url).

¿Por qué no aparece el fondo que especifiqué? background solo funciona con los avatares de estilo ilustración/animación de la biblioteca de HeyGen. Los avatares realistas y fotorrealistas conservan su fondo de grabación original; en ese caso, usa output_format: webm para obtener una salida transparente y compón tú mismo.

¿Qué resoluciones y relaciones de aspecto admite? Hasta 4K, con opciones de relación de aspecto 9:16, 16:9 y 1:1 — cubre desde el feed vertical de video corto hasta la publicidad panorámica y cuadrada.

Puntos clave

Montar una canalización de avatares para video corto en hiapi se reduce a unos cuantos hechos concretos, no a adivinar: el costo es de $0.15 por segundo de salida (así que cronometra el guion antes de enviar, no después), la salida de subtítulos es un archivo adjunto .srt que debes quemar tú mismo, la sustitución de fondo solo funciona con avatares de estilo ilustración, y tu bucle de consulta debe tratar archiving como no terminal, igual que handling. Antes de fijar un presupuesto en código, consulta las cifras actuales en la página de precios de hiapi, y para la referencia completa de campos, mira la página del modelo. Si estás listo para ponerte manos a la obra, obtén una API key desde el panel y empieza con un guion corto — una salida de 5 segundos basta para confirmar que tu avatar, la relación de aspecto y el manejo de subtítulos funcionan bien, y luego amplía a lotes completos.