how-tos

HeyGen Avatar 6 API text to avatar: vídeos com apresentador a partir de um guião, sem ficheiro 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 guião

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

O 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 em ambos)
default_voiceWarm Pro Narrator
avatarsTodos os 1,248 nomes de looks, numa 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 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:

QueresProcura nomes comoExemplos
Apresentador virado para a câmaraFrontAbigail 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, 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 Hope e Hope (com espaço final) são duas vozes diferentes. Archer , Cassidy , Adam Stone , Spuds Oxley e Andrew Rizz també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 😊 ou Brenda - 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 Expert com Andrew e Abigail Office Front com Jessica 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 text em 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 prompt quando 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.

Destinoaspect_ratio
Site, YouTube, aula num LMS16:9 (predefinido)
Shorts, Reels, TikTok, stories9:16
Publicação quadrada no feed, cartão na app1:1
Publicação vertical no feed4:5
Publicação horizontal no feed5: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):

ModeloAvatar / vozGuiãoSaídaCusto aos 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

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.

Share: