how-tos

HeyGen Avatar 6 API text to avatar: vídeos com apresentador a partir de um roteiro, sem arquivo de áudio

Poyo.ai Team
10 min read
Share:

HeyGen Avatar 6 API text to avatar: um vídeo com apresentador a partir de um roteiro

A HeyGen Avatar 6 API consegue fazer um vídeo com apresentador a partir de nada além de um roteiro. No modo avatar público, você indica um dos 1,248 looks de banco da HeyGen, envia até 1,000 caracteres de text, escolhe uma de 102 vozes, e o heygen-avatar-6 (ou heygen-avatar-6-turbo) retorna um MP4 com sincronização labial. Sem foto, sem gravação, sem etapa de texto para fala do seu lado. Este passo a passo mostra como escolher um look e uma voz no catálogo, dirigir gestos com prompt, escolher o formato do quadro e quanto custa uma requisição de texto. Você também pode navegar pelos looks na página do modelo HeyGen Avatar 6.

A requisição 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"
  }
}
CampoObrigatórioRegra
avatarSimUm dos 1,248 nomes de looks
textSim (no lugar de audio_url)1–1,000 caracteres
voiceNãoUm de 102 nomes; padrão Warm Pro Narrator
promptNãoAté 1,200 caracteres de direção
aspect_ratioNão16:9 (padrão), 9:16, 1:1, 4:5, 5:4
resolutionNão1080p (padrão) ou 2K

É a presença de avatar que seleciona este modo. Não envie também image_urls ou video_url; use as entradas de um único modo por requisição. Envie para POST https://api.poyo.ai/api/generate/submit e consulte /api/generate/status/{task_id} como no guia da HeyGen Avatar 6 API.

A PoYo publica todos os nomes na página Avatars and Voices e como catálogo JSON. O catálogo tem cinco chaves:

ChaveConteúdo
modelsheygen-avatar-6, heygen-avatar-6-turbo (os mesmos nomes funcionam nos dois)
default_voiceWarm Pro Narrator
avatarsTodos os 1,248 nomes de looks, em uma lista simples
avatars_by_personOs mesmos looks agrupados por 156 pessoas
voicesTodos os 102 nomes de vozes

Cada pessoa tem um ou mais looks, e cada look é um valor avatar separado. 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 cenário, roupa e ângulo de câmera, o que geralmente basta para escolher sem pré-visualizar:

Você querProcure nomes comoExemplos
Apresentador de frente para a câmeraFrontAbigail Office Front, Bryan Suit Front
Ângulo de três quartosSideAbigail Office Side
Sentado, informalSofa, Sitting, LoungeAnnie Sofa Sitting Front
Uma função ou cenárioDoctor, Nurse, Yoga, Tech ExpertAnn 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, escolha uma pessoa e fique nos looks Front dela, para que o apresentador seja o mesmo em todos os vídeos. Use o look Side correspondente para os cortes.

Os nomes são reconhecidos independentemente de maiúsculas/minúsculas e espaços extras, então abigail office front seleciona Abigail Office Front. A PoYo verifica avatar contra a lista no envio, então um erro de digitação retorna um 400 imediato em vez de uma tarefa que falha. Valide antes no seu 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 próxima seção explica por quê.

Escolha uma voz

voice decide quem lê o text. Se você não enviar, recebe 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:

  • Espaços no final podem fazer diferença. A documentação destaca que Hope e Hope (com espaço no final) são duas vozes diferentes. Archer , Cassidy , Adam Stone , Spuds Oxley e Andrew Rizz também terminam com espaço no catálogo. Copie os nomes do JSON em vez de digitá-los de novo.
  • Alguns nomes contêm emoji ou sufixos que parecem nomes de arquivo, como Cute Chloe - Friendly 😊 ou Brenda - UGC - 1.mp4. Esses caracteres fazem parte do nome. Envie o corpo da requisição como JSON UTF-8 e o nome passa sem alterações.
  • A voz não está presa ao avatar. Qualquer uma das 102 vozes pode ler para qualquer um dos 1,248 looks. Escolha uma voz que combine com a pessoa na tela; nossos testes do dia do lançamento juntaram Bryan Tech Expert com Andrew e Abigail Office Front com Jessica Anne Bogart.

voice só se aplica quando você envia text. Se você enviar audio_url, o avatar fala a sua gravação e voice não é usado.

Dirija 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: "Escreva a ação ao lado das palavras. O Avatar 6 a executa no momento exato." O exemplo dela: "Farmacêutico simpático. Em 'Hello', faça um joinha. Em 'the counter on the left', aponte para o lado com o dedo 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:

  • Cite as palavras exatas do text em que cada ação deve acontecer, para que a deixa não fique ambígua.
  • Descreva primeiro um papel ou clima ("Friendly product expert") e depois as deixas.
  • Deixe o prompt de fora quando não tiver 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 seu roteiro" sozinho.

Escolha a proporção de acordo com 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.

Destinoaspect_ratio
Site, YouTube, aula em LMS16:9 (padrão)
Shorts, Reels, TikTok, stories9:16
Post quadrado no feed, card no app1:1
Post vertical no feed4:5
Post horizontal no feed5:4

resolution é separado: 1080p ou 2K em qualquer proporção. O 2K custa mais por segundo, então gere os rascunhos em 1080p.

Quanto o vídeo vai durar e quanto custa

Com texto, o vídeo dura o tempo que o avatar leva para lê-lo, até 1,000 caracteres. Você paga pela duração do vídeo final, arredondada para cima, para segundos inteiros. Os créditos são reservados no envio e acertados pelos segundos reais quando a tarefa termina.

Nossos testes do dia do lançamento na API de produção, 19 de novembro de 2026 (16:9, 1080p):

ModeloAvatar / vozRoteiroSaídaCusto nos preços atuaisTempo real
heygen-avatar-6-turboAbigail Office Front / Jessica Anne Bogart27 palavras10.16 s110 créditos ($0.55)Cerca de 2.4 min
heygen-avatar-6Bryan Tech Expert / Andrew21 palavras6.88 s140 créditos ($0.70)Cerca de 2 min

Isso dá cerca de 2.7 e 3.1 palavras por segundo nessas duas execuções, útil para um orçamento aproximado, mas não uma garantia, já que o ritmo varia com a voz e o roteiro. 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). Veja Preço da HeyGen Avatar 6 API para mais detalhes.

Como as tarefas de texto mantêm uma reserva enquanto rodam, disparar muitas de uma vez pode retornar HTTP 200 com code 402 no corpo (insufficient_credits_error). No nosso teste, uma terceira requisição foi recusada com: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Coloque os jobs de texto em fila, ou mantenha um saldo que cubra as reservas em andamento. Use o Turbo enquanto itera; a comparação Avatar 6 vs Turbo mostra quando trocar.

Perguntas frequentes

A HeyGen Avatar 6 API consegue transformar texto em um vídeo com avatar falante?

Sim. No modo avatar público, envie avatar, até 1,000 caracteres de text e, opcionalmente, voice. Não é preciso arquivo de áudio.

Onde fica a lista de avatares e vozes da HeyGen Avatar 6 API?

Na página Avatars and Voices da documentação da PoYo, e como catálogo JSON para download com as chaves avatars, avatars_by_person e voices.

Qual é a voz padrão da HeyGen Avatar 6 API?

Warm Pro Narrator, usada quando voice não é enviado.

Posso usar minha própria foto com texto em vez de um avatar de banco?

Não. text só funciona no modo avatar público. Para a sua própria foto, use o modo foto com image_urls e um audio_url; se precisar, gere o áudio antes com um modelo TTS.

Quais proporções o text to avatar do HeyGen Avatar 6 suporta?

16:9, 9:16, 1:1, 4:5 e 5:4, em 1080p ou 2K.

Como é cobrada uma requisição de texto da HeyGen Avatar 6 API?

Pela duração do vídeo final, arredondada para cima, para segundos inteiros, na tarifa por segundo do modelo. Os créditos são reservados no envio e acertados quando a tarefa termina.

Share: