Blogue

Guia de uso

Gerar vídeos curtos com heygen-avatar-iv via API HiAPI: guia para desenvolvedores

Entradas de apresentador digital e áudio, ritmo do roteiro, proporção e duração, além de geração em lote — com requisições HiAPI executáveis

Nov 18, 2026
Imagem de capa: sobre um fundo marrom-escuro, largas faixas trançadas em tons de aveia e latão se entrelaçam formando um padrão de cesto plano.
Nesta página

Por que escolher heygen-avatar-iv para vídeos curtos

Vídeos curtos tornaram-se o canal de distribuição padrão para lançamentos de produtos, anúncios de atualização de versão, explicações de documentação e clipes para redes sociais. Para a maioria das equipes de engenharia, o gargalo não está na edição — está em produzir de forma consistente material de narração com pessoa em cena, sem agendar estúdio nem enviar material de um lado para o outro com um apresentador real.

É exatamente essa lacuna que a geração de vídeo com apresentador digital preenche. Você fornece a aparência visual e a fonte de áudio/voz, e o modelo retorna o clipe renderizado do apresentador digital lendo o roteiro. heygen-avatar-iv é o endpoint do catálogo HiAPI voltado para esse fluxo de trabalho: clipes curtos com prioridade para vertical, com o apresentador olhando diretamente para a câmera e falando.

O modelo é adequado para os seguintes cenários:

  • Você precisa produzir em escala. Dez versões localizadas do mesmo anúncio, ou um clipe diário a cada lançamento — é um ciclo, não uma gravação única.
  • O conteúdo é guiado por roteiro. Se a mensagem está no texto, um apresentador digital basta.
  • Você quer reprodutibilidade. Uma requisição é um arquivo, que pode ser comparado por diff, versionado e reexecutado — diferente de uma sessão gravada.
  • Você já chama APIs. Uma chamada HTTP integra-se ao pipeline existente, sem introduzir uma nova ferramenta com UI própria.

Ele não é adequado para performances improvisadas com gestos amplos, nem para cenários em que a presença física de uma pessoa específica é o atrativo. Trate heygen-avatar-iv como um renderizador: com as mesmas entradas, deve-se obter o mesmo tipo de saída — e é justamente isso que o torna scriptável.

O restante deste guia vai da chamada de teste única até o loop em lote, com curl e Python executáveis que você pode adaptar. Detalhes do modelo e parâmetros estão na página do modelo heygen-avatar-iv.

Roteiro e aparência do apresentador digital fundem-se em um ponto de encontro semelhante a um tear, formando um único quadro de vídeo curto vertical.

A estrutura de uma requisição heygen-avatar-iv

Antes de escrever o código de geração, modele a requisição como dois grupos de entrada independentes. Quase todos os bugs iniciais vêm de confundir os dois.

Primeiro grupo: aparência visual

É quem aparece — a escolha do apresentador digital que determina o rosto, o enquadramento e a aparência geral do apresentador. Mantenha esse grupo estável ao longo de uma campanha. Se você vai produzir cinco clipes sobre o mesmo produto, eles devem compartilhar o mesmo bloco de aparência, para que a série pareça ter o mesmo apresentador.

Segundo grupo: áudio e voz

É o que se diz e como se diz. Dependendo da requisição, a fonte de áudio pode ser uma escolha de timbre que lê o texto do seu roteiro, ou uma faixa de áudio fornecida. Esse grupo muda a cada clipe: novo roteiro, novo ritmo e, às vezes, um novo timbre para localização.

Como eles mapeiam para a chamada

A requisição HiAPI envia os dois grupos no mesmo payload para o endpoint de geração. Conceitualmente:

request
├── bloco de apresentador / identidade   → permanece estável em uma série
└── bloco de áudio / voz                 → muda a cada clipe
        └── texto do roteiro ou fonte de áudio

Essa separação gera duas regras práticas:

  1. Parametrize o grupo de áudio e congele o grupo de aparência. No código, mantenha a aparência como uma constante no nível do módulo e passe roteiro e timbre como parâmetros de função. Isso garante estruturalmente a consistência visual de uma série.
  2. Ao depurar, altere apenas um grupo por vez. Se o clipe parece errado, substitua só a aparência; se o áudio parece errado, substitua só o grupo de áudio. Depurar duas variáveis em chamadas de renderização pagas sai caro.

Defina também desde cedo se o seu grupo de áudio é orientado por texto ou por faixa de áudio, pois essa escolha determina o ritmo da próxima seção — uma faixa fornecida define a temporalidade, enquanto uma voz gerada segue o seu roteiro.

Os nomes exatos dos campos, os valores aceitos e os padrões estão listados na página do modelo; leia-os e fixe-os em um objeto de configuração, em vez de espalhar literais pelo código.

Dois grupos de entrada — aparência visual e áudio/voz — entrelaçam-se em uma única chamada de geração.

Faça sua primeira chamada com curl

Comece com um clipe curto. O objetivo desta chamada não é a qualidade da saída — é validar de ponta a ponta as credenciais, o formato do payload e o caminho de download, antes de qualquer automação.

Defina a chave como variável de ambiente, para que nunca entre em texto claro no histórico do shell:

export HIAPI_API_KEY="your_key_here"

Em seguida, envie uma requisição mínima. Substitua pela sua escolha de apresentador digital e por um roteiro curto de uma linha:

curl -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "avatar": "<avatar_identifier>",
      "script": "Este é um teste de trinta segundos do pipeline de apresentador digital. Se você consegue ler esta frase na tela, o formato da requisição está correto.",
      "voice": "<voice_identifier>",
      "aspect_ratio": "9:16",
      "duration": 30
    }
  }'

Verifique em ordem:

  • Autenticação. Um erro de credencial aqui significa parar — nada a jusante importa.
  • Validação do payload. Erros de schema indicam o campo problemático. Corrija um campo por vez.
  • Aceitação da tarefa. Uma chamada bem-sucedida retorna uma referência de job ou task, não necessariamente o arquivo final. A geração é assíncrona; registre esse identificador.
  • Obtenção do resultado. Conforme o contrato de resposta na página do modelo, use a referência retornada para consultar o status ou obter a URL do resultado.
  • Reprodução. Baixe o clipe e assista. Confirme que enquadramento, orientação e conteúdo falado correspondem ao roteiro.

Guarde este comando curl em um arquivo de rascunho, preenchido com seus identificadores reais. Ele será seu experimento de controle: quando a versão em Python falhar, execute o curl novamente para provar se o problema está no seu código ou na entrada.

Cada faixa trançada marca uma etapa — montar, enviar, receber, baixar — com um laço de retorno para uma chamada de nova tentativa.

Passar para Python para geração repetível

Depois que a chamada curl funcionar, encapsule-a em uma função. O ponto não é abstrair por abstrair — é tornar cada parâmetro explícito, para que o clipe seja completamente descrito pelo ponto de chamada.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/generate"
API_KEY = os.environ["HIAPI_API_KEY"]

# Mantenha estável em uma série
AVATAR = "<avatar_identifier>"


def generate_clip(script: str, voice: str, aspect_ratio: str = "9:16",
                  duration: int = 30) -> dict:
    payload = {
        "model": "heygen-avatar-iv",
        "input": {
            "avatar": AVATAR,
            "script": script,
            "voice": voice,
            "aspect_ratio": aspect_ratio,
            "duration": duration,
        },
    }
    resp = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    job = generate_clip(
        script="Este é um teste de trinta segundos do pipeline de apresentador digital.",
        voice="<voice_identifier>",
    )
    print(job)

Pontos de design que valem a pena adotar:

  • Os padrões refletem seu clipe mais comum. Se a maioria das saídas são clipes curtos verticais, torne-os padrão e sobrescreva raramente.
  • A aparência fica no nível do módulo. A escolha do apresentador existe em um único lugar; trocar a marca exige alterar uma linha.
  • Retorne a resposta completa. Não extraia a URL imediatamente e descarte o objeto job; você vai precisar desse identificador para logs e novas tentativas.
  • Lance exceção em erros HTTP. Falhas silenciosas em um loop em lote são piores do que um crash.
  • Trate explicitamente a etapa assíncrona. Adicione um pequeno auxiliar poll(job_id) em vez de dar sleep dentro da função de geração.

Fixe a lógica de tratamento da resposta ao contrato documentado na página do modelo — os nomes de campo de status do job e de obtenção do resultado são a parte mais propensa a divergir das suas suposições.

Escrever o roteiro de narração e controlar o ritmo

Vídeos com apresentador digital são áudio-primeiro. Um roteiro que parece bom no papel costuma ficar longo demais quando lido em voz alta, e cortar depois da geração significa pagar renderização por texto que será descartado.

Escreva pelo comprimento e depois corte

Estime a duração antes de chamar a API. Um ritmo confortável fica em torno de 130–160 palavras por minuto; para conteúdo técnico que o público precisa acompanhar, use a faixa inferior. Assim, um clipe de 30 segundos precisa de cerca de 65–80 palavras, e um de 60 segundos, cerca de 130–160. Escreva com esse orçamento, leia em voz alta com um cronômetro e então corte. Se precisar cortar, remova frases inteiras em vez de palavras — cortes em nível de frase preservam o ritmo.

Escreva para o ouvido

  • Frases curtas. Uma ideia por frase. É nas orações subordinadas que a compreensão cai.
  • Não dependa de referências puramente visuais. “Como mostrado abaixo” não funciona sem um slide.
  • Coloque o ponto principal no início. O público de vídeos curtos decide nos primeiros segundos; coloque a tese na primeira frase.
  • Escreva por extenso o que o TTS leria errado. Abreviações, strings de versão e nomes de produtos com capitalização incomum devem ser escritos como devem ser pronunciados.

Controle o ritmo pela linha do tempo

Distribua o roteiro em blocos de tempo conforme a duração alvo:

0–5s    gancho: tese ou problema
5–20s   corpo: o mecanismo, em duas ou três frases
20–28s  detalhe: um número ou exemplo que vale reter
28–30s  fechamento: uma única chamada para ação

Essa estrutura em blocos também funciona como artefato de revisão — os revisores podem rejeitar um bloco sem que você precise renderizar nada novamente. Mantenha o roteiro de cada clipe em um arquivo separado, versionado junto com o código que o renderiza, e o loop em lote da próxima seção torna-se totalmente reproduzível.

Definir proporção, duração e saída

Antes da primeira renderização, decida a orientação e o comprimento com base na plataforma de destino. Renderizar novamente um clipe finalizado em uma segunda orientação é desperdício, e reeditar um clipe longo demais significa regenerar o áudio também.

Proporção

  • 9:16 vertical — o padrão dos feeds de vídeos curtos: shorts, reels, stories e posicionamentos mobile-first. Projete o enquadramento para isso primeiro; quando possível, recorte as demais proporções a partir do master vertical.
  • 16:9 horizontal — players incorporados, landing pages, vídeos de documentação e cenários de apresentação.
  • 1:1 quadrado — posicionamentos de feed que preferem formato quadrado. Bom como versão derivada secundária.

Se a sua campanha precisa das duas orientações, trate-as como duas tarefas distintas, com roteiros diferentes, em vez de renderizar o mesmo roteiro duas vezes — uma fala que funciona em 30 segundos verticais frequentemente deixa um silêncio incômodo em um corte quadrado mais curto.

Duração

Defina a duração com base no orçamento de roteiro da seção anterior, e não o contrário. Passe uma duração que corresponda ao comprimento real da narração; clipes preenchidos com silêncio ou cortados no meio da frase parecem quebrados. Mantenha as metas de cada plataforma em uma configuração, para facilitar ajustes:

TARGETS = {
    "vertical": {"aspect_ratio": "9:16", "duration": 30},
    "horizontal": {"aspect_ratio": "16:9", "duration": 45},
}

Saída

Baixe e armazene você mesmo os clipes finalizados, em vez de depender de URLs de resultado temporárias. Uma convenção simples — {clip_id}-{orientation}-{version}.mp4 — mantém as versões derivadas rastreáveis e deixa claros os arquivos obsoletos. Registre o identificador do job junto com o arquivo, para que qualquer clipe possa ser rastreado até a sua requisição exata.

A cobrança é pelas gerações que você solicita — por duração e quantidade de clipes —, portanto enxugar o roteiro antes de renderizar é a otimização mais barata de que você dispõe. Consulte o painel de preços para as tarifas atuais.

Gerar vários clipes em lote

Com uma função funcional, o processamento em lote é apenas um loop sobre uma lista de tarefas. O ponto-chave é que cada tarefa seja a descrição completa de um clipe.

JOBS = [
    {"id": "launch-vertical", "script_file": "scripts/launch.txt",
     "voice": "<voice_a>", "aspect_ratio": "9:16", "duration": 30},
    {"id": "launch-square", "script_file": "scripts/launch_sq.txt",
     "voice": "<voice_a>", "aspect_ratio": "1:1", "duration": 20},
    {"id": "changelog-vertical", "script_file": "scripts/changelog.txt",
     "voice": "<voice_b>", "aspect_ratio": "9:16", "duration": 30},
]

results = []
for job in JOBS:
    with open(job["script_file"]) as f:
        script = f.read().strip()
    print(f"submitting {job['id']} ({len(script.split())} words)")
    resp = generate_clip(
        script=script,
        voice=job["voice"],
        aspect_ratio=job["aspect_ratio"],
        duration=job["duration"],
    )
    results.append({"id": job["id"], "job": resp})

Padrões que valem a pena adotar:

  • Roteiros como arquivos, não literais de string. Eles podem ser revisados, comparados por diff e reutilizados entre orientações.
  • Log de contagem de palavras. Imprimir a contagem de palavras de cada tarefa detecta, antes de gastar com renderização, roteiros que vão ultrapassar a duração.
  • IDs de job estáveis. Use-os nos nomes dos arquivos de saída e nos logs, para que clipes com falha em vinte execuções possam ser identificados.
  • Falhas internas, relatório depois. Envolva cada envio em try/except, colete as falhas e continue — um roteiro ruim não deve abortar o lote inteiro.
  • Respeite limites de taxa e concorrência. Comece em série; só adicione um pool de threads limitado depois que a execução serial estiver estável.
  • Persista a lista de resultados. Grave os IDs de job em um arquivo JSON, para que lotes parcialmente concluídos possam ser retomados em vez de reiniciados.

Pontos de falha comuns e verificações

Estes são os problemas mais frequentes. Cada um tem uma verificação de isolamento barata.

Erro de formato de entrada

Erros de schema são a falha inicial mais comum. Verificação: execute o comando curl original com os mesmos identificadores. Se o curl funcionar e o Python falhar, o bug está na sua serialização — geralmente um tipo incompatível, como uma string passada onde se espera duração inteira, ou uma quebra de linha extra no final do arquivo de roteiro.

Áudio não corresponde ao roteiro

Se a voz diz algo diferente do pretendido ou o clipe fica sem som, o grupo de áudio está errado. Verificação: confirme se a requisição é orientada por texto ou por faixa de áudio, e confirme que você passou o campo correspondente. Fornecer ao mesmo tempo um campo de faixa de áudio e um campo de roteiro é o conflito silencioso típico — decida qual tem prioridade e remova o outro.

Orientação errada ou faixas pretas

O clipe volta com faixas pretas ou com um enquadramento inesperado. Verificação: confirme que aspect_ratio realmente chegou ao payload — um valor padrão na função pode sobrescrever silenciosamente o que você acha que passou. Registre o payload montado antes de enviar.

Duração incompatível

O clipe é cortado no meio da frase ou sobra no final. Verificação: compare a contagem de palavras do roteiro com o orçamento de duração. Corrija o roteiro, não a duração, a menos que a meta em si esteja errada.

Deriva de aparência em uma série

Clipes da mesma campanha parecem apresentadores diferentes. Verificação: confirme que o identificador do apresentador digital vem de uma única constante, e não de uma configuração por tarefa.

Saída truncada ou ausente

O job tem sucesso, mas o arquivo está incompleto. Verificação: confirme que o job atingiu um estado terminal de sucesso antes de baixar, e confirme que você seguiu o contrato de obtenção na página do modelo, em vez de adivinhar URLs.

Regra geral: um clipe de teste, uma requisição curl, uma variável por vez. Faça primeiro uma renderização vertical curta via modelo heygen-avatar-iv, valide de ponta a ponta e só então deixe o loop escalar.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API