Tutorial
Chamar veo-3.1/image-to-video pela API HiAPI: tutorial em curl e Python
Nesta página
O que o endpoint veo-3.1 image-to-video espera
Antes de escrever a primeira linha de código, ajuda entender que tipo de chamada é essa. O veo-3.1/image-to-video não devolve o vídeo diretamente na resposta HTTP em que você envia o prompt. É um endpoint de tarefa assíncrona: você descreve o vídeo desejado, a plataforma aceita a tarefa e depois você volta para consultar o resultado.
Conceitualmente, uma requisição contém duas partes bem distintas:
- Imagem do primeiro quadro. É o quadro estático inicial a partir do qual o vídeo é gerado. Ela ancora a composição, o sujeito e a aparência do momento de abertura. Todo o restante é gerado pelo modelo a partir desse ponto de partida.
- Opções de geração. São os parâmetros que controlam como o vídeo é gerado — por exemplo, se o áudio é gerado, a resolução de saída e a duração do clipe.
Essa separação importa por dois motivos. Primeiro, torna as falhas mais fáceis de raciocinar: problemas de imagem parecem diferentes de problemas de parâmetros, e você quer conseguir distingui-los. Segundo, significa que seu código também deve ser organizado da mesma forma — uma parte da lógica cuida da preparação da imagem, outra cuida da montagem do conjunto de opções.
Quem chama deve fornecer, no mínimo: uma imagem de primeiro quadro válida e decisões sobre áudio, resolução e duração. Todo o resto — enviar a tarefa, acompanhar o status, retornar o vídeo final — é tratado pelo ciclo de vida de tarefas da plataforma. Sua integração só precisa fazer três coisas: enviar uma requisição bem formatada, guardar o identificador de tarefa retornado e fazer polling até a tarefa entrar em estado terminal.
Uma dica prática antes de continuar: como a chamada é assíncrona, seu código não pode assumir que o vídeo estará disponível imediatamente após o envio. Projete o fluxo em torno disso desde o início, e o restante do tutorial parecerá natural.
O modelo mental das duas partes
Mantenha este quadro em mente ao ler as seções a seguir:
- Entrada → imagem do primeiro quadro preparada e validada.
- Opções → áudio, resolução, duração.
- Tarefa → envio, obtenção do identificador, polling, recuperação.
Cada seção abaixo corresponde a um desses blocos.
Preparar a imagem do primeiro quadro
A imagem do primeiro quadro é a entrada mais importante em uma chamada de imagem para vídeo, então dê a ela uma etapa dedicada no pipeline em vez de escondê-la dentro do construtor de requisição. A chamada da API precisa conseguir referenciar essa imagem, o que significa que ela deve estar em um formato que a plataforma aceite e consiga ler.
O que verificar antes de enviar
- A imagem realmente abre. Downloads truncados ou arquivos corrompidos são a causa mais comum de falhas confusas adiante. Antes de enviar qualquer coisa, verifique se ela decodifica corretamente.
- O formato é aceito pela plataforma. Se sua origem for captura de tela, foto de celular ou exportação de ferramenta de design, normalize para um formato amplamente suportado antes do upload. Converter uma vez com antecedência dá menos trabalho do que depurar depois.
- As dimensões são razoáveis. Imagens minúsculas ou extremamente esticadas oferecem pouco material ao modelo. Se a origem for pequena demais, considere ampliar ou escolher um quadro melhor.
- A composição é um bom ponto de partida. Como este é o primeiro quadro, o movimento gerado continua a partir dele. Escolha um quadro em que o sujeito esteja claramente visível e cuja composição você fique satisfeito em ver no início do clipe.
Mantenha separado das opções
Organize o código de modo que a preparação da imagem retorne uma referência que possa ser entregue ao construtor de requisição, em vez de misturar processamento de imagem com montagem de parâmetros. Concretamente:
# Estrutura em pseudocódigo, não é um cliente completo
def prepare_first_frame(path):
image = load_and_validate(path) # decodifica, verifica formato, verifica dimensões
ref = upload_or_encode(image) # gera algo que a chamada da API possa referenciar
return ref
def build_request(first_frame_ref, options):
return {
"first_frame": first_frame_ref,
# áudio / resolução / duração entram aqui
}
Essa separação compensa na depuração. Se a tarefa falhar, você pode executar prepare_first_frame isoladamente e confirmar que o lado da imagem está saudável antes de mexer em qualquer parâmetro de geração.
Valide cedo, falhe alto
Faça a validação do seu lado e lance erros claros quando ela falhar. Uma imagem malformada ou ilegível nunca deve chegar à rede — capturá-la localmente transforma uma falha assíncrona de tarefa vaga em uma exceção precisa e imediata escrita por você.
Definir as opções de geração: áudio, resolução e duração
Com a imagem tratada, as decisões restantes são as opções de geração. Elas mudam a natureza da saída, então trate-as como parâmetros nomeados explícitos, e não como valores mágicos enterrados no corpo da requisição.
Áudio
A opção de áudio controla se o vídeo gerado inclui uma faixa de áudio. É tanto uma decisão técnica quanto de produto:
- Se o vídeo for incorporado em silêncio — loop de fundo, visual principal em autoplay — normalmente não é preciso áudio, e dispensá-lo simplifica o processamento posterior.
- Se o clipe for exibido isoladamente com som — conteúdo curto para redes sociais, demonstrações — ative o áudio para obter o material completo em uma única chamada.
Decida de forma intencional conforme o caso de uso, em vez de adotar o padrão cegamente; isso afeta tanto a saída quanto a forma como seu pipeline posterior lida com o arquivo.
Resolução
A resolução determina as dimensões em pixels do vídeo final. Escolha com base em onde o vídeo será exibido e em quanto detalhe o conteúdo precisa, em vez de simplesmente pegar o "maior valor disponível". Um clipe renderizado para um player pequeno embutido não ganha nada por ser gerado em um tamanho muito além da capacidade do painel de exibição. Se a plataforma publicar um conjunto de valores suportados, escolha explicitamente entre eles e valide no cliente, para que valores não suportados falhem rapidamente.
Duração
A duração define o comprimento do clipe gerado. Ela interage com o planejamento do seu conteúdo: um plano que precisa estabelecer a cena e depois mostrar movimento precisa de mais tempo do que um único gesto. Note que este é um dos parâmetros mais prováveis de serem medidos — a cobrança da plataforma é descrita em termos de saída gerada, então fique atento ao tamanho dos clipes ao enviar requisições em lote.
Montar as opções em um objeto
Coloque as três em uma mesma estrutura de opções, para que haja um único lugar para consultar e um único lugar para alterar:
options = {
"audio": True, # gera a faixa de áudio
"resolution": "...", # um dos valores suportados
"duration": 8, # segundos de vídeo gerado
}
Use os valores que sua conta e a documentação atual do endpoint indicam como suportados — leia da documentação em vez de fixar suposições no código, e valide ao construir a requisição, para que valores inválidos nunca se tornem tarefas com falha.
Enviar a tarefa com curl
Agora junte as duas partes e envie. Comece pela linha de comando, porque o curl torna a forma da requisição visível e dá a você uma maneira rápida de testar alterações antes de escrever o código.
A requisição
O envio da requisição tem a seguinte estrutura — substitua os valores de placeholder pelas suas credenciais, referência de imagem e valores de opção:
curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_frame": "<referência de imagem vinda da etapa de upload>",
"audio": true,
"resolution": "<valor suportado>",
"duration": 8
}'
Algumas convenções que vale a pena adotar:
- Guarde a chave em uma variável de ambiente (
$HIAPI_API_KEY) em vez de colá-la no comando. Esse hábito continua diretamente no seu código Python e mantém a chave longe do histórico do shell. - Envie o JSON com o cabeçalho
Content-Typeexplícito. - No corpo da requisição, mantenha a referência de imagem separada dos valores numéricos e booleanos das opções, ecoando o modelo de duas partes da primeira seção.
Ler a resposta
Como este é um endpoint assíncrono, uma resposta bem-sucedida não é o vídeo. É apenas a confirmação de que a tarefa foi aceita e traz as informações necessárias para acompanhá-la — o mais importante, o identificador da tarefa e, normalmente, um campo de status indicando que ela foi enfileirada ou está em execução.
Leia em duas etapas. Primeiro, confirme que o status HTTP indica aceitação, e não erro do cliente. Depois, analise o corpo da resposta e extraia o identificador da tarefa:
curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | tee submit.json
Gravando a resposta em submit.json, você tem algo para inspecionar e também para alimentar a etapa de polling. Se o envio falhar, o corpo da resposta de erro é sua primeira e melhor pista — verifique se ele aponta para a referência de imagem ou para alguma opção, corrija apenas essa metade e envie novamente.
Fazer polling da tarefa assíncrona até o vídeo ficar pronto
Com o identificador da tarefa em mãos, o fluxo se torna um laço: pergunte à plataforma o status da tarefa e pare quando ela entrar em estado terminal.
Ciclo de vida
Uma tarefa de imagem para vídeo passa por poucos estados. Ela é aceita e enfileirada, depois processada e, por fim, ou conclui com sucesso produzindo o vídeo, ou falha com um erro. Seu código de polling só precisa distinguir três coisas:
- Ainda em processamento — continue esperando.
- Sucesso — leia a localização da saída e baixe ou armazene o vídeo.
- Falha — pare e lance um erro.
Fazer polling com responsabilidade
Dois hábitos tornam o polling mais robusto:
- Espere entre as verificações. Um laço apertado martelando o endpoint de status desperdiça requisições sem ganho algum; a geração leva tempo real. Use um intervalo fixo ou um backoff suave.
- Defina um prazo limite. Nunca faça polling infinito. Escolha um número máximo de tentativas ou um tempo máximo decorrido e trate o excesso como uma falha relatável de forma clara.
# Esboço de laço de polling
for i in $(seq 1 60); do
status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
-H "Authorization: Bearer $HIAPI_API_KEY")
echo "$status"
# saia quando o campo de status indicar sucesso ou falha
sleep 5
done
Trate as strings exatas de status e os caminhos de endpoint como itens a confirmar na documentação atual da API, e não como suposições fixadas no script.
Em caso de sucesso
Quando a tarefa reporta sucesso, a resposta traz a localização do vídeo final. Baixe e armazene prontamente em um local persistente — resultados de tarefas em qualquer plataforma assíncrona devem ser tratados como algo a recuperar agora, e não como algo a buscar preguiçosamente muito depois. Registre o identificador da tarefa junto com o arquivo armazenado, para que qualquer saída possa ser rastreada até a requisição que a produziu.
A mesma requisição em Python
A versão em Python não deve ser uma segunda implementação — deve ser a mesma requisição, expressa uma vez e reutilizada. O objetivo é uma única função que envia e faz polling, construída a partir da mesma referência de imagem e do mesmo objeto de opções que você já validou.
Um corpo de requisição, um cliente
import os
import time
import requests
BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
})
def build_body(first_frame_ref, options):
return {"first_frame": first_frame_ref, **options}
def submit(body):
r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
r.raise_for_status()
data = r.json()
return data["job_id"]
def poll(job_id, interval=5, max_attempts=60):
for _ in range(max_attempts):
r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
r.raise_for_status()
data = r.json()
state = data.get("status")
if state in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"A tarefa {job_id} não foi concluída a tempo")
def image_to_video(first_frame_ref, options):
job_id = submit(build_body(first_frame_ref, options))
result = poll(job_id)
if result["status"] == "failed":
raise RuntimeError(result.get("error", "A tarefa falhou"))
return result # contém a localização do vídeo final
Por que essa forma
- Uma
Session. Reutilizar a sessão coloca o cabeçalho de autenticação em um único lugar e reaproveita a conexão entre o envio e cada polling. - Um
build_body. A requisição curl e a requisição Python usam o mesmo corpo — as mesmas chaves, os mesmos valores. Quando você modificar alguma opção, modifique em um único lugar. - Timeouts e prazos explícitos. As duas chamadas definem timeout, e
polltem limite de tentativas, então uma tarefa travada nunca prende seu processo. - Falhas expostas em alto e bom som. O
raise_for_statusno envio captura imediatamente erros de nível de requisição; o ramo explícito de falha emimage_to_videocaptura falhas de nível de tarefa.
Se mais tarde você precisar chamar outros modelos pela mesma plataforma, essa estrutura é generalizável: a sessão, a função auxiliar de envio e a função auxiliar de polling permanecem iguais, e só o endpoint e o construtor de corpo mudam.
Diagnosticar chamadas de imagem para vídeo com falha
Quando uma chamada não produz vídeo, reduza o escopo perguntando em qual etapa ela falhou. O modelo de requisição em duas partes oferece uma checklist clara.
Etapa 1: envio rejeitado
Se a própria chamada de envio retorna erro, nada foi gerado — o que é uma boa notícia, porque o problema está na requisição.
- Problema na referência de imagem. A causa única mais comum. Execute a etapa de preparação da imagem isoladamente para confirmar que ela produz uma imagem válida, legível e no formato correto, além de uma referência aceita pela API. Verifique primeiro uploads truncados e formatos não suportados.
- Valores de opção inválidos. Resolução não suportada ou duração fora da faixa são rejeitadas no envio. Valide as opções contra os valores suportados na documentação antes de enviar.
- Autenticação e cabeçalhos. Confirme que a chave está realmente sendo enviada (
Authorization: Bearer ...) e que o corpo vai como JSON. Ao montar requisições manualmente no curl, corpos vazios ou malformados passam facilmente despercebidos.
Etapa 2: tarefa enviada, mas com falha
Se o envio foi aceito mas o polling termina em falha, a requisição está bem formatada, e o problema está no conteúdo ou na tarefa em si.
- Leia o erro da tarefa. A resposta de falha explica melhor o que deu errado do que qualquer suposição. Registre-a literalmente.
- Examine o primeiro quadro. Imagens de origem sem sujeito claro, com recorte extremo ou severamente distorcidas oferecem pouco material ao modelo. Troque por um quadro mais limpo e tente novamente.
- Reconsidere as opções. Durações muito longas ou combinações incomuns de configuração merecem ser retestadas com uma configuração mais simples, para isolar qual parâmetro é o problema.
Etapa 3: o polling nunca termina
Se o seu laço expira em vez de falhar, trate isso como problema de infraestrutura, e não de conteúdo. Confirme que você está consultando o identificador de tarefa correto, que o intervalo não é agressivo demais e que o prazo limite é longo o bastante para a duração solicitada. Registre o identificador da tarefa no envio — sem ele, você não consegue investigar uma tarefa travada.
Fluxo eficaz de depuração
Quando algo der errado, siga esta ordem: valide a imagem localmente, envie novamente e capture a resposta bruta, verifique o erro da tarefa se houver, depois simplifique as opções e tente de novo. Cada passo testa exatamente uma metade da requisição, e é por isso que separar imagem e parâmetros de geração no código compensa justamente na hora do erro.
Com isso, você tem o ciclo completo: preparar o primeiro quadro, definir áudio, resolução e duração, enviar de forma assíncrona e fazer polling até a conclusão — seja executando em curl ou em Python, é a mesma requisição.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio