Tutorial
Como chamar a API de texto para vídeo veo-3.1: exemplos em curl e Python
Guia prático de integração para desenvolvedores
Nesta página
O que veo-3.1/text-to-video pode fazer por você
veo-3.1/text-to-video é um modelo de geração de vídeo a partir de texto disponibilizado por meio da API unificada da HiAPI. Você envia um prompt de texto, escolhe algumas opções de saída e recebe o vídeo gerado. Ele fica na HiAPI junto com outros endpoints de geração, então, se você já usa recursos de imagem ou chat nessa plataforma, essa forma de integração será familiar: uma requisição HTTP autenticada retorna uma tarefa, e você faz polling até que ela seja concluída.
Este endpoint é a escolha certa quando você tem uma descrição textual de uma cena e quer gerar um vídeo curto sem gerenciar infraestrutura própria. Você não precisa lidar com alocação de GPU, pesos de modelo ou filas. O custo disso é que a geração é assíncrona: você envia a tarefa e volta depois para conferir o resultado. Isso é normal em vídeo, porque a renderização leva mais tempo do que um único ciclo de requisição/resposta.
Use texto para vídeo quando a entrada principal for o prompt. Se depois você precisar de geração condicionada por imagem ou por vídeo, consulte os endpoints correspondentes no catálogo de modelos. A estrutura de requisição aqui (autenticação, envio de tarefa, polling) é o mesmo padrão que você reutilizará nos endpoints de mídia da HiAPI, então aprender uma vez traz benefícios duradouros. Você encontra os detalhes completos do modelo na página do modelo veo-3.1/text-to-video.
Endpoint, autenticação e estrutura de requisição
Todas as requisições à HiAPI usam HTTPS e bearer token. Guarde sua chave de API em uma variável de ambiente em vez de codificá-la diretamente, e envie-a no cabeçalho Authorization:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Uma requisição de texto para vídeo é um objeto JSON com um campo model e um objeto input. O objeto input contém o prompt e quaisquer controles de saída. O corpo mínimo da requisição fica assim:
{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "Uma viela de neon molhada pela chuva à noite, movimento lento de dolly"
}
}
O retorno não é o vídeo final, mas um envelope de tarefa. Ele normalmente contém um identificador de tarefa, um campo de status e timestamps. A estrutura é mais ou menos assim:
{
"id": "job_abc123",
"status": "queued",
"created_at": "2025-01-01T00:00:00Z"
}
Consulte a resposta real para os nomes exatos dos campos, mas a estrutura é consistente: você precisa do id para fazer polling, e o status informa se a tarefa está na fila, em execução ou concluída. Não presuma que a tarefa foi concluída só porque a chamada de envio retornou 200 — isso significa apenas que a tarefa foi aceita.
Escolhendo parâmetros: áudio nativo e opções de resolução
Além do prompt, os parâmetros mais importantes para texto para vídeo são se deve gerar áudio nativo e qual opção de resolução usar. Ambos afetam o tempo de geração e a natureza da saída, então faça escolhas conscientes em vez de usar os padrões sem pensar.
Áudio nativo
Alguns modelos de vídeo podem gerar uma faixa de áudio junto com a imagem. Se esse endpoint oferecer uma opção de áudio nativo, ativá-la significa que o clipe gerado inclui som sincronizado. Isso é útil para cenas em que o áudio faz parte da experiência — ruído ambiente, música ou efeitos sonoros que combinam com a ação. Se você planeja adicionar sua própria trilha ou narração na pós-produção, desative-a para que a saída foque apenas na imagem. A geração de áudio também aumenta o tempo de processamento, então ative apenas quando realmente precisar.
Opções de resolução
As opções de resolução permitem equilibrar fidelidade visual com custo e latência. Opções mais altas produzem saídas mais nítidas, mas levam mais tempo e consomem mais recursos. Escolha a opção mais baixa que atenda ao seu objetivo de entrega: uma opção de rascunho para iteração e revisão, e uma opção mais alta para a renderização final. Se você for gerar muitos candidatos para um prompt, explore com a opção mais baixa e depois regenere o vencedor em qualidade total. A cobrança acompanha a saída que você gera, então escolher a opção de forma consciente é a principal alavanca sob seu controle.
Quando não tiver certeza de quais valores esse endpoint aceita no momento, envie primeiro uma requisição só com o prompt e depois verifique a resposta ou a mensagem de erro. A HiAPI retorna erros de validação estruturados que listam os campos aceitáveis, então você pode ajustar com base neles sem adivinhar.
Requisição curl executável
Este comando curl envia uma tarefa de texto para vídeo. Ele define o tipo de conteúdo JSON, passa o bearer token a partir de uma variável de ambiente e envia um corpo com model e input.
curl -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "Uma viela de neon molhada pela chuva à noite, movimento lento de dolly",
"duration": 5,
"resolution": "720p"
}
}'
Uma chamada bem-sucedida retorna um objeto JSON com o id e o status da tarefa. Anote esse id — você precisará dele para o polling. Se estiver escrevendo um script, pode extrair o id com um processador JSON:
JOB_ID=$(curl -s -X POST https://api.hiapi.ai/v1/videos/generations \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"veo-3.1/text-to-video","input":{"prompt":"Uma viela de neon molhada pela chuva à noite, movimento lento de dolly"}}' \
| jq -r '.id')
echo "$JOB_ID"
Ajuste o caminho do endpoint, os nomes dos parâmetros e quaisquer campos opcionais conforme o que a API real espera. Esse padrão — enviar um corpo JSON via POST e ler o id da resposta — é a base de todos os exemplos a seguir.
Enviando a mesma requisição em Python
A versão em Python faz a mesma coisa usando a biblioteca padrão requests. Leia a chave do ambiente, monte o payload e envie.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
payload = {
"model": "veo-3.1/text-to-video",
"input": {
"prompt": "Uma viela de neon molhada pela chuva à noite, movimento lento de dolly",
},
}
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=headers,
json=payload,
timeout=60,
)
response.raise_for_status()
job = response.json()
job_id = job["id"]
print(f"Tarefa enviada: {job_id} (status: {job.get('status')})")
Dois pontos merecem destaque. Primeiro, response.raise_for_status() converte erros HTTP em exceções, tornando as falhas visíveis imediatamente em vez de deixar um payload inválido seguir silenciosamente. Segundo, timeout=60 evita que uma conexão travada bloqueie seu script. O envio em si é rápido; o vídeo real é renderizado de forma assíncrona, então você não fica esperando o arquivo aqui. Em seguida, você usará o job_id para fazer polling da conclusão.
Fazendo polling da tarefa assíncrona até o vídeo ficar pronto
Depois de enviar, faça polling do endpoint da tarefa até que o status indique conclusão ou falha. Um loop simples com uma pequena pausa já é suficiente para começar.
import time
while True:
res = requests.get(
f"{BASE_URL}/videos/generations/{job_id}",
headers=headers,
timeout=30,
)
res.raise_for_status()
state = res.json().get("status")
print(f"Status: {state}")
if state == "succeeded":
video_url = res.json().get("output", {}).get("url")
print(f"Vídeo pronto: {video_url}")
break
if state == "failed":
raise RuntimeError(f"Tarefa falhou: {res.json()}")
time.sleep(5)
Algumas melhorias úteis: comece com intervalos curtos e depois aumente gradualmente para reduzir requisições desperdiçadas; adicione um número máximo de tentativas ou um prazo limite para evitar loops infinitos com tarefas travadas; e trate com cautela qualquer status inesperado, em vez de presumir que significa "continue esperando". Os valores de status comuns incluem queued, running, succeeded e failed. Quando a tarefa é bem-sucedida, a resposta normalmente traz uma URL de saída; baixe e salve o arquivo prontamente, pois URLs assinadas podem expirar.
Torne o polling idempotente e registre o id da tarefa a cada mudança de status. Se seu processo reiniciar, você pode retomar pelo id sem reenviar. Em produção, se a plataforma oferecer webhook, considere usá-lo, com o polling como fallback.
Diagnosticando erros comuns
A maioria das falhas se enquadra em algumas categorias. Verifique a lista abaixo em ordem, em vez de tentar novamente às cegas.
Falhas de autenticação (401/403)
Verifique se o cabeçalho Authorization está presente e formatado corretamente como Bearer <key>, e se a variável de ambiente está de fato definida no shell ou processo que faz a requisição. Uma armadilha comum é executar o script em um ambiente em que a chave existe em um shell mas não em outro.
Erros de validação (400/422)
Esses erros retornam detalhes estruturados sobre qual campo está incorreto. Causas comuns: prompt ausente, valores de resolution ou duration não suportados, ou nível de aninhamento de parâmetros errado. Leia a mensagem de erro literalmente — ela geralmente aponta o campo problemático. Envie primeiro o payload mínimo e depois adicione um parâmetro de cada vez.
Limite de taxa (429)
Você enviou requisições rápido demais. Implemente backoff exponencial e um limite de tentativas. Se for iniciar muitas tarefas, escalone os envios e acompanhe as tarefas em andamento.
Timeouts e erros de rede
Um timeout do cliente no envio raramente é problema da tarefa em si — a tarefa roda no servidor. Use timeouts razoáveis tanto no envio quanto nas requisições de polling, e repita GETs idempotentes. Nunca repita um POST às cegas sem verificar se a tarefa original já foi criada.
A tarefa nunca é concluída
Se uma tarefa ficar em queued ou running por muito mais tempo que o esperado, verifique o código de status e a mensagem em vez de reenviar. Prompts longos ou opções de resolução mais altas levam mais tempo; isso é normal. Se a tarefa reportar failed, registre o corpo completo da resposta — a mensagem de erro geralmente indica a causa.
Em caso de dúvida, reproduza com a menor requisição possível e inspecione cada resposta. Isso é muito melhor do que alterar vários parâmetros de uma vez e adivinhar qual deles importa. Para detalhes específicos do endpoint, consulte a página do modelo.
Artigos relacionados
Ver todos os artigos →-
Tutorial
kling-image-4.0 cenários de aplicação na prática: 5 usos de alto valor e pontos de integração
-
Tutorial
Como chamar o gemini-omni-1.1-flash pela API HiAPI: guia com curl e Python
-
Tutorial
Como usar o qwen-image-2.0-pro pela API HiAPI: curl, Python e uma requisição funcional
Um exercício prático de integração para desenvolvedores: primeira chamada bem-sucedida, análise da estrutura da requisição e diagnóstico de falhas