Tutorial
Como gerar vídeos com gemini-omni-flash através da API HiAPI
Caminhos de requisição de texto para vídeo e imagem para vídeo, seleção de modelo e uma lista de verificação de integração funcional
Nesta página
Por que o gemini-omni-flash tem dois endpoints de vídeo
Antes de escrever a primeira linha de código, a decisão mais importante é: qual dos dois endpoints de vídeo você realmente precisa. O gemini-omni-flash é oferecido na HiAPI como dois modelos independentes, e não como um único endpoint com um sinalizador de modo:
gemini-omni-flash/text-to-video— gera vídeo apenas a partir de um prompt de texto.gemini-omni-flash/image-to-video— usa a imagem de origem fornecida como âncora visual e gera vídeo guiado por um prompt de texto.
A separação existe porque as duas tarefas têm entradas diferentes, regras de validação diferentes e modos de falha diferentes. O texto para vídeo só precisa validar uma string de prompt. O imagem para vídeo também precisa buscar e decodificar sua imagem de origem, o que adiciona toda uma classe de erros que simplesmente não ocorre no caminho de texto (URL inacessível, formato não suportado, recurso grande demais).
Regra prática: se você já tem uma imagem estática — foto de produto, quadro de storyboard, fotografia —, use imagem para vídeo, porque o modelo parte do seu conteúdo visual em vez de criar do zero. Se você tem apenas uma ideia e nenhum material de referência, use texto para vídeo.
Distinga os dois IDs de modelo no seu código desde o primeiro dia. Tratá-los como um único conceito de "vídeo" e depois acrescentar um sinalizador if has_image é exatamente o que faz uma integração acabar com cargas confusas e bugs difíceis de entender.
O que permanece igual
Os dois endpoints compartilham o mesmo esquema de autenticação, a mesma URL base, as mesmas convenções gerais de requisição/resposta e o mesmo modelo de cobrança (vídeo é cobrado pela saída gerada, não pelo número de requisições). São essas partes compartilhadas que tornam viável um único construtor de requisições — detalhado adiante.
O que é diferente
Apenas a estrutura da carga e a validação de entrada diferem. A diferença é pequena o suficiente para você suportar os dois endpoints sem duplicar todo o código de integração.
Pré-requisitos e configuração da API
Antes da primeira chamada, você precisa de três coisas.
1. Chave de API
Crie uma chave na sua conta HiAPI e armazene-a como variável de ambiente, nunca codificada diretamente:
export HIAPI_API_KEY="your_key_here"
Cada requisição é autenticada por um bearer token no cabeçalho Authorization. Não há etapa de assinatura separada nem nonce por requisição.
2. URL base e convenção de nomes de modelos
Todas as chamadas vão para a mesma URL base da HiAPI, e o modelo é selecionado pelo campo model no corpo da requisição. Os IDs de modelo seguem o padrão family/variant, então os modelos de vídeo são escritos como gemini-omni-flash/text-to-video e gemini-omni-flash/image-to-video. Você troca de endpoint alterando apenas uma string, não o host.
3. Ferramentas para disparar requisições
curl basta para verificar a conectividade, e Python (com requests) basta para construir uma integração real. Nenhum dos dois exige um SDK específico de fabricante — a API é apenas JSON sobre HTTPS.
Verificação de conectividade
Antes de gerar qualquer vídeo, acesse um endpoint leve (por exemplo, listar os modelos disponíveis) para confirmar que a chave funciona e o caminho de rede está normal. Se isso falhar, você está depurando credenciais ou conectividade, não geração de vídeo — descobrir qual dos dois poupa muito tempo.
Lista rápida de verificação:
- A chave foi exportada no shell em que a requisição será executada.
- A URL base está documentada e é usada de forma consistente em todos os lugares (nada de variação de barra final entre scripts).
- Todo POST define
Content-Type: application/json. - Há uma forma de ver a resposta JSON bruta sem truncamento.
Fazer uma requisição de texto para vídeo
Comece pela menor requisição possível que tenha chance de funcionar. Não preencha todos os parâmetros opcionais de cara — se a menor requisição falhar, você sabe que o problema é estrutural; se funcionar, cada parâmetro adicionado depois é uma mudança atribuível isoladamente.
Estrutura mínima
A requisição de texto para vídeo envia o ID do modelo e o prompt:
{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Plano de avanço lento por uma rua de neon molhada pela chuva à noite, reflexos no asfalto úmido, cinematográfico"
}
Essa é a carga completa. Envie-a, confirme que recebeu um objeto de resposta de sucesso e só então comece a enriquecer o conteúdo.
Evoluir a requisição passo a passo
Depois que a chamada mínima funcionar, adicione um parâmetro por vez e revalide após cada adição. Acréscimos típicos no caminho de texto:
- Detalhes do prompt — sujeito, movimento, comportamento de câmera, iluminação e atmosfera. Prompts vagos produzem movimento vago; descreva o que se move e como a câmera se move.
- Duração / comprimento da saída — vídeo é cobrado pela saída gerada, então o comprimento afeta diretamente o custo. Fixe-o explicitamente em vez de depender de padrões que você ainda não verificou.
- Proporção ou resolução (se o modelo suportar), para corresponder ao player ou formato de rede social a jusante.
Pontos de escrita de prompt que realmente importam
A qualidade do texto para vídeo é determinada principalmente pela especificidade do prompt. Três bons hábitos:
- Descreva movimento, não apenas conteúdo. "Um barquinho de papel descendo por uma sarjeta" dá ao modelo algo animável; "um barquinho de papel" não dá.
- Especifique a câmera. Fixa, panorâmica, avanço, na mão — a linguagem de câmera elimina muita ambiguidade.
- Limite a uma cena. Descrever múltiplas tomadas em um único clipe curto costuma produzir um resultado confuso.
Quando o resultado de texto para vídeo ficar ruim, mude primeiro o prompt e só depois mexa em qualquer parâmetro técnico.
Fazer uma requisição de imagem para vídeo
O caminho de imagem é estruturalmente igual ao caminho de texto, com um acréscimo: a imagem de origem. O método de teste "mínimo primeiro" que você aprendeu também se aplica aqui.
Estrutura mínima
{
"model": "gemini-omni-flash/image-to-video",
"prompt": "Deriva suave na mão, sujeito girando levemente em direção à câmera, luz suave de janela",
"image": "https://your-cdn.example.com/source-frame.jpg"
}
Nesse caso, o prompt descreve movimento e comportamento de câmera em relação à imagem, e não o conteúdo da cena — a imagem já fornece o conteúdo. Esse é o erro conceitual mais comum: as pessoas escrevem uma descrição completa da cena e depois se perguntam por que a saída ignorou o quadro de origem.
Como fornecer a imagem de origem
A imagem é passada por referência, e o serviço precisa conseguir buscá-la. Há duas consequências práticas:
- O recurso precisa ser acessível publicamente pelo serviço, não pode estar atrás do seu localhost, VPN ou bucket autenticado. URLs assinadas com expiração curta funcionam, desde que ainda sejam válidas quando a requisição for executada.
- Formato e tamanho precisam ser suportados. Fique com formatos web comuns e dimensões razoáveis. Um TIFF de 40 MB é uma sessão de depuração esperando para acontecer.
Se sua imagem estiver em armazenamento privado, gere uma URL assinada de curta duração no momento da requisição em vez de tentar tornar o bucket público.
Diferenças práticas em relação ao caminho de texto
- O papel do prompt muda de descrever a cena para descrever o movimento.
- A validação ganha uma etapa de busca do recurso, o que introduz toda uma nova classe de falhas (veja a seção de depuração).
- A composição da saída fica restrita à proporção da imagem de origem, o que afeta o planejamento do layout a jusante.
Teste a URL da imagem no navegador primeiro. Se ela não carregar de forma limpa para você, também não carregará para o serviço.
Chamar a API com curl e Python
Faça a mesma requisição funcionar em dois lugares: no terminal (para iteração rápida e visibilidade do bruto) e na sua base de código (para uso real).
curl
curl -sS https://api.hiapi.ai/v1/chat/completions \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-omni-flash/text-to-video",
"prompt": "Plano de avanço lento por uma rua de neon molhada pela chuva à noite, cinematográfico"
}'
Troque a string model por gemini-omni-flash/image-to-video e adicione o campo image para atingir o outro endpoint — nada mais precisa mudar.
Use -sS para que erros não sejam engolidos silenciosamente; ao inspecionar a resposta, canalize por um formatador JSON para tornar os campos aninhados legíveis.
Python
import os
import requests
BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": "Plano de avanço lento por uma rua de neon molhada pela chuva à noite, cinematográfico",
}
resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())
Dois detalhes que vale a pena copiar: leia a chave de uma variável de ambiente e defina um timeout suficientemente generoso. A geração de vídeo não é uma requisição instantânea — o timeout padrão de 10 segundos produz falhas falsas que parecem erro da API, mas são apenas seu cliente desistindo cedo demais.
Para imagem para vídeo, adicione uma linha:
payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"
Ao receber um status diferente de 2xx, sempre imprima ou registre o corpo bruto da resposta antes de lançar a exceção. O texto do erro normalmente aponta diretamente o campo problemático.
Organizar o código da sua integração
Depois que os dois caminhos funcionarem, é tentador deixar na base de código duas funções quase idênticas. Uma estrutura um pouco melhor custa quase nada e se paga no momento em que você adicionar um segundo modelo de vídeo.
Dois componentes compartilhados
Um construtor de requisições. Uma função que recebe parâmetros no nível da intenção e retorna o dicionário de carga:
def build_video_payload(prompt, image_url=None, duration=None):
if image_url:
payload = {
"model": "gemini-omni-flash/image-to-video",
"prompt": prompt,
"image": image_url,
}
else:
payload = {
"model": "gemini-omni-flash/text-to-video",
"prompt": prompt,
}
if duration:
payload["duration"] = duration
return payload
A escolha do endpoint passa a ser resultado de "tenho uma imagem?", o que corresponde à decisão real de produto. Quem chama nunca toca diretamente no ID do modelo.
Um manipulador de respostas. Uma função que trata separadamente erros de transporte, erros de carga e falhas no nível do modelo, e retorna um objeto de resultado normalizado (status, referência do vídeo, corpo bruto da resposta para logs). Todos os chamadores passam por ele, então a semântica de erro é consistente entre os dois endpoints.
Por que vale a pena fazer assim
- O ID do modelo muda em um único lugar. Quando você migrar para um modelo de vídeo diferente, basta editar o construtor, não quinze pontos de chamada.
- Tratamento de erro consistente. Falhas de busca de imagem e falhas de validação de prompt aparecem da mesma forma na sua UI.
- Testável sem rede. O construtor é uma função pura; você pode testar a estrutura da carga em testes unitários a baixo custo.
- Visibilidade de cobrança. Como vídeo é cobrado pela saída gerada, um manipulador único é o lugar natural para registrar duração e tamanho da saída a fim de acompanhar custos.
Mantenha o construtor enxuto. A lógica de negócio sobre o que gerar pertence a quem chama; o construtor só precisa saber como expressar essa intenção no formato da API.
Depurar falhas comuns de requisição
Quase todas as falhas iniciais se encaixam em uma de três categorias. Identifique a categoria primeiro e depois corrija.
Categoria 1: estrutura da requisição
Sintoma: retorno 4xx imediato, mensagem de erro citando campos ausentes ou desconhecidos, ou reclamação de JSON malformado.
Verifique nesta ordem:
- O JSON é válido? Cole o corpo da requisição em um linter. Uma vírgula final deixada por edição manual da carga é o problema clássico.
- O ID do modelo está exatamente igual?
gemini-omni-flash/text-to-videoegemini-omni-flash-text-to-videonão são a mesma string. Um erro de digitação aqui produz um erro de "modelo não encontrado" que parece problema de autenticação. - Os cabeçalhos estão completos? Tanto
AuthorizationquantoContent-Type: application/jsondefinidos. - O modelo corresponde ao endpoint? Enviar o campo
imagepara o endpoint de texto não dará o resultado que você quer — o campo será rejeitado ou ignorado e, em ambos os casos, você obtém um resultado errado.
Categoria 2: recurso de entrada (apenas caminho de imagem)
Sintoma: a requisição é aceita, mas falha durante o processamento, ou o erro menciona busca ou decodificação da imagem.
Verifique:
- Abra a URL da imagem em uma janela de navegador privado sem cookies. Se não carregar para você, também não carregará para o serviço.
- Confirme que a URL não é um endereço localhost, um host de rede privada ou um link assinado expirado.
- Confirme que o formato é um formato web comum e o tamanho do arquivo é razoável.
- Confirme que a resposta é realmente uma imagem — uma CDN que retorna status 200 com uma página de erro HTML no corpo é uma armadilha surpreendentemente comum.
Categoria 3: a própria chamada ao modelo
Sintoma: a requisição é válida, o recurso está acessível, mas a geração falha ou é recusada — geralmente relacionada a política de conteúdo ou capacidade.
Verifique:
- Reduza para o prompt mínimo e tente de novo. Se funcionar, seu prompt era a variável.
- Verifique se o timeout do cliente é longo o suficiente — nos logs, um timeout de cliente parece exatamente uma falha do servidor, a menos que você confira se alguma resposta chegou.
- Ative logs completos de requisição/resposta (com a chave mascarada), para distinguir as três categorias de problema de relance.
Ordem de depuração eficaz
Carga mínima → validar → adicionar imagem → validar → adicionar parâmetros opcionais um a um → validar. Quando algo quebrar, a última mudança que você fez é a culpada. Contanto que você mantenha a disciplina de depurar uma variável por vez, a maior parte da dor de integração desaparece.
Comece pela chamada mínima funcional de cada endpoint, envolva-a com o construtor e o manipulador compartilhados e então expanda gradualmente — esse caminho mantém texto para vídeo e imagem para vídeo previsíveis à medida que a integração cresce.
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