![]()
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-keye exporta-a comoPOYO_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.
| 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 um 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 em vez 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 (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 corpo | error.type | O que fazer |
|---|---|---|
| 400 | validation_error e outros | Corrige a entrada: áudio fora de 2–60 s, nome de avatar desconhecido, um campo de outro modo. Não repitas sem alterações |
| 401 | authentication_error | Verifica o cabeçalho Authorization: Bearer |
| 402 | insufficient_credits_error | Carrega saldo, ou espera que as tarefas de texto em curso sejam acertadas (ver abaixo) |
| 429 | rate_limit_error | Abranda e tenta de novo |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Tenta 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):
| 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 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.