how-tos

Guia da HeyGen Avatar 6 API: o primeiro vídeo falante em cURL e Python

Poyo.ai Team
9 min read
Share:

Guia da HeyGen Avatar 6 API: o primeiro vídeo falante em cURL e Python

Este guia da HeyGen Avatar 6 API leva-te de uma chave de API a um vídeo falante pronto no PoYo. Submetes um pedido JSON com o ID de modelo heygen-avatar-6 (ou heygen-avatar-6-turbo), guardas o task ID devolvido e fazes polling até o MP4 estar pronto. Todos os corpos de pedido abaixo seguem o formato da documentação PoYo; a página do modelo HeyGen Avatar 6 tem um Playground se quiseres ver primeiro as entradas.

Antes de começar

  • Cria uma chave em poyo.ai/dashboard/api-key e exporta-a como POYO_API_KEY. Mantém-na no teu servidor.
  • Aloja cada ficheiro de entrada num URL HTTP ou HTTPS público e descarregável diretamente. O PoYo vai buscar os media por si; não aceita uploads no pedido.
  • Escolhe um nível. Os dois IDs aceitam os mesmos campos. O Turbo custa 10 créditos ($0.05) por segundo em 1080p; o Avatar 6 custa 20 créditos ($0.10). Vê Avatar 6 vs Turbo.

O teu primeiro pedido à HeyGen Avatar 6 API com cURL

O primeiro pedido mais rápido não precisa de media nenhum: um avatar público da HeyGen lê o teu 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"
    }
  }'

Uma resposta bem-sucedida tem "code": 200 e data.task_id, com status definido como not_started. É um trabalho em fila, não um vídeo. Faz polling:

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Os estados são not_started, running, finished e failed. Quando está finished, o MP4 está em data.files[] com file_type video, e data.credits_amount mostra o que foi cobrado. Em failed, lê data.error_message.

Um ciclo de polling Python com limite de tempo

Nos nossos testes do dia do lançamento, a 19 de novembro de 2026, clips curtos de texto demoraram cerca de 2 a 2.4 minutos da submissão ao resultado. Este ciclo consulta a cada 5 segundos (a documentação de estado recomenda 2–5 s), para aos 15 minutos e nunca volta a submeter em caso de timeout, porque uma segunda submissão é uma segunda tarefa cobrada.

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)

Em produção, adiciona um callback_url no nível superior em vez de fazeres polling. O PoYo envia o mesmo objeto de tarefa (sem o invólucro code / data) quando a tarefa está finished ou failed, assinado com HMAC-SHA256 em X-Webhook-Signature; a documentação de webhooks indica a regra da assinatura.

Os três modos de entrada da HeyGen Avatar 6 API

Não há um seletor de modo. avatar seleciona o modo avatar público; caso contrário, video_url seleciona o modo vídeo de referência; caso contrário, o pedido corre em modo foto. Usa as entradas de um só modo por pedido.

Modo avatar público com texto

Mostrado acima. avatar é um dos 1,248 looks públicos, text vai até 1,000 caracteres e voice é uma das 102 vozes (predefinida Warm Pro Narrator). O guia text-to-avatar explica como escolher looks e vozes do catálogo.

Modo avatar público com o teu áudio

Troca text e voice por audio_url. aspect_ratio continua a aplicar-se:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Abigail Sofa Front",
    "audio_url": "https://example.com/speech.mp3",
    "aspect_ratio": "9:16"
  }
}

Modo foto

Uma foto de uma pessoa real mais a fala. O vídeo mantém a proporção da foto, por isso recorta a foto para o enquadramento que queres antes de a enviares. callback_url fica ao lado de model, não 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 vídeo de referência

Para personagens animadas ou ilustradas. video_url é um clip da personagem; image_urls acrescenta opcionalmente uma imagem fixa da mesma personagem. A saída mantém a proporção do 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"
  }
}

Regras de validação dos campos da HeyGen Avatar 6 API

Verifica-as no teu próprio código antes de submeter; são os limites documentados.

CampoModoRegra
modelTodosheygen-avatar-6 ou heygen-avatar-6-turbo
image_urlsFoto (obrigatório), vídeo de referência (opcional)Array com exatamente um URL
video_urlVídeo de referênciaPelo menos 2 s, até 50 MB
avatarAvatar públicoUm dos 1,248 nomes listados
audio_urlFoto, vídeo de referência; ou avatar público em vez de text2–60 s, até 15 MB
textAvatar público1–1,000 caracteres
voiceAvatar público com textUm de 102 nomes
promptTodosAté 1,200 caracteres
aspect_ratioAvatar público16:9, 9:16, 1:1, 4:5, 5:4
resolutionTodos1080p (predefinido) ou 2K

Os nomes de avatares e vozes correspondem independentemente de maiúsculas/minúsculas e espaços extra, com uma exceção documentada: Hope e Hope (com espaço final) são duas vozes diferentes. O esquema de entrada não permite campos extra, por isso não envies opções nativas da HeyGen como motion_expressiveness ou motion_prompt da API da própria HeyGen; no PoYo, a direção de movimento vai em prompt.

Erros que vale a pena tratar

Lê sempre code no corpo da resposta. Alguns erros de validação chegam como HTTP 200 com "code": 400, por isso verificar apenas o estado HTTP não chega.

code no corpoerror.typeO que fazer
400validation_error e outrosCorrige a entrada: áudio fora de 2–60 s, nome de avatar desconhecido, um campo de outro modo. Não repitas sem alterações
401authentication_errorVerifica o cabeçalho Authorization: Bearer
402insufficient_credits_errorCarrega saldo, ou espera que as tarefas de texto em curso sejam acertadas (ver abaixo)
429rate_limit_errorAbranda e tenta de novo
500 / 502 / 503internal_error, upstream_error, service_errorTenta de novo com backoff exponencial

A duração do áudio, a duração do vídeo de referência e o nome do avatar são verificados na submissão, por isso estes erros aparecem como um 400 imediato em vez de uma tarefa falhada minutos depois.

O caso 402 tem uma particularidade própria da HeyGen. No nosso teste do dia do lançamento, depois de submetidas duas tarefas de texto, um terceiro pedido (Turbo, 2K, 22 palavras) voltou como HTTP 200 com code 402 no corpo e tipo insufficient_credits_error: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." As tarefas de texto retêm créditos enquanto correm, por isso uma rajada de submissões de texto pode receber 402 mesmo quando as cobranças finais caberiam no saldo. Põe os trabalhos de texto em fila, ou mostra a mensagem de erro ao utilizador, já que ela indica os dois números.

Como é calculada a primeira fatura da HeyGen Avatar 6 API

O PoYo cobra por segundo de saída, arredondado para cima, para segundos inteiros (1 crédito = $0.005):

Modelo1080p2K
heygen-avatar-6-turbo10 créditos ($0.05) / s18 créditos ($0.09) / s
heygen-avatar-620 créditos ($0.10) / s29 créditos ($0.145) / s
  • Com audio_url (todos os modos): a cobrança é a duração do áudio, arredondada para cima, feita na submissão. Um clip de 12.3 segundos no Avatar 6 em 1080p custa 13 × 20 = 260 créditos ($1.30).
  • Com text: os créditos são reservados na submissão e acertados pela duração do vídeo final quando a tarefa termina. Nos nossos testes, um guião de 27 palavras no Turbo devolveu 10.16 s, cobrados como 11 segundos, o que aos preços atuais dá 110 créditos (11 s × 10, $0.55); um guião de 21 palavras no Avatar 6 devolveu 6.88 s, cobrados como 7 segundos, o que aos preços atuais dá 140 créditos (7 s × 20, $0.70).

data.credits_amount na tarefa terminada é o número com que deves fazer a reconciliação. Mais exemplos estão em Preços da HeyGen Avatar 6 API.

Perguntas frequentes

Como chamo a HeyGen Avatar 6 API a partir de Python?

Faz POST de JSON para https://api.poyo.ai/api/generate/submit com requests e depois faz polling de /api/generate/status/{task_id} com um prazo, como no ciclo acima. Qualquer cliente HTTP serve; não é necessário SDK.

Existe um callback na HeyGen Avatar 6 API?

Sim. Adiciona callback_url no nível superior do pedido. O PoYo envia os dados da tarefa quando termina ou falha.

Porque é que o meu pedido à HeyGen Avatar 6 API devolveu HTTP 200 mas nenhuma tarefa?

Lê o corpo. Um code diferente de 200 significa que o pedido falhou, mesmo com HTTP 200; error.message explica porquê.

Posso enviar um ficheiro diretamente para a HeyGen Avatar 6 API?

Não. image_urls, video_url e audio_url aceitam URLs HTTP ou HTTPS públicos que o PoYo descarrega.

Durante quanto tempo são guardados os resultados da HeyGen Avatar 6 API?

Os vídeos gerados ficam acessíveis durante 3 dias após a criação. Descarrega o MP4 para o teu próprio armazenamento.

Share: