Como usar a API do HeyGen Avatar IV? Faça uma foto falar em 5 minutos

TL;DR

• O que é: avatar de foto da HeyGen. Uma foto de rosto mais um roteiro (ou um áudio) geram um MP4 em que a pessoa da foto fala. Já está disponível no HiAPI: abra a página do modelo, envie a foto e gere.
• Quanto custa: cobrança por segundo de vídeo, US$ 0,15 por segundo, mesmo preço para 720p e 1080p, US$ 1,50 por um vídeo de 10 segundos.
• Como chamar a API: POST https://api.hiapi.ai/v1/tasks, com model igual a heygen-avatar-iv, envie o link da foto e o roteiro, receba o taskId e consulte; em 5 minutos você roda o primeiro.

Veja primeiro um resultado pronto. O trecho de apresentação horizontal de 9 segundos abaixo usa uma foto de meio corpo de suéter mais uma fala em inglês:

1080p / 16:9, 9 segundos, voz Cute Chloe - Friendly. O suéter, o cabelo e o ambiente da foto são preservados, e a sincronia labial, o piscar e a leve inclinação da cabeça acompanham a fala.

Texto original da fala:

Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.

Gerar com esta fala → A fala já está preenchida; envie sua própria foto e gere.

Para quem serve o HeyGen Avatar IV?

Use quando você tem uma foto e quer que "essa pessoa" apareça falando. Usos comuns:

• Apresentação de produtos e recomendações: a mesma foto com falas diferentes, gerando vídeos curtos com vários argumentos de venda em lote.
• Cursos e treinamentos: o professor grava uma foto uma vez e cada aula precisa apenas do roteiro.
• Comunicados internos e vídeos de atendimento: a imagem de consultores, médicos e gerentes fica fixa, e o conteúdo é atualizado a qualquer momento.
• Ilustrações e personagens 3D: desde que haja um rosto nítido, personagens de desenho também podem falar.

Se você não quer usar a própria imagem, prefere escolher entre avatares predefinidos, ou precisa de fundo transparente, legendas e 4K, escolha o HeyGen Avatar V, com o mesmo preço.

Teste primeiro na página do modelo

Antes de escrever código, gere um vídeo na web para ver como sua foto fica:

1. Clique em "Gerar com esta fala" acima; a fala será preenchida automaticamente.
2. Envie uma foto de uma só pessoa, de frente e com iluminação uniforme.
3. Escolha 1080p, 16:9; a voz pode ficar sem seleção, o padrão é Warm Pro Narrator.
4. Clique em gerar, visualize online quando terminar e baixe se gostar.

Um vídeo de 10 segundos custa US$ 1,50; com US$ 10 você gera cerca de 66 segundos de vídeo, o suficiente para comparar algumas fotos e vozes.

Três coisas para preparar antes de chamar a API

1. API Key: crie no console, no formato sk-..., e coloque no cabeçalho Authorization: Bearer.
2. Link HTTPS público da foto: o mais estável é uma foto de uma só pessoa, de frente, com traços do rosto sem obstrução, iluminação uniforme e boca naturalmente fechada. A API lê a foto pelo link, então envie a imagem para seu próprio armazenamento ou CDN primeiro.
3. Fala ou áudio, escolha um: se enviar a fala, ela será lida pela voz escolhida; se enviar áudio (audio_url), a sincronia labial seguirá sua gravação.

Requisição mínima: versão cURL

O link de foto abaixo pode ser usado diretamente; basta trocar pela sua Key para rodar:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
      "prompt": "Hi, I'\''m Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
      "voice": "Cute Chloe - Friendly",
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }
  }'

O ID da tarefa retornada fica em data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Não é preciso enviar a duração: com fala, ela é definida pelo tamanho do texto e pela velocidade da voz; com áudio, é igual à duração do áudio.

Consultar o resultado

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Quando data.status virar success, procure em data.output o item cujo type é video; o url é o MP4:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-...",
    "status": "success",
    "model": "heygen-avatar-iv",
    "output": [
      {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4"}
    ]
  },
  "message": "success"
}

Exemplo completo em Python: criar, consultar e baixar

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "heygen-avatar-iv",
    "input": {
        "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
        "prompt": "Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
        "voice": "Cute Chloe - Friendly",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(8)

if data["status"] == "success":
    video_url = next(o["url"] for o in data["output"] if o["type"] == "video")
    with open("avatar-iv.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    print("saved avatar-iv.mp4")
else:
    print(data.get("error"))

Visão geral dos parâmetros

Parâmetro	Obrigatório	Valor padrão	Descrição
image_url	Sim	—	Link HTTPS público da foto de rosto; precisa de um rosto nítido
prompt	Escolha um	—	Fala, com no máximo 5000 caracteres, em chinês ou inglês
voice	Não	Warm Pro Narrator	102 vozes predefinidas, só tem efeito quando se usa a fala
audio_url	Escolha um	—	Áudio que guia a sincronia labial, com no máximo 600 segundos
resolution	Não	720p	720p ou 1080p, mesmo preço
aspect_ratio	Não	16:9	16:9, 9:16, 4:5, 5:4, 1:1, auto (mantém a proporção da foto)
background	Não	Branco	{"type": "color" ou "image", "value": ...}, preenche as áreas vazias do enquadramento
callback	Não	—	{"url": "...", "when": "final"}, envia o objeto da tarefa no estado final

A lista completa de vozes está na documentação em chinês.

As duas formas de conduzir e como usar o fundo

Conduzido por fala: envie prompt e voice, ideal para trocar conteúdo em lote. O vídeo vertical abaixo já tem a foto em 9:16, então o enquadramento de saída preenche tudo:

1080p / 9:16, 8 segundos, voz Andrew.

I've been using these new earbuds for a week. The noise canceling is super quiet, and the battery lasts all day. Follow me for more.

Gerar com esta fala → A fala já está preenchida; envie sua foto vertical e escolha 9:16 para gerar.

Conduzido por áudio: se você já gravou a narração ou quer usar sua própria voz, troque prompt e voice por audio_url; a sincronia labial e as pausas seguirão a gravação.

Fundo: quando o enquadramento de saída for diferente da proporção da foto, sobram áreas vazias; preencha com background. Para cor sólida, envie {"type": "color", "value": "#F5EFE6"}; para imagem, {"type": "image", "value": "https://..."}. O vídeo abaixo coloca a foto horizontal do professor em tela vertical, preenchendo em cima e embaixo com uma imagem de quadro-negro:

1080p / 9:16, 11 segundos, voz Professor Dean, background com uma imagem de quadro-negro.

Hello everyone. Today we'll explain the Pythagorean theorem in five minutes. In a right triangle, the squares of the two legs add up to the square of the hypotenuse.

Gerar com esta fala → A fala já está preenchida; envie sua foto e gere.

3 cuidados antes de publicar

1. Use callback no servidor. Adicione "callback": {"url": "https://yourapp.com/webhook", "when": "final"} na requisição; ao fim da tarefa o resultado é enviado automaticamente, sem polling.
2. Não repita o POST depois de receber o taskId. Cada POST /v1/tasks cria uma nova tarefa e cobra separadamente. Em caso de timeout de rede, verifique primeiro se você guardou o taskId; se guardou, continue consultando ou aguarde o callback.
3. Baixe imediatamente após o sucesso. O link de saída expira; assim que receber o resultado, salve o MP4 no seu próprio armazenamento.

Como é a cobrança?

US$ 0,15 por segundo, calculado pelos segundos reais do vídeo gerado; a resolução não afeta o preço, então use 1080p direto. Ao criar a tarefa, é feito um pré-débito pela duração estimada; ao concluir, ajusta-se para mais ou para menos pelos segundos reais, e tarefas com falha são reembolsadas integralmente.

Duração do vídeo	Custo
5 segundos	US$ 0,75
10 segundos	US$ 1,50
30 segundos	US$ 4,50
60 segundos	US$ 9,00

O custo depende só dos segundos; para economizar, escreva falas mais curtas. Por mês, 300 vídeos de 10 segundos custam cerca de US$ 450, e 20 aulas de 60 segundos, cerca de US$ 180. A tabela completa está na página de preços.

O vídeo de 9 segundos da Lin no início custou US$ 1,35. Gerar com a mesma fala → A fala já está preenchida; envie sua foto e calcule quantos segundos o seu vídeo terá.

Perguntas frequentes

Posso usar falas em chinês? Sim. prompt aceita chinês e inglês, com no máximo 5000 caracteres.

Posso usar minha própria voz? Sim. Envie a gravação em audio_url, com no máximo 600 segundos; a sincronia labial seguirá sua gravação.

Que tipo de foto dá o melhor resultado? Uma foto de uma só pessoa, de frente, com traços do rosto sem obstrução, iluminação uniforme e boca naturalmente fechada. Ilustrações e personagens 3D também funcionam, desde que tenham um rosto nítido. Para perfis laterais, máscaras, fotos com várias pessoas ou rostos muito pequenos, tente outra foto; tarefas com falha de reconhecimento são reembolsadas integralmente.

Minha foto é horizontal; como gerar um vídeo vertical? Defina aspect_ratio como 9:16 e preencha as áreas vazias em cima e embaixo com background, como no vídeo do quadro-negro acima.

Quanto tempo leva um vídeo? A geração é assíncrona; quanto mais longa a fala e maior a resolução, mais demora. Use callback no servidor para receber o resultado automaticamente ao final.

Links relacionados ao HeyGen Avatar IV

• Página do modelo HeyGen Avatar IV: envie uma foto e gere online
• Documentação em chinês do HeyGen Avatar IV: todos os parâmetros e as 102 vozes
• Página do modelo HeyGen Avatar V: 497 avatares predefinidos, com suporte a fundo transparente e legendas
• Página de preços do HiAPI: preços por segundo e por imagem de todos os modelos

Experimente agora: pegue uma foto sua de frente, gere com esta fala da Lin →; a fala já está preenchida, envie a foto, escolha 1080p e 16:9, e um vídeo de cerca de 9 segundos custa US$ 1,35.