¿Cómo se usa la API de HeyGen Avatar IV? Haz que una foto hable en 5 minutos

TL;DR

• Qué es: un avatar digital a partir de foto creado por HeyGen. Una foto de retrato más un guion (o un audio) generan un MP4 en el que la persona de la foto habla. Ya está disponible en HiAPI; abre la página del modelo, sube una foto y genera.
• Cuánto cuesta: se cobra por segundos de video, $0.15 por segundo, mismo precio para 720p y 1080p; un video de 10 segundos cuesta $1.50.
• Cómo llamar a la API: POST https://api.hiapi.ai/v1/tasks, en model escribe heygen-avatar-iv, envía el enlace de la foto y el guion, obtén el taskId y consulta; en 5 minutos tienes tu primer video funcionando.

Primero mira un video terminado. Este clip horizontal de 9 segundos usa una foto de medio cuerpo con suéter y un guion en inglés:

1080p / 16:9, 9 segundos, voz Cute Chloe - Friendly. El suéter, el peinado y la habitación de la foto se conservan; el movimiento de labios, el parpadeo y un leve asentimiento siguen al audio.

Texto original del guion:

Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.

Generar con este guion → El guion ya está rellenado; sube tu propia foto y genera.

¿Para quién es HeyGen Avatar IV?

Si tienes una foto y quieres que "esa persona" aparezca hablando, usa esto. Usos habituales:

• Explicaciones de producto y videos de recomendación: con la misma foto cambias el guion y produces en lote videos cortos con distintos argumentos de venta.
• Cursos y formación: el profesor graba una foto una vez y en cada clase solo escribe el guion.
• Avisos corporativos y videos de atención al cliente: la imagen de asesores, médicos o gerentes se mantiene fija y el contenido se actualiza cuando quieras.
• Ilustraciones y personajes 3D: siempre que haya una cara clara, los personajes de dibujo también pueden hablar.

Si no quieres usar tu propia imagen y prefieres elegir entre avatares predefinidos, o necesitas fondo transparente, subtítulos o 4K, elige HeyGen Avatar V, al mismo precio.

Pruébalo primero en la página del modelo

Antes de escribir código, genera uno en la web para ver cómo queda tu foto:

1. Haz clic en "Generar con este guion" de arriba; el guion se rellena automáticamente.
2. Sube una foto de una sola persona, de frente y con iluminación uniforme.
3. Elige 1080p y 16:9; la voz puedes no elegirla, por defecto es Warm Pro Narrator.
4. Haz clic en generar, previsualiza en línea cuando termine y descarga si te convence.

Un video de 10 segundos cuesta $1.50; con $10 puedes generar unos 66 segundos de video, suficiente para comparar varias fotos y varias voces.

Tres cosas que preparar antes de llamar a la API

1. API Key: créala en la consola, con formato sk-..., y colócala en la cabecera Authorization: Bearer.
2. Enlace HTTPS público de la foto: lo más estable es una foto de una sola persona, de frente, sin rasgos faciales ocultos, con iluminación uniforme y boca cerrada de forma natural. La interfaz lee la foto desde el enlace, así que sube primero la imagen a tu propio almacenamiento o CDN.
3. Guion o audio, elige uno: si envías un guion, lo lee la voz seleccionada; si envías un audio (audio_url), el movimiento de labios sigue tu grabación.

Solicitud mínima: versión cURL

El enlace de foto de abajo se puede usar directamente; solo cambia tu Key y ejecútalo:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
      "prompt": "Hi, I'\''m Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
      "voice": "Cute Chloe - Friendly",
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }
  }'

El ID de tarea devuelto está en data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

No hace falta enviar la duración: con guion la determina la longitud del texto y la velocidad de habla; con audio dura lo mismo que el audio.

Consultar el resultado

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Cuando data.status pase a success, busca en data.output el elemento cuyo type sea video; su url es el MP4:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-...",
    "status": "success",
    "model": "heygen-avatar-iv",
    "output": [
      {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4"}
    ]
  },
  "message": "success"
}

Ejemplo completo en Python: crear, consultar y descargar

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "heygen-avatar-iv",
    "input": {
        "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
        "prompt": "Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
        "voice": "Cute Chloe - Friendly",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(8)

if data["status"] == "success":
    video_url = next(o["url"] for o in data["output"] if o["type"] == "video")
    with open("avatar-iv.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    print("saved avatar-iv.mp4")
else:
    print(data.get("error"))

Resumen de parámetros

Parámetro	Obligatorio	Valor por defecto	Descripción
image_url	Sí	—	Enlace HTTPS público de la foto del retrato; necesita una cara clara
prompt	Uno de los dos	—	Guion, máximo 5000 caracteres, en chino o en inglés
voice	No	Warm Pro Narrator	102 voces predefinidas; solo se aplica al usar guion
audio_url	Uno de los dos	—	Audio que controla el movimiento de labios, máximo 600 segundos
resolution	No	720p	720p o 1080p, mismo precio
aspect_ratio	No	16:9	16:9, 9:16, 4:5, 5:4, 1:1, auto (mantiene la proporción de la foto)
background	No	Blanco	{"type": "color" o "image", "value": ...}, rellena el espacio libre del encuadre
callback	No	—	{"url": "...", "when": "final"}, envía el objeto de tarea al llegar al estado final

La lista completa de voces está en la documentación en chino.

Las dos formas de control y cómo usar el fondo

Control por guion: envía prompt y voice; ideal para cambiar contenido en lote. Este video vertical hablado a cámara tiene una foto que ya es 9:16, así que el encuadre de salida queda lleno:

1080p / 9:16, 8 segundos, voz Andrew.

I've been using these new earbuds for a week. The noise canceling is super quiet, and the battery lasts all day. Follow me for more.

Generar con este guion → El guion ya está rellenado; sube tu foto vertical y elige 9:16 para generar.

Control por audio: si ya tienes la narración grabada o quieres usar tu propia voz, cambia prompt y voice por audio_url; el movimiento de labios y las pausas siguen la grabación.

Fondo: cuando la proporción del encuadre de salida no coincide con la de la foto, quedan espacios libres; rellénalos con background. Para color sólido envía {"type": "color", "value": "#F5EFE6"}; para imagen, {"type": "image", "value": "https://..."}. Este video mete una foto horizontal de una profesora en vertical y rellena arriba y abajo con una imagen de pizarra:

1080p / 9:16, 11 segundos, voz Professor Dean, background con una imagen de pizarra.

Hello everyone. Today we'll explain the Pythagorean theorem in five minutes. In a right triangle, the squares of the two legs add up to the square of the hypotenuse.

Generar con este guion → El guion ya está rellenado; sube tu foto y genera.

3 cosas a tener en cuenta antes de publicar

1. Usa callback en el servidor. Añade a la solicitud "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; al terminar la tarea se envía automáticamente y te ahorras el polling.
2. No repitas el POST después de obtener el taskId. Cada POST /v1/tasks crea una tarea nueva y se cobra por separado. Si hay un timeout de red, comprueba primero si guardaste el taskId; si lo tienes, sigue consultando o espera el callback.
3. Descarga en cuanto tengas éxito. Los enlaces de salida caducan; en cuanto recibas el resultado, guarda el MP4 en tu propio almacenamiento.

¿Cómo se factura?

$0.15 por segundo, según los segundos reales del video generado; la resolución no afecta al precio, así que usa 1080p directamente. Al crear la tarea se hace una retención según la duración estimada y, al terminar, se ajusta según los segundos reales (se devuelve o se cobra la diferencia); las tareas fallidas se reembolsan por completo.

Duración del video	Coste
5 segundos	$0.75
10 segundos	$1.50
30 segundos	$4.50
60 segundos	$9.00

El coste solo depende de los segundos; para ahorrar, acorta el guion. 300 videos hablados de 10 segundos al mes cuestan unos $450; 20 cursos de 60 segundos, unos $180. Consulta la lista completa en la página de precios.

El video de 9 segundos de Lin del principio costó $1.35. Generar con el mismo guion → El guion ya está rellenado; sube tu foto y calcula cuántos segundos tendrá tu video.

Preguntas frecuentes

¿Se puede usar un guion en chino? Sí. prompt admite chino e inglés, con un máximo de 5000 caracteres.

¿Puedo usar mi propia voz? Sí. Envía la grabación a audio_url, máximo 600 segundos; el movimiento de labios sigue tu grabación.

¿Qué tipo de foto da mejor resultado? Una foto de una sola persona, de frente, sin rasgos faciales ocultos, con iluminación uniforme y boca cerrada de forma natural. También sirven ilustraciones y personajes 3D, siempre que tengan una cara clara. Si es de perfil, lleva mascarilla, hay varias personas o la cara es muy pequeña, prueba con otra; las tareas que fallan en el reconocimiento se reembolsan por completo.

La foto es horizontal, ¿cómo saco un video vertical? Pon aspect_ratio en 9:16 y rellena los espacios de arriba y abajo con background, como en el ejemplo de la pizarra.

¿Cuánto tarda un video? La generación es asíncrona; cuanto más largo sea el guion y más alta la resolución, más tardará. Usa callback en el servidor para recibir el aviso automáticamente al terminar.

Enlaces relacionados con HeyGen Avatar IV

• Página del modelo HeyGen Avatar IV: sube una foto y genera en línea
• Documentación en chino de HeyGen Avatar IV: todos los parámetros y las 102 voces
• Página del modelo HeyGen Avatar V: 497 avatares predefinidos, compatible con fondo transparente y subtítulos
• Página de precios de HiAPI: precios por segundo y por imagen de todos los modelos

Pruébalo ahora: busca una foto tuya de frente, genera con este guion de Lin →, el guion ya está rellenado; sube la foto, elige 1080p y 16:9, y un video de unos 9 segundos cuesta $1.35.