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 você de uma chave de API a um vídeo falante pronto na PoYo. Você envia uma requisição JSON com o ID de modelo heygen-avatar-6 (ou heygen-avatar-6-turbo), guarda o task ID retornado e faz polling até o MP4 ficar pronto. Todos os corpos de requisição abaixo seguem o formato da documentação da PoYo; a página do modelo HeyGen Avatar 6 tem um Playground se você quiser ver as entradas antes.

Antes de começar

  • Crie uma chave em poyo.ai/dashboard/api-key e exporte-a como POYO_API_KEY. Mantenha-a no seu servidor.
  • Hospede cada arquivo de entrada em uma URL HTTP ou HTTPS pública e baixável diretamente. A PoYo busca a mídia por conta própria; ela não aceita uploads na requisição.
  • Escolha 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). Veja Avatar 6 vs Turbo.

Sua primeira requisição à HeyGen Avatar 6 API com cURL

A primeira requisição mais rápida não precisa de nenhuma mídia: um avatar público da HeyGen lê o seu 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. Isso é um job na fila, não um vídeo. Faça polling:

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

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

Um loop de polling em Python com limite de tempo

Nos nossos testes do dia do lançamento, em 19 de novembro de 2026, clipes curtos de texto levaram cerca de 2 a 2.4 minutos do envio ao resultado. Este loop consulta a cada 5 segundos (a documentação de status recomenda 2–5 s), para em 15 minutos e nunca reenvia em caso de timeout, porque um segundo envio é 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, adicione um callback_url no nível superior em vez de fazer polling. A PoYo envia o mesmo objeto de tarefa (sem o envelope code / data) quando a tarefa está finished ou failed, assinado com HMAC-SHA256 em X-Webhook-Signature; a documentação de webhooks traz 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; senão, video_url seleciona o modo vídeo de referência; senão, a requisição roda no modo foto. Use as entradas de um único modo por requisição.

Modo avatar público com texto

Mostrado acima. avatar é um dos 1,248 looks públicos, text tem até 1,000 caracteres e voice é uma das 102 vozes (padrão Warm Pro Narrator). O guia text-to-avatar mostra como escolher looks e vozes no catálogo.

Modo avatar público com o seu áudio

Troque text e voice por audio_url. aspect_ratio continua valendo:

{
  "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, então recorte a foto no enquadramento desejado antes de enviá-la. 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 animados ou ilustrados. video_url é um clipe do personagem; image_urls adiciona opcionalmente uma imagem estática do mesmo personagem. A saída mantém a proporção do clipe:

{
  "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

Verifique estas regras no seu próprio código antes de enviar; 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 uma 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 no lugar 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 (padrão) ou 2K

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

Erros que vale a pena tratar

Sempre leia code no corpo da resposta. Alguns erros de validação voltam como HTTP 200 com "code": 400, então verificar só o status HTTP não basta.

code no corpoerror.typeO que fazer
400validation_error e outrosCorrija a entrada: áudio fora de 2–60 s, nome de avatar desconhecido, um campo de outro modo. Não repita sem alterar
401authentication_errorVerifique o header Authorization: Bearer
402insufficient_credits_errorRecarregue, ou espere as tarefas de texto em andamento serem acertadas (veja abaixo)
429rate_limit_errorReduza o ritmo e tente de novo
500 / 502 / 503internal_error, upstream_error, service_errorTente 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 no envio, então esses erros aparecem como um 400 imediato, e não como uma tarefa que falha minutos depois.

O caso 402 tem uma particularidade da HeyGen. No nosso teste do dia do lançamento, depois de enviadas duas tarefas de texto, uma terceira requisição (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." Tarefas de texto retêm créditos enquanto rodam, então uma rajada de envios de texto pode receber 402 mesmo quando as cobranças finais caberiam no saldo. Coloque os jobs de texto em fila, ou mostre a mensagem de erro ao usuário, já que ela informa os dois números.

Como a primeira cobrança da HeyGen Avatar 6 API é calculada

A 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 no envio. Um clipe 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 no envio e acertados pela duração do vídeo final quando a tarefa termina. Nos nossos testes, um roteiro de 27 palavras no Turbo gerou 10.16 s, cobrados como 11 segundos, o que nos preços atuais dá 110 créditos (11 s × 10, $0.55); um roteiro de 21 palavras no Avatar 6 gerou 6.88 s, cobrados como 7 segundos, o que nos preços atuais dá 140 créditos (7 s × 20, $0.70).

data.credits_amount na tarefa concluída é o número para conciliar. Mais exemplos estão em Preço da HeyGen Avatar 6 API.

Perguntas frequentes

Como chamo a HeyGen Avatar 6 API em Python?

Faça um POST de JSON para https://api.poyo.ai/api/generate/submit com requests e depois faça polling de /api/generate/status/{task_id} com um prazo, como no loop acima. Qualquer cliente HTTP funciona; não é preciso SDK.

A HeyGen Avatar 6 API tem callback?

Sim. Adicione callback_url no nível superior da requisição. A PoYo envia os dados da tarefa quando ela termina ou falha.

Por que minha requisição à HeyGen Avatar 6 API retornou HTTP 200 mas nenhuma tarefa?

Leia o corpo. Um code diferente de 200 significa que a requisição falhou, mesmo com HTTP 200; error.message explica o motivo.

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

Não. image_urls, video_url e audio_url aceitam URLs HTTP ou HTTPS públicas que a PoYo baixa.

Por quanto tempo os resultados da HeyGen Avatar 6 API ficam guardados?

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

Share: