Transforme roteiros em vídeos curtos de locução com heygen-avatar-v e a API da hiapi

Conteúdo de locução para vídeos curtos — atualizações rápidas de fundadores, demonstrações de produto, anúncios de locução no estilo UGC — normalmente exige agendar uma pessoa real, preparar o microfone e fazer a edição mais uma vez. O heygen-avatar-v na hiapi reduz tudo isso a uma única chamada de API: envie um roteiro ou um arquivo de áudio e receba de volta um vídeo de avatar com sincronia labial, movimentos ociosos naturais e uma faixa de legendas, pronto para ir direto ao feed de vídeos curtos. Este artigo percorre o fluxo real de /v1/tasks, um clipe gerado de verdade, as restrições que vale conhecer antes de montar um pipeline em torno do modelo e os preços obtidos em tempo real do /api/pricing da hiapi. Se o que você busca são dicas de estilo do próprio avatar em nível de prompt, o artigo heygen-avatar-v prompt recipes já cobre isso — aqui o assunto é como encaixar o modelo num pipeline reutilizável de vídeos curtos.

O que o heygen-avatar-v realmente entrega

O heygen-avatar-v é um modelo de vídeo com pessoa digital, não um gerador de vídeo a partir de texto no sentido de Sora/Kling — ele usa um roteiro de texto ou um arquivo de áudio enviado para animar um avatar HeyGen predefinido e retorna um vídeo em que a boca do avatar sincroniza com a fala, com movimentos contínuos e sutis (piscadas, leve movimento de cabeça, oscilação dos ombros) para não parecer um retrato estático. Esse comportamento de "estar em movimento mesmo parado" é exatamente a linha divisória entre um clipe curto utilizável e uma foto falante que o público identifica como falsa na hora.

O modelo é movido por duas entradas mutuamente exclusivas — você envia uma ou outra:

• prompt — roteiro em texto; o TTS da hiapi narra e conduz a sincronia labial
• audio_url — URL pública de uma faixa de voz pré-gravada (sua própria narração, uma voz clonada, o que for), que conduz a sincronia labial

Não existe campo duration. A duração do clipe depende inteiramente de quanto tempo o roteiro ou o áudio leva para tocar — uma linha de 40 palavras gera um clipe mais curto do que uma de 200 palavras. Isso importa para o planejamento de custos, como veremos adiante.

Campos opcionais refinam o estilo: avatar (escolhido na biblioteca de predefinições do HeyGen), voice (usado apenas com prompt; ignorado com audio_url), aspect_ratio (9:16 para Reels/TikTok/Shorts, 16:9, 1:1), resolution, background (cor sólida ou cenário — mas veja a armadilha abaixo), caption (gera uma faixa de legendas) e output_format (mp4 ou webm, este último com fundo transparente, prático para compor sobre o seu próprio cenário).

Clipe real: roteiro na entrada, vídeo de avatar com legendas na saída

Abaixo está uma saída real do heygen-avatar-v — o avatar narra uma linha de roteiro, com movimento ocioso visível entre as frases e uma faixa de legendas sincronizada:

Note o que não acontece: o avatar não congela entre as frases, e as legendas acompanham a fala em vez de serem coladas depois. Essa combinação — movimento contínuo mais legendas sincronizadas — é o motivo inteiro de escolher este modelo em vez de narrar uma imagem estática de avatar no editor.

Armadilhas: dois problemas que mordem a primeira versão do pipeline

caption entrega um arquivo anexo de legendas, não legendas embutidas no vídeo. Definir caption: true retorna um arquivo .srt sincronizado além do vídeo de saída — ele não grava o texto nos quadros do vídeo. Se você quer o texto de legenda na tela (a aparência da maioria das plataformas de vídeos curtos), precisa fazer uma etapa separada de gravação usando esse arquivo .srt (ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4, ou o recurso nativo de importação de legendas da sua plataforma). Trate a "legenda" da API como dado, não como imagem renderizada.

background só funciona com avatares em estilo ilustração, não com os fotorrealistas. A biblioteca de avatares do HeyGen mistura avatares fotorrealistas com avatares em estilo ilustração/animação. O parâmetro background consegue substituir com sucesso o cenário atrás de um avatar em estilo ilustração, mas avatares fotorrealistas mantêm o fundo original da gravação, não importa o que você envie — o modelo não os recorta. Se o seu pipeline pressupõe que todo avatar aceita sobrescrita de fundo, teste primeiro o ID de avatar específico que pretende usar antes de assumir que ele vai compor como esperado. Para avatares fotorrealistas que você quer colocar sobre o seu próprio fundo, a abordagem confiável é output_format: webm (transparente).

Custos: cobrança por segundo de saída, não por chamada

Segundo o /api/pricing em tempo real da hiapi, o heygen-avatar-v custa US$ 0,15 por segundo de saída — tarifa única, independente de resolução ou proporção. Como não há entrada de duração, seu custo real depende de quanto tempo o roteiro ou o áudio leva para tocar:

Tamanho do roteiro (aprox.)	Duração da saída	Custo
Frase de gancho curta	Cerca de 5 segundos	US$ 0,75
Um bloco de vídeo curto	Cerca de 10 segundos	US$ 1,50
Argumentação de várias frases	Cerca de 20 segundos	US$ 3,00
Anúncio completo de locução de 30 segundos	Cerca de 30 segundos	US$ 4,50

Como o custo escala com a duração da fala e não com um parâmetro definido previamente, a prática útil é cronometrar o roteiro antes de enviar a tarefa (lendo em voz alta ou rodando um estimador de duração de TTS), em vez de descobrir a fatura só depois que o clipe terminar de renderizar.

O pipeline: enviar, consultar e baixar antes que expire

O heygen-avatar-v roda no endpoint assíncrono /v1/tasks da hiapi — como todos os modelos baseados em tarefas da plataforma, no formato "criar primeiro, consultar depois". Um detalhe específico desse fluxo: entre handling e success a tarefa passa por uma etapa archiving, enquanto a plataforma finaliza o vídeo e o arquivo anexo de legendas, então não trate archiving como estado terminal no seu loop de consulta.

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

Duas observações operacionais que não podem ser ignoradas em escala:

• Baixe imediatamente. Como toda saída de tarefa da hiapi, a URL retornada traz um expireAt e não serve como link de longo prazo — assim que a tarefa der certo, puxe os bytes (vídeo e .srt) para o seu próprio armazenamento.
• Não envie um payload mínimo só para "verificar o schema". Como estritamente apenas prompt ou audio_url são obrigatórios, os demais campos usam valores padrão silenciosamente, e um payload com apenas {"prompt": "test"} não retorna 400 — ele dispara uma renderização real e cobrável. Valide os nomes dos campos contra a documentação ou usando um valor propositalmente inválido para obter uma resposta 4xx, em vez de omitir campos contra o endpoint real.

Perguntas frequentes

Posso usar minha própria voz em vez do TTS da hiapi? Sim — envie audio_url em vez de prompt, com a URL pública da sua gravação, e o avatar fará a sincronia labial com essa faixa em vez de sintetizar a fala a partir do texto.

A opção caption grava as legendas no vídeo? Não. caption: true retorna um arquivo .srt separado, sincronizado com o áudio do vídeo de saída. Se você quer o texto de legenda na tela, grave-o você mesmo como etapa de pós-processamento.

Consigo controlar a duração do clipe? Não diretamente — não há parâmetro duration. O comprimento da saída é determinado pelo tamanho do roteiro (ao usar prompt) ou pela duração do arquivo de áudio (ao usar audio_url).

Por que o fundo que especifiquei não aparece? background só funciona com avatares em estilo ilustração/animação da biblioteca HeyGen. Avatares fotorrealistas mantêm o fundo original da gravação; nesse caso, use output_format: webm para obter saída transparente e faça a composição você mesmo.

Quais resoluções e proporções são suportadas? Até 4K, com opções de proporção 9:16, 16:9 e 1:1 — cobrindo do feed vertical de vídeos curtos a veiculações widescreen e quadradas.

Conclusão

Montar um pipeline de avatares para vídeos curtos na hiapi se resume a alguns fatos concretos, não a adivinhação: o custo é US$ 0,15 por segundo de saída (então cronometre o roteiro antes de enviar, não depois), a saída de legendas é um arquivo anexo .srt que você mesmo precisa gravar, a substituição de fundo só funciona com avatares em estilo ilustração, e seu loop de consulta precisa tratar archiving como não terminal, assim como handling. Antes de fixar um orçamento no código, confira os números atuais na página de preços da hiapi e a referência completa de campos na página do modelo. Se você está pronto para começar, obtenha uma API key no dashboard e comece com um roteiro curto — uma saída de 5 segundos já basta para confirmar que seu avatar, proporção e tratamento de legendas funcionam, antes de escalar para lotes inteiros.