Blog

Guía de uso

Genera videos cortos con heygen-avatar-iv mediante la API de HiAPI: guía para desarrolladores

Entradas de avatar y audio, ritmo del guion, relación de aspecto y duración, y generación por lotes, con solicitudes ejecutables a HiAPI

Nov 18, 2026
Imagen de portada: un patrón de cestería plano y ancho formado por anchas cintas trenzadas en tonos avena y latón sobre un fondo de color café oscuro.
En esta página

Por qué elegir heygen-avatar-iv para videos cortos

Los videos cortos se han convertido en el canal de distribución predeterminado para lanzamientos de productos, anuncios de actualizaciones, explicaciones de documentación y piezas breves para redes sociales. Para la mayoría de los equipos de ingeniería, el cuello de botella no está en la edición, sino en producir de forma estable material de locución con una persona en cámara, sin reservar un estudio ni intercambiar material con un presentador humano.

Aquí es donde entra la generación de video con avatares digitales. Tú aportas la imagen visual y la fuente de audio/voz, y el modelo devuelve un clip renderizado en el que ese avatar digital lee el guion. heygen-avatar-iv es el endpoint del catálogo de HiAPI orientado a este flujo de trabajo: clips cortos con prioridad vertical, en los que el presentador habla directamente a cámara.

El modelo encaja en los siguientes escenarios:

  • Necesitas producir a escala. Diez versiones localizadas del mismo anuncio, o un clip diario por cada lanzamiento: es un bucle, no una grabación única.
  • El contenido está guiado por el guion. Si el mensaje está en el texto, un presentador digital es suficiente.
  • Buscas reproducibilidad. Una solicitud es un archivo que puedes comparar, versionar y volver a ejecutar, a diferencia de una sesión de grabación.
  • Ya llamas a la API. Una única llamada HTTP se integra en tu pipeline existente, sin introducir una nueva herramienta con su propia UI.

No es adecuado para actuaciones improvisadas con gestos amplios, ni para escenarios en los que la presencia física de una persona concreta sea el atractivo. Trata heygen-avatar-iv como un renderizador: con las mismas entradas deberías obtener el mismo tipo de salida, y eso es precisamente lo que lo hace programable.

El resto de esta guía va desde una única llamada de prueba hasta un bucle por lotes, con ejemplos ejecutables de curl y Python que puedes adaptar. Los detalles del modelo y sus parámetros están en la página del modelo heygen-avatar-iv.

El guion y la figura del avatar digital se fusionan en un punto de encuentro similar a un telar para dar un único marco de video corto vertical.

Composición de una solicitud a heygen-avatar-iv

Antes de escribir el código de generación, modela la solicitud como dos grupos de entrada independientes. Casi todos los errores tempranos provienen de confundir ambos.

Primer grupo: la imagen visual

Es quién aparece en cámara: la selección del avatar digital que determina el rostro del presentador, el encuadre y el aspecto general. Mantén este grupo estable durante una campaña. Si vas a producir cinco clips sobre el mismo producto, deben compartir el mismo bloque de imagen para que la serie parezca presentada por la misma persona.

Segundo grupo: audio y voz

Es qué se dice y cómo se dice. Según la solicitud, la fuente de audio puede ser una selección de timbre que lee el texto de tu guion, o una pista de audio proporcionada. Este grupo cambia en cada clip: nuevo guion, nuevo ritmo y, a veces, un nuevo timbre para la localización.

Cómo se asignan a la llamada

La solicitud a HiAPI envía ambos grupos en el mismo payload al endpoint de generación. Conceptualmente:

request
├── avatar / identity block   → se mantiene estable durante una serie
└── audio / voice block       → cambia en cada clip
        └── texto del guion o fuente de audio

Esta división da lugar a dos reglas prácticas:

  1. Parametriza el grupo de audio y congela el grupo de imagen. En el código, mantén la imagen como una constante a nivel de módulo y pasa el guion y el timbre como argumentos de la función. Así garantizas estructuralmente la coherencia visual de una serie.
  2. Al depurar, cambia un solo grupo a la vez. Si el clip no se ve bien, sustituye solo la imagen; si no se oye bien, sustituye solo el grupo de audio. Depurar con dos variables a la vez sobre llamadas de renderización de pago resulta caro.

Además, decide cuanto antes si tu grupo de audio se basa en texto o en una pista de audio, porque esta elección determina el ritmo de la siguiente sección: una pista de audio proporcionada fija la sincronización, mientras que una voz generada sigue tu guion.

Los nombres exactos de los campos, los valores aceptados y los valores predeterminados se enumeran en la página del modelo; léelos y fíjalos en un objeto de configuración en lugar de dispersar literales por el código.

Dos grupos de entrada —la imagen visual y la fuente de audio/voz— se entrelazan en una única llamada de generación.

Realiza tu primera llamada con curl

Empieza con un clip corto. El objetivo de esta llamada no es la calidad de la salida, sino validar de extremo a extremo las credenciales, la forma del payload y la ruta de descarga antes de automatizar nada.

Define la clave como variable de entorno para que nunca entre en texto plano en el historial del shell:

export HIAPI_API_KEY="your_key_here"

Después envía una solicitud mínima. Sustituye por tu propia selección de avatar y una línea breve de guion:

curl -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "avatar": "<avatar_identifier>",
      "script": "Esta es una prueba de treinta segundos del pipeline de avatares digitales. Si puedes leer esta frase en pantalla, la forma de la solicitud es correcta.",
      "voice": "<voice_identifier>",
      "aspect_ratio": "9:16",
      "duration": 30
    }
  }'

Comprueba en orden:

  • Autenticación. Un error de credenciales aquí significa detenerse: nada de lo que venga después importa.
  • Validación del payload. Un error de esquema indicará el campo problemático. Corrige un campo a la vez.
  • Aceptación de la tarea. Una llamada correcta devuelve una referencia de job o de task, no necesariamente el archivo final. La generación es asíncrona; registra ese identificador.
  • Obtención del resultado. Según el contrato de respuesta de la página del modelo, consulta el estado con la referencia devuelta u obtén la URL del resultado.
  • Reproducción. Descarga el clip y visualízalo. Confirma que el encuadre, la orientación y el contenido leído coinciden con el guion.

Guarda este comando curl en un archivo de borrador con tus identificadores reales. Se convertirá en tu experimento de control: cuando la versión de Python falle, vuelve a ejecutar el curl para demostrar si el problema está en tu código o en la entrada.

Cada cinta trenzada marca un paso —construir, enviar, recibir, descargar— con un bucle de reintento de la llamada.

Pasa a Python para una generación reproducible

Una vez que la llamada curl funciona, envuélvela en una función. El objetivo no es abstraer por abstraer, sino hacer que cada parámetro sea explícito, de modo que el clip quede descrito por completo en el punto de llamada.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/generate"
API_KEY = os.environ["HIAPI_API_KEY"]

# Se mantiene estable durante una serie
AVATAR = "<avatar_identifier>"


def generate_clip(script: str, voice: str, aspect_ratio: str = "9:16",
                  duration: int = 30) -> dict:
    payload = {
        "model": "heygen-avatar-iv",
        "input": {
            "avatar": AVATAR,
            "script": script,
            "voice": voice,
            "aspect_ratio": aspect_ratio,
            "duration": duration,
        },
    }
    resp = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    job = generate_clip(
        script="Esta es una prueba de treinta segundos del pipeline de avatares digitales.",
        voice="<voice_identifier>",
    )
    print(job)

Decisiones de diseño que te beneficiarán más adelante:

  • Los valores predeterminados reflejan tus clips más habituales. Si la mayoría de las salidas son clips cortos verticales, usa esos valores por defecto y sobrescríbelos pocas veces.
  • La imagen va a nivel de módulo. La selección del avatar existe en un solo lugar, y cambiar de marca requiere una sola línea.
  • Devuelve la respuesta completa. No extraigas la URL de inmediato y descartes el objeto job; necesitarás ese identificador para registros y reintentos.
  • Lanza excepciones ante errores HTTP. Un fallo silencioso en un bucle por lotes es peor que una caída.
  • Gestiona explícitamente el paso asíncrono. Añade un pequeño helper poll(job_id) en lugar de hacer sleep dentro de la función de generación.

Ajusta la lógica de tratamiento de la respuesta al contrato documentado en la página del modelo: los nombres de los campos de estado del job y de obtención de resultados son lo que más probablemente difiera de tus suposiciones.

Redacta el guion de locución y controla el ritmo

Los videos con avatares digitales priorizan el audio. Un guion que se lee bien en papel a menudo resulta demasiado largo en voz alta, y recortar después de la generación significa pagar renderización por un texto que se va a eliminar.

Primero escribe según la longitud y luego recorta

Estima la duración antes de llamar a la API. Una velocidad cómoda es de unas 130 a 160 palabras por minuto; para contenido técnico que la audiencia debe seguir, usa el extremo inferior. Por tanto, un clip de 30 segundos necesita aproximadamente 65 a 80 palabras, y uno de 60 segundos, unas 130 a 160 palabras. Redacta con ese presupuesto, léelo en voz alta con un cronómetro y luego recorta. Si tienes que recortar, elimina frases enteras en lugar de palabras: el recorte a nivel de frase mantiene intacto el ritmo.

Escribe para el oído

  • Frases cortas. Una idea por frase. Las oraciones subordinadas son donde decae la comprensión.
  • Nada de referencias que dependan solo de lo visual. «Como se muestra a continuación» no funciona sin una diapositiva.
  • Pon lo importante al principio. La audiencia de videos cortos decide en los primeros segundos; coloca la afirmación en la primera frase.
  • Escribe tal como debe pronunciarse lo que el TTS leería mal. Siglas, cadenas de versión y nombres de producto con mayúsculas anómalas deben escribirse según su pronunciación prevista.

Controla el ritmo según la línea temporal

Distribuye el guion en bloques temporales según la duración objetivo:

0–5 s    gancho: la afirmación o el problema
5–20 s   cuerpo: el mecanismo, en dos o tres frases
20–28 s  detalle: un dato o ejemplo que merece la pena retener
28–30 s  cierre: una única llamada a la acción

Esta estructura por bloques también sirve como artefacto de revisión: un revisor puede rechazar un bloque sin que tengas que volver a renderizar nada. Guarda el guion de cada clip en un archivo independiente bajo control de versiones junto al código que lo renderiza, y el bucle por lotes de la siguiente sección se vuelve totalmente reproducible.

Configura la relación de aspecto, la duración y la salida

Decide la orientación y la duración según la plataforma de destino antes de la primera renderización. Volver a renderizar un clip terminado en una segunda orientación es puro desperdicio, y reeditar un clip demasiado largo implica regenerar también el audio.

Relación de aspecto

  • 9:16 vertical: el valor predeterminado de los feeds de video corto: shorts, reels, stories y ubicaciones mobile-first. Diseña el encuadre pensando primero en este formato; siempre que sea posible, recorta las demás proporciones a partir de una versión maestra vertical.
  • 16:9 horizontal: reproductores embebidos, landing pages, videos de documentación y presentaciones.
  • 1:1 cuadrado: ubicaciones de feed que prefieren el formato cuadrado. Adecuado como versión derivada secundaria.

Si tu campaña necesita dos orientaciones, trátalas como dos tareas distintas con guiones diferentes, en lugar de renderizar el mismo guion dos veces: una línea que funciona en un vertical de 30 segundos a menudo deja silencios incómodos en un corte cuadrado más corto.

Duración

Establece la duración según el presupuesto de guion de la sección anterior, no al revés. Indica una duración que coincida con la longitud real de la locución; un clip rellenado o cortado a mitad de frase parece defectuoso. Mantén los objetivos de cada plataforma en la configuración para facilitar los ajustes:

TARGETS = {
    "vertical": {"aspect_ratio": "9:16", "duration": 30},
    "horizontal": {"aspect_ratio": "16:9", "duration": 45},
}

Salida

Descarga y almacena tú mismo el clip terminado, en lugar de depender de una URL de resultado temporal. Una convención sencilla —{clip_id}-{orientation}-{version}.mp4— mantiene trazables las versiones derivadas y deja evidentes los archivos obsoletos. Registra el identificador del job junto al archivo para que cualquier clip pueda rastrearse hasta su solicitud exacta.

La facturación se aplica a las generaciones que solicites —por duración y número de clips—, así que depurar el guion antes de renderizar es la optimización más barata a tu disposición. Consulta las tarifas actuales en el panel de precios.

Genera varios clips por lotes

Con una función que funciona, el procesamiento por lotes es un bucle sobre una lista de tareas. La clave es que cada tarea describa por completo un clip.

JOBS = [
    {"id": "launch-vertical", "script_file": "scripts/launch.txt",
     "voice": "<voice_a>", "aspect_ratio": "9:16", "duration": 30},
    {"id": "launch-square", "script_file": "scripts/launch_sq.txt",
     "voice": "<voice_a>", "aspect_ratio": "1:1", "duration": 20},
    {"id": "changelog-vertical", "script_file": "scripts/changelog.txt",
     "voice": "<voice_b>", "aspect_ratio": "9:16", "duration": 30},
]

results = []
for job in JOBS:
    with open(job["script_file"]) as f:
        script = f.read().strip()
    print(f"submitting {job['id']} ({len(script.split())} words)")
    resp = generate_clip(
        script=script,
        voice=job["voice"],
        aspect_ratio=job["aspect_ratio"],
        duration=job["duration"],
    )
    results.append({"id": job["id"], "job": resp})

Patrones que merece la pena adoptar:

  • Guiones como archivos, no como literales de cadena. Se pueden revisar, comparar y reutilizar entre orientaciones.
  • Registro del recuento de palabras. Imprime el número de palabras de cada tarea para detectar antes de gastar en renderización los guiones que superarán la duración.
  • IDs de job estables. Úsalos en los nombres de archivo de salida y en los registros para poder identificar los clips fallidos entre veinte ejecuciones.
  • Fallo suave y luego informe. Envuelve cada envío en try/except, recopila los fallos y continúa: un guion defectuoso no debe abortar todo el lote.
  • Respeta los límites de tasa y la concurrencia. Empieza en serie; añade un pool de hilos acotado solo cuando la ejecución en serie sea estable.
  • Persiste la lista de resultados. Escribe los IDs de job en un archivo JSON para que un lote parcialmente completado pueda reanudarse en lugar de reiniciarse.

Puntos de fallo habituales y comprobaciones

Estos son los problemas que aparecen primero. Cada uno tiene una comprobación de aislamiento barata.

Error de formato en la entrada

Los errores de esquema son el fallo inicial más común. Comprobación: ejecuta el comando curl original con los mismos identificadores. Si curl funciona y Python falla, el bug está en tu serialización, normalmente por un desajuste de tipos, como pasar una cadena en un duration entero, o por un salto de línea sobrante al final del archivo de guion.

Desajuste entre audio y guion

Si la voz dice algo distinto de lo previsto en pantalla, o el clip no tiene sonido, el grupo de audio está mal. Comprobación: confirma si la solicitud se basa en texto o en una pista de audio, y confirma que pasaste el campo correspondiente. Proporcionar a la vez un campo de pista de audio y uno de guion es un conflicto típico que produce silencio: decide cuál tiene prioridad y elimina el otro.

Orientación incorrecta o barras negras

El clip vuelve con barras negras o con un encuadre inesperado. Comprobación: verifica que aspect_ratio llega realmente al payload; un valor predeterminado en la función puede sobrescribir silenciosamente el valor que creías haber pasado. Registra el payload ensamblado antes de enviarlo.

Desajuste de duración

El clip se corta a mitad de frase o se alarga. Comprobación: compara el recuento de palabras del guion con el presupuesto de duración. Corrige el guion en lugar de la duración, salvo que el objetivo en sí sea erróneo.

Deriva de la imagen en una serie

Los clips de una misma campaña parecen presentados por personas distintas. Comprobación: confirma que el identificador del avatar proviene de una única constante y no de una configuración por tarea.

Salida truncada o ausente

El job tiene éxito pero el archivo está incompleto. Comprobación: antes de descargar, confirma que el job ha alcanzado un estado final de éxito y que sigues el contrato de obtención de la página del modelo en lugar de adivinar la URL.

Regla general: un clip de prueba, una solicitud curl y una variable a la vez. Valida de extremo a extremo con una breve renderización vertical en el modelo heygen-avatar-iv antes de dejar que el bucle escale.

Artículos relacionados

Ver todos los artículos →

Empieza a crear con artefactos de IA persistentes

Consigue tu API key y llama a modelos de imagen, vídeo y audio a través de una única API basada en tasks.

Leer la documentación de la API