¿Cómo usar la API de HeyGen Avatar V? Desde elegir el avatar hasta descargar el video final

En HeyGen Avatar V eliges un avatar predefinido, introduces un guion o un audio y generas un video con sincronización labial. HiAPI cobra por duración de salida, $0.15 por segundo; un video de 10 segundos cuesta $1.50.

HeyGen Avatar V ya está disponible en HiAPI; abre la página del modelo para elegir primero el avatar y la voz, y luego conectarte a la API. El siguiente ejemplo de explicación de negocios es un video ya generado:

Brandon Office Sitting Front, Dexter - Professional; 16:9, video final 1280×720, unos 8 segundos. La solicitud original era 1080p; esta página muestra la versión web en 720p.

Hi, I'm Daniel. Send me your quarterly numbers, and I'll walk your team through what changed and what to do next.

Generar con este prompt → El guion ya está rellenado; selecciona manualmente el avatar, la voz, 1080p y 16:9 de arriba, y elige MP4 como salida.

¿Cómo probarlo en línea?

1. Abre el enlace prellenado y conserva este guion corto.
2. Elige el avatar y la voz; estos parámetros deben seleccionarse manualmente, el enlace solo incorpora el guion.
3. Configura la relación de aspecto, la resolución y el formato; la primera vez puedes usar la combinación anterior.
4. Tras generar, escucha la voz, revisa la sincronización labial, descarga el video final y luego cámbialo por tu propio texto.

Anota el avatar, la voz y la relación de aspecto de esta prueba; al generar en lote, manténlos y cambia solo el guion, así el presentador y la voz se mantienen consistentes.

V elige al presentador entre avatares predefinidos; para que tu propia foto aparezca, elige Avatar IV.

Todas las resoluciones se cobran según los segundos reales de salida; si falla, se reembolsa el importe completo; consulta la tabla de precios y presupuesto para el costo completo.

¿Qué se necesita preparar para la API?

Crea una API key en la consola. En la solicitud, indica explícitamente model, el obligatorio input.avatar, y elige uno entre prompt y audio_url. Para el avatar y la voz usa los valores de solicitud en inglés de las tarjetas de documentación; los nombres en chino solo sirven para identificarlos.

El guion se lee directamente; no incluyas instrucciones de cámara en prompt. Para la conducción por audio, pasa una dirección HTTP(S) accesible y elimina prompt y voice. No es necesario pasar duration; la duración la determina la lectura del guion o el audio.

Qué tienes	Qué campos de conducción pasar
Guion que se debe leer	avatar + prompt; voice opcional
Audio ya grabado	avatar + audio_url; omite prompt y voice

Consulta de valores de avatar: documentación de parámetros → avatar digital, despliega todo, busca y copia el «valor de solicitud» en inglés; la voz se busca igualmente en voces predefinidas. La página en inglés corresponde a Request value; no pongas nombres de visualización en chino en la solicitud.

**Solicitud mínima completa para conducción por audio:** sustituye la dirección de ejemplo por la URL de tu audio propio accesible públicamente. La relación de aspecto, la resolución y el formato omitidos usan los valores predeterminados de la documentación; el audio puede durar hasta 600 segundos y ocupar como máximo 32 MiB.

{
  "model": "heygen-avatar-v",
  "input": {
    "avatar": "Brandon Office Sitting Front",
    "audio_url": "https://example.com/your-recording.mp3"
  }
}

Crear y consultar tareas con cURL

Sustituye el marcador de Key por tu valor; esta solicitud usa los parámetros del caso de negocios:

export HIAPI_API_KEY="sk-YOUR_KEY"
curl --fail-with-body --connect-timeout 10 --max-time 60 \
  -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-v",
    "input": {
      "avatar": "Brandon Office Sitting Front",
      "prompt": "Hi, I\u0027m Daniel. Send me your quarterly numbers, and I\u0027ll walk your team through what changed and what to do next.",
      "voice": "Dexter - Professional",
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "caption": false,
      "output_format": "mp4"
    }
  }'

Revisa el estado HTTP y el code del JSON; tras crear correctamente, guarda data.taskId. Luego consulta solo la misma tarea:

TASK_ID="REPLACE_WITH_data.taskId"
curl --fail-with-body --connect-timeout 10 --max-time 60 \
  "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

queued, handling y archiving indican procesamiento; los estados finales son success o fail. Tras el éxito, busca video según data.output[].type; si habilitaste subtítulos, busca también caption. Lee la url del producto y descárgalo a tiempo según expireAt.

**Ejemplo de estructura de respuesta:** el primer bloque es la creación exitosa; el segundo es una consulta exitosa con subtítulos habilitados; el ID de tarea, las URL y la hora de expiración son valores ilustrativos; expireAt es un número en segundos Unix. Si el POST expira o se pierde la respuesta, consulta primero el registro de la tarea; no repitas el POST a ciegas; si tienes ID, continúa con GET.

{
  "code": 200,
  "data": {"taskId": "TASK_ID_FROM_CREATE"}
}

{
  "code": 200,
  "data": {
    "taskId": "TASK_ID_FROM_CREATE",
    "status": "success",
    "output": [
      {"type": "video", "url": "https://example.com/result.mp4", "expireAt": 4070908800},
      {"type": "caption", "url": "https://example.com/result.srt", "expireAt": 4070908800}
    ]
  }
}

Python: crear, sondeo limitado y descarga

Primero instala requests y configura la Key en la variable de entorno HIAPI_API_KEY. El código envía una sola vez y sondea como máximo 30 minutos; si se agota el tiempo, conserva el ID de tarea y continúa consultando.

import os
import time
from pathlib import Path
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
payload = {
    "model": "heygen-avatar-v",
    "input": {
        "avatar": "Brandon Office Sitting Front",
        "prompt": "Hi, I'm Daniel. Send me your quarterly numbers, and I'll walk your team through what changed and what to do next.",
        "voice": "Dexter - Professional",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
        "caption": False,
        "output_format": "mp4",
    },
}

def api_request(method, url, **kwargs):
    advice = (
        "Submission state may be unknown; check task history before another POST."
        if method == "POST"
        else f"Continue GET with the saved task ID: {url.rsplit('/', 1)[-1]}."
    )
    try:
        response = requests.request(
            method, url, headers=HEADERS, timeout=(10, 30), **kwargs
        )
    except requests.RequestException:
        raise RuntimeError(f"Network error. {advice}") from None
    if not response.ok:
        raise RuntimeError(f"HTTP {response.status_code}. {advice}")
    try:
        body = response.json()
    except ValueError:
        raise RuntimeError(f"Response is not JSON. {advice}") from None
    if not isinstance(body, dict):
        raise RuntimeError(f"Unexpected response shape. {advice}")
    if body.get("code") != 200 or not isinstance(body.get("data"), dict):
        raise RuntimeError(f"API error: code={body.get('code')}. {advice}")
    return body["data"]

# Submit once. No automatic POST retries.
created = api_request("POST", API, json=payload)
task_id = created.get("taskId")
if not isinstance(task_id, str) or not task_id:
    raise RuntimeError("Missing taskId; check task history before resubmitting.")
print("taskId:", task_id)  # Keep this ID to resume GET queries.
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    data = api_request("GET", f"{API}/{task_id}")
    status = data.get("status")
    if status == "fail":
        raise RuntimeError(f"Task failed: {task_id}; inspect its task record.")
    if status == "success":
        break
    if status not in ("queued", "handling", "archiving"):
        raise RuntimeError(f"Unexpected task status: {status}")
    time.sleep(8)
else:
    raise TimeoutError(f"Polling timed out; continue GET for taskId={task_id}.")

raw_outputs = data.get("output")
if not isinstance(raw_outputs, list):
    raise RuntimeError(f"Missing output list; inspect taskId={task_id}.")
outputs = {
    item["type"]: item
    for item in raw_outputs
    if isinstance(item, dict) and item.get("type") in ("video", "caption")
}
if "video" not in outputs:
    raise RuntimeError("Successful task has no video artifact.")
for kind, artifact in outputs.items():
    if not isinstance(artifact.get("url"), str) or not artifact["url"]:
        raise RuntimeError(f"Missing {kind} URL; inspect taskId={task_id}.")
    suffix = payload["input"]["output_format"] if kind == "video" else "srt"
    target = Path(f"avatar-v.{suffix}")
    # Artifact downloads do not need the API Authorization header.
    with requests.get(artifact["url"], stream=True, timeout=(10, 120)) as response:
        response.raise_for_status()
        with target.open("wb") as file:
            for chunk in response.iter_content(chunk_size=1024 * 1024):
                if chunk:
                    file.write(chunk)
    print("saved:", target)

¿Qué parámetros deben establecerse explícitamente?

Campo	Reglas y valores predeterminados
avatar	Obligatorio, valor de solicitud del avatar en inglés
prompt / audio_url	Elige uno; el guion admite hasta 5,000 caracteres, el audio dura como máximo 600 segundos y ocupa como máximo 32 MiB
voice	Opcional en la ruta de guion; predeterminado Warm Pro Narrator
resolution	Predeterminado 720p; opcionales 1080p y 4k en minúsculas
aspect_ratio	Predeterminado 16:9; también 9:16, 4:5, 5:4, 1:1, auto
fit	Predeterminado cover; opcional contain
caption	Predeterminado false; true devuelve un SRT independiente
output_format	Predeterminado mp4; opcional webm
remove_background	Predeterminado false; para uso transparente elige true junto con webm, y comprueba primero el avatar elegido con un video corto
background	Objeto; type es color o image, value contiene un color hexadecimal o una URL HTTP(S) de imagen

Resolución y relación de aspecto son dos parámetros distintos: para explicaciones horizontales usa 16:9, para videos verticales usa 9:16; indícalos en la solicitud. Tras descargar, revisa las dimensiones reales del archivo. Para WebM transparente, confirma primero el efecto de eliminación de fondo del avatar elegido y luego impórtalo en el editor.

Los subtítulos no se graban en la imagen; deben superponerse en el reproductor o en el editor. El siguiente caso vertical tiene caption=true y devuelve un SRT independiente; el video es 1080×1920 y dura 6.52 segundos, con solicitud en 1080p y 9:16. El SRT de subtítulos independiente se puede importar al editar.

New drop just landed: our travel mug keeps coffee hot for twelve hours. Swipe up and grab yours today!

Generar con este prompt → El guion ya está rellenado; selecciona manualmente Riley Casual Front, Charming Charles - Friendly, 9:16 y 1080p, activa los subtítulos y elige MP4 como salida.

¿Qué cuatro cosas revisar antes de publicar?

1. Validar la entrada: avatar, método de conducción, valores de solicitud en inglés y límites de longitud.
2. Guardar el ID de tarea: si la consulta falla o expira, continúa con GET usando el mismo ID.
3. Encontrar todos los productos: tras el éxito, busca video según type; si activaste subtítulos, busca caption.
4. Revisar la descarga: confirma las dimensiones reales, el audio y el archivo de subtítulos antes de entregar.

¿Cómo resolver los problemas comunes?

• **Problemas de validación de entrada:** revisa avatar, el campo de conducción elegido, los valores de solicitud en inglés y los límites de guion y audio; escribe la resolución como 4k y elimina duration.
• **POST expirado:** consulta primero el registro de la tarea; si ya tienes taskId, continúa con GET; cada POST crea una nueva tarea.
• **Tarea fail:** revisa el motivo del error en el registro de la tarea y vuelve a enviar tras corregir la entrada correspondiente.
• **Enlace de descarga expirado:** guarda los productos a tiempo tras el éxito; lee los subtítulos desde type=caption.

El servidor puede añadir al mismo nivel de input "callback": {"url": "https://yourapp.com/webhook", "when": "final"}, recibir el objeto de tarea en estado final y usar consultas GET de compensación.

Para detalles de precio, consulta la tabla de precio por segundo y presupuesto; para cambiar de avatar, consulta dos casos; para todos los valores, consulta la documentación de parámetros de la API.

Generar con este prompt → El guion ya está rellenado; selecciona manualmente el avatar y la voz de negocios, 1080p, 16:9 y MP4; genera primero una frase y luego conecta el guion completo.