![]()
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-keye exporte-a comoPOYO_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.
| Campo | Modo | Regra |
|---|---|---|
model | Todos | heygen-avatar-6 ou heygen-avatar-6-turbo |
image_urls | Foto (obrigatório), vídeo de referência (opcional) | Array com exatamente uma URL |
video_url | Vídeo de referência | Pelo menos 2 s, até 50 MB |
avatar | Avatar público | Um dos 1,248 nomes listados |
audio_url | Foto, vídeo de referência; ou avatar público no lugar de text | 2–60 s, até 15 MB |
text | Avatar público | 1–1,000 caracteres |
voice | Avatar público com text | Um de 102 nomes |
prompt | Todos | Até 1,200 caracteres |
aspect_ratio | Avatar público | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Todos | 1080p (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 corpo | error.type | O que fazer |
|---|---|---|
| 400 | validation_error e outros | Corrija a entrada: áudio fora de 2–60 s, nome de avatar desconhecido, um campo de outro modo. Não repita sem alterar |
| 401 | authentication_error | Verifique o header Authorization: Bearer |
| 402 | insufficient_credits_error | Recarregue, ou espere as tarefas de texto em andamento serem acertadas (veja abaixo) |
| 429 | rate_limit_error | Reduza o ritmo e tente de novo |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Tente 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):
| 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 |
- 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.