Como usar a API HeyGen Avatar V? Da escolha do avatar ao download do vídeo final

No HeyGen Avatar V, escolha um avatar predefinido, insira uma fala ou áudio e gere um vídeo com sincronização labial. A HiAPI cobra pela duração da saída, US$ 0,15 por segundo, US$ 1,50 por um vídeo de 10 segundos.

O HeyGen Avatar V já está disponível na HiAPI. Abra a página do modelo para escolher primeiro o avatar e a voz e depois conectar a API. Este exemplo de apresentação comercial é um vídeo final já pronto:

Brandon Office Sitting Front, Dexter - Professional; 16:9, vídeo final 1280×720, cerca de 8 segundos. A solicitação original era 1080p; esta página mostra a versão web em 720p.

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

Gerar com este prompt → A fala já está preenchida; selecione manualmente o avatar, a voz, 1080p e 16:9 acima, e escolha MP4 como saída.

Como testar online?

1. Abra o link pré-preenchido e mantenha esta fala curta.
2. Escolha o avatar e a voz; esses parâmetros precisam ser selecionados manualmente, o link só traz a fala.
3. Defina proporção, resolução e formato; no primeiro teste use a combinação acima.
4. Após gerar, ouça a dublagem, confira a sincronização labial, baixe o vídeo final e depois troque pelo seu próprio texto.

Anote o avatar, a voz e a proporção usados neste teste; ao gerar em lote, mantenha-os e troque apenas a fala, assim o apresentador e a voz permanecem consistentes.

O V permite escolher o apresentador entre avatares predefinidos; para usar sua própria foto como apresentador, escolha o Avatar IV.

Todas as resoluções são cobradas pelos segundos reais de saída, com reembolso integral em caso de falha; veja os custos completos na tabela de preços e orçamento.

O que preparar para a API?

Crie uma API key no console. Na solicitação, escreva explicitamente model, o obrigatório input.avatar e escolha um entre prompt e audio_url. Use os valores de solicitação em inglês dos cartões da documentação para avatar e voz; os nomes em chinês servem apenas para identificação.

A fala é lida diretamente; não coloque instruções de câmera no prompt. Para condução por áudio, envie um endereço HTTP(S) acessível e remova prompt e voice. Não é necessário enviar duration; a duração é determinada pela leitura da fala ou pelo áudio.

O que você tem	Quais campos de condução enviar
Fala a ser lida	avatar + prompt; voice é opcional
Áudio já gravado	avatar + audio_url; omita prompt e voice

Consulta de valores de avatar: documentação de parâmetros → avatar digital, expanda tudo, pesquise e copie o "valor de solicitação" em inglês; a voz também é consultada em vozes predefinidas. A página em inglês corresponde a Request value; não coloque o nome de exibição em chinês na solicitação.

**Solicitação completa mínima para condução por áudio:** substitua o endereço de exemplo pela URL do seu áudio publicamente acessível. Proporção, resolução e formato omitidos usam os padrões da documentação; o áudio tem no máximo 600 segundos e no máximo 32 MiB.

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

Criar e consultar tarefas com cURL

Substitua o placeholder da Key pelo seu valor; esta solicitação usa os parâmetros do caso comercial:

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"
    }
  }'

Verifique o status HTTP e o code do JSON; após criar com sucesso, guarde data.taskId. Em seguida, consulte apenas a mesma tarefa:

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 e archiving indicam processamento; os estados finais são success ou fail. Após sucesso, procure video conforme data.output[].type; se as legendas estiverem ativadas, procure também caption. Leia o url do artefato e baixe antes de expireAt.

**Exemplo de estrutura de resposta:** o primeiro trecho é a criação bem-sucedida, o segundo é uma consulta bem-sucedida com legendas ativadas; ID da tarefa, URLs e tempo de expiração são valores ilustrativos; expireAt é um número em segundos Unix. Em caso de timeout ou resposta perdida no POST, consulte primeiro o registro da tarefa e não faça outro POST às cegas; se houver ID, continue com 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: criar, polling limitado, baixar

Instale requests e defina a Key na variável de ambiente HIAPI_API_KEY. O código envia apenas uma vez e faz polling por no máximo 30 minutos; em caso de timeout, guarde o ID da tarefa e continue 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)

Quais parâmetros precisam ser definidos explicitamente?

Campo	Regras e padrões
avatar	Obrigatório, valor de solicitação do avatar em inglês
prompt / audio_url	Escolha um; a fala tem no máximo 5.000 caracteres, o áudio no máximo 600 segundos e no máximo 32 MiB
voice	Opcional no caminho de fala, padrão Warm Pro Narrator
resolution	Padrão 720p, opções 1080p e 4k em minúsculas
aspect_ratio	Padrão 16:9; também 9:16, 4:5, 5:4, 1:1, auto
fit	Padrão cover, opção contain
caption	Padrão false; true retorna SRT separado
output_format	Padrão mp4, opção webm
remove_background	Padrão false; para uso transparente escolha true com webm, teste primeiro com um clipe curto no avatar escolhido
background	Objeto; type é color ou image, value recebe uma cor hexadecimal ou URL HTTP(S) de imagem

Resolução e proporção são dois parâmetros: use 16:9 para apresentações horizontais e 9:16 para falas verticais, indicando ambos na solicitação. Após baixar, confira as dimensões reais do arquivo. Para WebM transparente, confirme primeiro o efeito de remoção de fundo do avatar escolhido e depois importe no editor de vídeo.

As legendas não são incorporadas na imagem; é preciso sobrepô-las no player ou no editor de vídeo. O caso vertical abaixo define caption=true e retorna um SRT separado; o vídeo tem 1080×1920 e 6,52 segundos, com solicitação em 1080p e 9:16. O SRT de legendas separado pode ser importado na edição.

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

Gerar com este prompt → A fala já está preenchida; selecione manualmente Riley Casual Front, Charming Charles - Friendly, 9:16 e 1080p, ative as legendas e escolha MP4 como saída.

Quais quatro itens verificar antes de publicar?

1. Validar entrada: avatar, modo de condução, valores de solicitação em inglês e limites de tamanho.
2. Guardar o ID da tarefa: se a consulta falhar ou der timeout, continue com GET usando o mesmo ID.
3. Encontrar todos os artefatos: após sucesso, procure video por type; com legendas ativadas, procure caption.
4. Verificar o download: confirme dimensões reais, áudio e arquivo de legendas antes de entregar.

Como lidar com problemas comuns?

• **Problema na validação de entrada:** verifique avatar, o campo de condução escolhido, os valores de solicitação em inglês, os limites de fala e áudio; escreva a resolução como 4k e remova duration.
• **Timeout no POST:** consulte primeiro o registro da tarefa; se já houver taskId, continue com GET, pois cada POST cria uma nova tarefa.
• **Tarefa fail:** veja o motivo do erro no registro da tarefa, ajuste a entrada correspondente e envie novamente.
• **Link de download expirado:** salve os artefatos assim que obtiver sucesso; as legendas são lidas em type=caption.

O servidor pode adicionar "callback": {"url": "https://yourapp.com/webhook", "when": "final"} no mesmo nível de input para receber o objeto da tarefa em estado final e usar GET como consulta de compensação.

Veja os detalhes de preço na tabela de preço por segundo e orçamento, consulte dois casos para trocar de avatar e veja todos os valores na documentação de parâmetros da API.

Gerar com este prompt → A fala já está preenchida; selecione manualmente o avatar e a voz comerciais, 1080p, 16:9 e MP4, gere primeiro uma frase e depois conecte o roteiro completo.