Como usar a API do Veo 3.1? Gere seu primeiro vídeo em 5 minutos

TL;DR

• O Veo 3.1 é o modelo de geração de vídeo do Google e, na HiAPI, está dividido em três versões: Standard, Fast e Lite, com texto para vídeo e imagem para vídeo. Abra a página do modelo para gerar online; novos usuários ganham 200 créditos ao se cadastrar.
• Cobrança por segundo: Lite 720p sem áudio custa $0.06 por segundo, Fast 720p/1080p com áudio custa $0.25 por segundo e a versão Standard custa $0.57 por segundo; um rascunho Lite de 4 segundos sai por apenas $0.24.
• A API tem duas etapas: envie com POST /v1/tasks e consulte o resultado com o taskId. O curl e o Python abaixo funcionam só copiando e colando.

O que o Veo 3.1 faz?

• Áudio nativo: imagem e som são gerados juntos; ambiência, efeitos sonoros e sons das ações acompanham a imagem; generate_audio vem ativado por padrão, e desativá-lo sai mais barato.
• Três durações: 4, 6 e 8 segundos, em 16:9 horizontal ou 9:16 vertical.
• Até 4K: Standard e Fast suportam 720p, 1080p e 4K; Lite suporta 720p e 1080p.
• Imagem para vídeo: envie uma imagem como primeiro quadro, o modelo a anima, e o formato pode seguir a imagem original.

O vídeo vertical de 6 segundos em 1080p abaixo foi gerado com uma imagem de produto de tênis e uma única requisição; o baque grave ao apoiar e a batida de bumbo grave foram adicionados pelo próprio modelo:

The sneaker slowly rotates about 90 degrees as the camera pushes in from a low angle. Dust particles drift through the rim light. The shoe settles onto the wet stone pedestal with a deep, satisfying thud, sending a soft ring of mist rolling off the edges. A warm light sweep travels across the suede texture. Subtle bass-heavy electronic pulse builds in the background with a low whoosh on the landing. Cinematic product commercial, smooth stabilized motion, no text overlays.

Gerar com este prompt → (primeiro envie uma imagem de produto em 9:16)

veo-3.1/image-to-video, 1080p, 6 segundos, com áudio, $3.42, cerca de 115 segundos do envio à conclusão.

Como escolher entre as três versões?

Versão	720p/1080p com áudio	720p/1080p sem áudio	4K com áudio	Indicado para
Lite veo-3.1-lite	$0.1 (720p) / $0.14 (1080p)	$0.06 (720p) / $0.1 (1080p)	—	Ajustar prompts, rascunhos em lote
Fast veo-3.1-fast	$0.25	$0.17	$0.6	Vídeos curtos para redes sociais
Standard veo-3.1	$0.57	$0.29	$0.86	Publicidade, filmes de marca

Os valores são por segundo. Para 8 segundos com áudio: Lite 1080p $1.12, Fast $2, Standard $4.56. Para ver as contas em detalhe, consulte preços da API do Veo 3.1.

Dois caminhos para começar

Teste online (sem escrever código)

1. Abra a página do modelo Veo 3.1 Lite texto para vídeo e cadastre-se ou faça login.
2. Cole o prompt, escolha duração, resolução, formato e decida se quer áudio.
3. Clique em gerar e baixe o vídeo direto quando ficar pronto.

Chamada de API

1. Crie uma API Key no console.
2. Envie a tarefa com POST https://api.hiapi.ai/v1/tasks; a resposta traz o taskId.
3. Consulte o status com GET /v1/tasks/{taskId}; quando status for success, baixe o vídeo em output[0].url.

curl: o primeiro vídeo

Comece pelo Lite, o mais barato: 4 segundos em 720p sem áudio por $0.24:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-lite/text-to-video",
    "input": {
      "prompt": "A matte-black wireless earbud case slowly rotates on a reflective black surface under a single overhead spotlight.",
      "duration": 4,
      "resolution": "720p",
      "aspect_ratio": "9:16",
      "generate_audio": false
    }
  }'

Resposta:

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

Consulte o resultado:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... \
  -H "Authorization: Bearer $HIAPI_KEY"

Python: enviar, consultar e baixar

# pip install requests; antes, export HIAPI_KEY=sua_Key
import os, time, uuid, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}

def generate(prompt, model="veo-3.1-lite/text-to-video", timeout_s=900, **params):
    body = {"model": model, "input": {"prompt": prompt, **params}}
    # Ao reenviar a mesma tarefa, use o mesmo Idempotency-Key para evitar cobrança duplicada
    headers = {**H, "Idempotency-Key": str(uuid.uuid4())}
    r = requests.post("https://api.hiapi.ai/v1/tasks", json=body, headers=headers, timeout=30)
    r.raise_for_status()
    res = r.json()
    if res.get("code") != 200:
        raise RuntimeError(res)
    task_id = res["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d)
        time.sleep(10)
    raise TimeoutError(task_id)

url = generate(
    "A barista pours hot water in a slow spiral over ground coffee, steam rising in morning light",
    duration=4, resolution="720p", aspect_ratio="16:9", generate_audio=True,
)
with open("clip.mp4", "wb") as f:
    f.write(requests.get(url).content)

Depois de definir o prompt, troque model por veo-3.1-fast/text-to-video ou veo-3.1/text-to-video para gerar o vídeo final, mantendo os outros parâmetros.

Imagem para vídeo

Troque o nome do modelo para …/image-to-video e adicione uma imagem em input (image_url é uma string e aceita apenas uma imagem):

{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The sneaker slowly rotates and settles onto the wet stone pedestal with a deep thud",
    "image_url": "https://your-cdn.example.com/sneaker-916.jpg",
    "aspect_ratio": "auto",
    "resolution": "1080p",
    "duration": 6
  }
}

• Defina aspect_ratio como auto para seguir a imagem original; também é possível especificar 16:9 ou 9:16; imagens em outras proporções serão cortadas.
• Recomenda-se uma imagem original com 720p ou mais, em 16:9 ou 9:16; SVG não é suportado.
• Escreva no prompt "como deve se mover nos próximos segundos"; não é preciso descrever a imagem inteira de novo.

Atenção antes de ir para produção

• Use callback em vez de polling: adicione no nível superior da requisição "callback": {"url": "https://seu-dominio/hiapi/callback"}; ao final da tarefa, a HiAPI notifica ativamente; deduplique pelo taskId.
• Salve o quanto antes: output[0].url é um link temporário; assim que recebê-lo, armazene imediatamente no seu próprio storage.
• Preencha todos os parâmetros: duration tem padrão de 8 segundos; o resolution é obrigatório no Standard e no Fast; informe explicitamente duração, resolução e generate_audio para que o custo bata com o orçamento.
• Sem áudio, desative: com generate_audio: false, o Lite 720p cai de $0.1 para $0.06 por segundo, e o Standard cai de $0.57 para $0.29.
• Reembolso automático em caso de falha: a cobrança é feita apenas pelos vídeos gerados com sucesso.

Perguntas frequentes

Posso escrever o prompt em chinês?

Sim, em chinês ou inglês. Para maior consistência, escreva câmera, ação e som em frases separadas.

É possível gerar um vídeo de 10 segundos?

Cada geração suporta apenas 4, 6 ou 8 segundos. Para vídeos mais longos, gere por partes e edite depois.

O áudio pode ser controlado separadamente?

Você pode detalhar cada camada de som no prompt (som de ações próximas, vozes do ambiente, vento) e o modelo as gera separadamente; se não quiser áudio, defina generate_audio como false.

O que preciso mudar para usar um prompt ajustado no Lite com a versão Standard?

Apenas o nome do modelo. prompt, duration, aspect_ratio e generate_audio são compatíveis; se quiser 4K, altere resolution para 4k (o Lite não tem 4K).

Se quiser prompts prontos, veja exemplos de prompts do Veo 3.1; você também pode copiar o prompt do tênis acima e gerar na página do modelo.