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
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.

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:
- 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.
- 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.

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.

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 →-
Guía de uso
Guía de inicio con gpt-6.2-sol: límites de capacidad, integración vía API y consideraciones sobre el precio por token
Puntos clave de decisión e implementación de la integración para equipos de ingeniería
-
Guía de uso
Guía de inicio de gpt-6.2-astra: límites de capacidad del modelo de texto, puntos clave de integración y control de costes
-
Guía de uso
Guía de inicio de Tripo H3.1: cómo elegir entre tres modos de entrada, parámetros y precios
Guía práctica de decisiones de integración y control de costes de la generación 3D para desarrolladores