Blogue

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

Nov 9, 2026
Uma capa geométrica de prismas divididos em tons de sálvia e verde-pinheiro profundo, marcando a capa do artigo.
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:

  1. 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á.
  2. Especifique a câmera. Fixa, panorâmica, avanço, na mão — a linguagem de câmera elimina muita ambiguidade.
  3. 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:

  1. 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.
  2. O ID do modelo está exatamente igual? gemini-omni-flash/text-to-video e gemini-omni-flash-text-to-video nã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.
  3. Os cabeçalhos estão completos? Tanto Authorization quanto Content-Type: application/json definidos.
  4. O modelo corresponde ao endpoint? Enviar o campo image para 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:

  1. 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.
  2. Confirme que a URL não é um endereço localhost, um host de rede privada ou um link assinado expirado.
  3. Confirme que o formato é um formato web comum e o tamanho do arquivo é razoável.
  4. 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:

  1. Reduza para o prompt mínimo e tente de novo. Se funcionar, seu prompt era a variável.
  2. 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.
  3. 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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API