![]()
A HeyGen Avatar 6 API consegue fazer um vídeo com apresentador a partir de nada mais do que um guião. No modo avatar público indicas um dos 1,248 looks de stock da HeyGen, envias até 1,000 caracteres de text, escolhes uma de 102 vozes, e o heygen-avatar-6 (ou heygen-avatar-6-turbo) devolve um MP4 com sincronização labial. Sem foto, sem gravação, sem passo de texto para fala do teu lado. Este guia explica como escolher um look e uma voz do catálogo, dirigir gestos com prompt, escolher o formato do enquadramento e quanto custa um pedido de texto. Também podes explorar os looks na página do modelo HeyGen Avatar 6.
O pedido text-to-avatar
Este é o corpo documentado para o modo avatar público com texto:
{
"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"
}
}
| Campo | Obrigatório | Regra |
|---|---|---|
avatar | Sim | Um dos 1,248 nomes de looks |
text | Sim (em vez de audio_url) | 1–1,000 caracteres |
voice | Não | Um de 102 nomes; predefinido Warm Pro Narrator |
prompt | Não | Até 1,200 caracteres de direção |
aspect_ratio | Não | 16:9 (predefinido), 9:16, 1:1, 4:5, 5:4 |
resolution | Não | 1080p (predefinido) ou 2K |
É a presença de avatar que seleciona este modo. Não envies também image_urls ou video_url; usa as entradas de um só modo por pedido. Submete para POST https://api.poyo.ai/api/generate/submit e consulta /api/generate/status/{task_id} como no guia da HeyGen Avatar 6 API.
Escolhe um look de avatar no catálogo
O PoYo publica todos os nomes na página Avatars and Voices e como catálogo JSON. O catálogo tem cinco chaves:
| Chave | Conteúdo |
|---|---|
models | heygen-avatar-6, heygen-avatar-6-turbo (os mesmos nomes funcionam em ambos) |
default_voice | Warm Pro Narrator |
avatars | Todos os 1,248 nomes de looks, numa lista simples |
avatars_by_person | Os mesmos looks agrupados por 156 pessoas |
voices | Todos os 102 nomes de vozes |
Cada pessoa tem um ou mais looks, e cada look é um valor avatar distinto. A Abigail tem cinco (Abigail (Upper Body), Abigail Office Front, Abigail Office Side, Abigail Sofa Front, Abigail Sofa Side); a Annie tem 54; oito pessoas têm um único look. Os nomes descrevem o cenário, a roupa e o ângulo de câmara, o que normalmente chega para escolher sem pré-visualizar:
| Queres | Procura nomes como | Exemplos |
|---|---|---|
| Apresentador virado para a câmara | Front | Abigail Office Front, Bryan Suit Front |
| Ângulo de três quartos | Side | Abigail Office Side |
| Sentado, informal | Sofa, Sitting, Lounge | Annie Sofa Sitting Front |
| Uma função ou cenário | Doctor, Nurse, Yoga, Tech Expert | Ann Doctor Standing, Adriana Nurse Front, Amelia Yoga Front, Bryan Tech Expert |
Cerca de 480 nomes contêm Front e cerca de 430 contêm Side. Para uma série de vídeos explicativos, escolhe uma pessoa e fica pelos seus looks Front, para que o apresentador seja o mesmo em todos os vídeos. Usa o look Side correspondente para os planos de corte.
Os nomes correspondem independentemente de maiúsculas/minúsculas e espaços extra, por isso abigail office front seleciona Abigail Office Front. O PoYo verifica avatar contra a lista na submissão, por isso um erro de escrita devolve um 400 imediato em vez de uma tarefa falhada. Valida primeiro no teu próprio código:
import requests
catalog = requests.get(
"https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()
def norm(name: str) -> str:
return " ".join(name.split()).lower()
AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])
def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
if norm(avatar) not in AVATARS:
raise ValueError(f"unknown avatar: {avatar!r}")
if not 1 <= len(text) <= 1000:
raise ValueError("text must be 1-1,000 characters")
if voice is not None and voice not in VOICES:
raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
if prompt is not None and len(prompt) > 1200:
raise ValueError("prompt must be at most 1,200 characters")
body = {"avatar": AVATARS[norm(avatar)], "text": text,
"aspect_ratio": aspect_ratio, "resolution": resolution}
if voice:
body["voice"] = voice
if prompt:
body["prompt"] = prompt
return {"model": model, "input": body}
A verificação da voz usa nomes exatos de propósito; a secção seguinte explica porquê.
Escolhe uma voz
voice decide quem lê o text. Se o omitires, recebes Warm Pro Narrator. As 102 vozes incluem nomes simples (Andrew, Ivy, Jessica Anne Bogart), nomes descritivos (Calm Chloe, Professor Dean, Radio Rick, Chill Brian) e alguns com uma indicação de estilo no nome.
Três coisas costumam causar problemas:
- Os espaços finais podem contar. A documentação assinala que
HopeeHope(com espaço final) são duas vozes diferentes.Archer,Cassidy,Adam Stone,Spuds OxleyeAndrew Rizztambém terminam com um espaço no catálogo. Copia os nomes do JSON em vez de os escreveres de novo. - Alguns nomes contêm emoji ou sufixos que parecem nomes de ficheiro, como
Cute Chloe - Friendly 😊ouBrenda - UGC - 1.mp4. Esses caracteres fazem parte do nome. Envia o corpo do pedido como JSON UTF-8 e o nome passa sem alterações. - A voz não está ligada ao avatar. Qualquer uma das 102 vozes pode ler para qualquer um dos 1,248 looks. Escolhe uma voz que combine com a pessoa no ecrã; os nossos testes do dia do lançamento juntaram
Bryan Tech ExpertcomAndreweAbigail Office FrontcomJessica Anne Bogart.
voice só se aplica quando envias text. Se enviares audio_url, o avatar diz a tua gravação e voice não é usado.
Dirige gestos com prompt
prompt aceita até 1,200 caracteres de direção para gestos, expressão e postura. O relatório técnico da HeyGen descreve a técnica: "Escreve a ação ao lado das palavras. O Avatar 6 executa-a no momento exato." O seu exemplo: "Farmacêutico simpático. Em 'Hello', faz um polegar para cima. Em 'the counter on the left', aponta para o lado com o indicador."
Um padrão que segue esse formato:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Bryan Tech Expert",
"text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
"voice": "Andrew",
"prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
Dicas para manter os prompts úteis:
- Cita as palavras exatas do
textem que cada ação deve cair, para que a deixa não seja ambígua. - Descreve primeiro um papel ou estado de espírito ("Friendly product expert") e depois as deixas.
- Omite o
promptquando não tens deixas específicas. A página de lançamento do Avatar 6 da HeyGen diz que o modelo "ajusta gestos, emoção e expressão ao teu guião" por si só.
Escolhe a proporção conforme o destino
aspect_ratio só existe no modo avatar público; os modos foto e vídeo de referência mantêm o formato da entrada.
| Destino | aspect_ratio |
|---|---|
| Site, YouTube, aula num LMS | 16:9 (predefinido) |
| Shorts, Reels, TikTok, stories | 9:16 |
| Publicação quadrada no feed, cartão na app | 1:1 |
| Publicação vertical no feed | 4:5 |
| Publicação horizontal no feed | 5:4 |
resolution é independente: 1080p ou 2K em qualquer proporção. O 2K custa mais por segundo, por isso gera os rascunhos em 1080p.
Quanto vai durar o vídeo e quanto custa
Com texto, o vídeo dura o tempo que o avatar demora a lê-lo, até 1,000 caracteres. É-te cobrada a duração do vídeo final, arredondada para cima, para segundos inteiros. Os créditos são reservados quando submetes e acertados pelos segundos reais quando a tarefa termina.
Os nossos testes do dia do lançamento na API de produção, 19 de novembro de 2026 (16:9, 1080p):
| Modelo | Avatar / voz | Guião | Saída | Custo aos preços atuais | Tempo real |
|---|---|---|---|---|---|
heygen-avatar-6-turbo | Abigail Office Front / Jessica Anne Bogart | 27 palavras | 10.16 s | 110 créditos ($0.55) | Cerca de 2.4 min |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21 palavras | 6.88 s | 140 créditos ($0.70) | Cerca de 2 min |
Isto dá cerca de 2.7 e 3.1 palavras por segundo nestas duas execuções, útil para um orçamento aproximado mas não uma garantia, já que o ritmo varia com a voz e o guião. Tarifas por segundo: Turbo 10 créditos ($0.05) em 1080p ou 18 ($0.09) em 2K; Avatar 6 20 créditos ($0.10) ou 29 ($0.145). Vê Preços da HeyGen Avatar 6 API para mais detalhes.
Como as tarefas de texto mantêm uma reserva enquanto correm, lançar muitas de uma vez pode devolver HTTP 200 com code 402 no corpo (insufficient_credits_error). No nosso teste, um terceiro pedido foi recusado com: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Põe os trabalhos de texto em fila, ou mantém um saldo que cubra as reservas em curso. Usa o Turbo enquanto iteras; a comparação Avatar 6 vs Turbo mostra quando mudar.
Perguntas frequentes
A HeyGen Avatar 6 API consegue transformar texto num vídeo com avatar falante?
Sim. No modo avatar público, envia avatar, até 1,000 caracteres de text e, opcionalmente, voice. Não é preciso ficheiro de áudio.
Onde está a lista de avatares e vozes da HeyGen Avatar 6 API?
Na página Avatars and Voices da documentação PoYo, e como catálogo JSON descarregável com as chaves avatars, avatars_by_person e voices.
Qual é a voz predefinida da HeyGen Avatar 6 API?
Warm Pro Narrator, usada quando voice é omitido.
Posso usar a minha própria foto com texto em vez de um avatar de stock?
Não. text só funciona no modo avatar público. Para a tua própria foto, usa o modo foto com image_urls e um audio_url; se for preciso, gera primeiro o áudio com um modelo TTS.
Que proporções suporta o text to avatar do HeyGen Avatar 6?
16:9, 9:16, 1:1, 4:5 e 5:4, em 1080p ou 2K.
Como é cobrado um pedido de texto da HeyGen Avatar 6 API?
Pela duração do vídeo final, arredondada para cima, para segundos inteiros, à tarifa por segundo do modelo. Os créditos são reservados na submissão e acertados quando a tarefa termina.