![]()
Esta guía de la HeyGen Avatar 6 API te lleva desde una clave de API hasta un vídeo parlante terminado en PoYo. Envías una solicitud JSON con el ID de modelo heygen-avatar-6 (o heygen-avatar-6-turbo), guardas el ID de tarea devuelto y consultas el estado hasta que el MP4 esté listo. Todos los cuerpos de solicitud de abajo siguen la estructura de la documentación de PoYo; la página del modelo HeyGen Avatar 6 tiene un Playground si quieres ver antes las entradas.
Antes de empezar
- Crea una clave en
poyo.ai/dashboard/api-keyy expórtala comoPOYO_API_KEY. Guárdala en tu servidor. - Aloja cada archivo de entrada en una URL HTTP o HTTPS pública y descargable directamente. PoYo descarga los medios por su cuenta; no acepta subidas de archivos en la solicitud.
- Elige un nivel. Ambos IDs aceptan los mismos campos. Turbo cuesta 10 créditos ($0.05) por segundo en 1080p; Avatar 6 cuesta 20 créditos ($0.10). Consulta Avatar 6 frente a Turbo.
Tu primera solicitud a la HeyGen Avatar 6 API con cURL
La primera solicitud más rápida no necesita ningún archivo multimedia: un avatar público de HeyGen lee tu texto.
curl https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'
Una respuesta correcta tiene "code": 200 y data.task_id, con status en not_started. Es un trabajo en cola, no un vídeo. Consulta su estado:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Los estados son not_started, running, finished y failed. Con finished, el MP4 está en data.files[] con file_type video, y data.credits_amount muestra lo que se ha cobrado. Con failed, lee data.error_message.
Un bucle de polling acotado en Python
En nuestras pruebas del día del lanzamiento, el 19 de noviembre de 2026, los clips de texto cortos tardaron entre 2 y 2.4 minutos desde el envío hasta el resultado. Este bucle consulta cada 5 segundos (la documentación de estado recomienda 2–5 s), se detiene a los 15 minutos y nunca reenvía la solicitud al agotarse el tiempo, porque un segundo envío es una segunda tarea facturable.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
response.raise_for_status()
body = response.json()
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
return body["data"]
def generate(payload, timeout_s=900):
task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
task_id = task["task_id"]
print("task", task_id, flush=True)
deadline = time.monotonic() + timeout_s
while time.monotonic() < deadline:
time.sleep(5)
task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
if task["status"] == "failed":
raise RuntimeError(task.get("error_message") or "generation failed")
if task["status"] == "finished":
videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
return videos[0], task.get("credits_amount")
raise TimeoutError("still running; poll this task again later: " + task_id)
url, credits = generate({
"model": "heygen-avatar-6",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p",
},
})
print(url, credits)
En producción, añade un callback_url en el nivel superior en lugar de hacer polling. PoYo envía el mismo objeto de tarea (sin el envoltorio code / data) cuando la tarea está finished o failed, firmado con HMAC-SHA256 en X-Webhook-Signature; la documentación de webhooks explica la regla de la firma.
Los tres modos de entrada de la HeyGen Avatar 6 API
No hay un selector de modo. avatar selecciona el modo de avatar público; si no, video_url selecciona el modo de vídeo de referencia; si no, la solicitud se ejecuta en modo de foto. Usa las entradas de un solo modo por solicitud.
Modo de avatar público con texto
Es el que se muestra arriba. avatar es uno de los 1,248 looks públicos, text tiene hasta 1,000 caracteres y voice es una de 102 voces (por defecto Warm Pro Narrator). La guía de texto a avatar explica cómo elegir looks y voces del catálogo.
Modo de avatar público con tu audio
Sustituye text y voice por audio_url. aspect_ratio sigue aplicándose:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Modo de foto
Una foto de una persona real más la voz. El vídeo conserva la relación de aspecto de la foto, así que recorta la foto al encuadre que quieras antes de enviarla. callback_url va junto a model, no dentro de input:
{
"model": "heygen-avatar-6",
"callback_url": "https://your-domain.com/callback",
"input": {
"image_urls": ["https://example.com/presenter.png"],
"audio_url": "https://example.com/speech.mp3",
"prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
"resolution": "1080p"
}
}
Modo de vídeo de referencia
Para personajes animados o ilustrados. video_url es un clip del personaje; image_urls añade opcionalmente una imagen fija del mismo personaje. La salida conserva la relación de aspecto del clip:
{
"model": "heygen-avatar-6-turbo",
"input": {
"video_url": "https://example.com/cartoon-character.mp4",
"image_urls": ["https://example.com/cartoon-character.png"],
"audio_url": "https://example.com/speech.mp3",
"resolution": "2K"
}
}
Reglas de validación de campos de la HeyGen Avatar 6 API
Compruébalas en tu propio código antes de enviar; son los límites documentados.
| Campo | Modo | Regla |
|---|---|---|
model | Todos | heygen-avatar-6 o heygen-avatar-6-turbo |
image_urls | Foto (obligatorio), vídeo de referencia (opcional) | Array de exactamente una URL |
video_url | Vídeo de referencia | Al menos 2 s, hasta 50 MB |
avatar | Avatar público | Uno de los 1,248 nombres de la lista |
audio_url | Foto, vídeo de referencia; o avatar público en lugar de text | 2–60 s, hasta 15 MB |
text | Avatar público | 1–1,000 caracteres |
voice | Avatar público con text | Uno de 102 nombres |
prompt | Todos | Hasta 1,200 caracteres |
aspect_ratio | Avatar público | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Todos | 1080p (por defecto) o 2K |
Los nombres de avatares y voces coinciden sin importar mayúsculas/minúsculas ni espacios extra, con una excepción documentada: Hope y Hope (con espacio final) son dos voces distintas. El esquema de entrada no admite campos adicionales, así que no envíes opciones nativas de HeyGen como motion_expressiveness o motion_prompt de la API de la propia HeyGen; en PoYo, la dirección del movimiento va en prompt.
Errores que conviene manejar
Lee siempre code en el cuerpo de la respuesta. Algunos errores de validación llegan como HTTP 200 con "code": 400, así que comprobar solo el estado HTTP no basta.
code del cuerpo | error.type | Qué hacer |
|---|---|---|
| 400 | validation_error y otros | Corrige la entrada: audio fuera de 2–60 s, nombre de avatar desconocido, un campo de otro modo. No reintentes sin cambios |
| 401 | authentication_error | Revisa la cabecera Authorization: Bearer |
| 402 | insufficient_credits_error | Recarga saldo o espera a que se liquiden las tareas de texto en curso (ver abajo) |
| 429 | rate_limit_error | Espera y reintenta |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Reintenta con backoff exponencial |
La duración del audio, la duración del vídeo de referencia y el nombre del avatar se comprueban en el envío, así que estos errores aparecen como un 400 inmediato y no como una tarea fallida minutos después.
El caso 402 tiene un matiz propio de HeyGen. En nuestra prueba del día del lanzamiento, después de enviar dos tareas de texto, una tercera solicitud (Turbo, 2K, 22 palabras) devolvió HTTP 200 con code 402 en el cuerpo y tipo insufficient_credits_error: «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». Las tareas de texto retienen créditos mientras se ejecutan, así que una ráfaga de envíos de texto puede recibir un 402 aunque los cargos finales cupieran en el saldo. Pon en cola los trabajos de texto o muestra el mensaje de error al usuario, ya que indica ambas cifras.
Cómo se calcula la primera factura de la HeyGen Avatar 6 API
PoYo factura por segundo de salida, redondeado hacia arriba a segundos enteros (1 crédito = $0.005):
| Modelo | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 créditos ($0.05) / s | 18 créditos ($0.09) / s |
heygen-avatar-6 | 20 créditos ($0.10) / s | 29 créditos ($0.145) / s |
- Con
audio_url(todos los modos): el cargo corresponde a la duración del audio, redondeada hacia arriba, y se cobra en el envío. Un clip de 12.3 segundos en Avatar 6 a 1080p son 13 × 20 = 260 créditos ($1.30). - Con
text: los créditos se reservan en el envío y se liquidan según la duración del vídeo terminado cuando finaliza la tarea. En nuestras pruebas, un guion de 27 palabras en Turbo devolvió 10.16 s y se facturó como 11 segundos, que a precios actuales son 110 créditos (11 s × 10, $0.55); un guion de 21 palabras en Avatar 6 devolvió 6.88 s y se facturó como 7 segundos, que a precios actuales son 140 créditos (7 s × 20, $0.70).
data.credits_amount en la tarea terminada es la cifra con la que debes conciliar. Hay más ejemplos en Precios de la HeyGen Avatar 6 API.
Preguntas frecuentes
¿Cómo llamo a la HeyGen Avatar 6 API desde Python?
Haz un POST de JSON a https://api.poyo.ai/api/generate/submit con requests y después consulta /api/generate/status/{task_id} con un plazo límite, como en el bucle de arriba. Sirve cualquier cliente HTTP; no hace falta ningún SDK.
¿Tiene callback la HeyGen Avatar 6 API?
Sí. Añade callback_url en el nivel superior de la solicitud. PoYo envía los datos de la tarea cuando termina o falla.
¿Por qué mi solicitud a la HeyGen Avatar 6 API devolvió HTTP 200 pero ninguna tarea?
Lee el cuerpo. Un code distinto de 200 significa que la solicitud falló, aunque el estado HTTP sea 200; error.message explica el motivo.
¿Puedo subir un archivo directamente a la HeyGen Avatar 6 API?
No. image_urls, video_url y audio_url aceptan URLs HTTP o HTTPS públicas que PoYo descarga.
¿Cuánto tiempo se conservan los resultados de la HeyGen Avatar 6 API?
Los vídeos generados están accesibles durante 3 días tras su creación. Descarga el MP4 a tu propio almacenamiento.