Tutorial
Como usar gemini-omni-flash/text-to-video pela API HiAPI: guia com curl e Python
Nesta página
O que o endpoint faz e quando usá-lo
gemini-omni-flash/text-to-video é um endpoint de geração na HiAPI que transforma um prompt de texto — opcionalmente ancorado por uma imagem de primeiro frame — em um clipe curto. Você envia uma requisição, a HiAPI devolve uma tarefa consultável e, quando ela termina, você recebe uma URL de vídeo que pode baixar ou transmitir em streaming.
O endpoint é adequado nestes cenários:
- Clipes conceituais rápidos. Gerar teasers curtos de marketing, prévias de storyboard ou transições para redes sociais diretamente a partir de uma ou duas frases de descrição.
- Movimento guiado por imagem. Você já tem uma imagem estática — foto de produto, design de personagem, ilustração — e quer colocá-la em movimento, em vez de gerar a partir do zero.
- Geração em lote dentro de um pipeline. Como a geração é assíncrona, você pode enviar muitos trabalhos de uma vez a partir de um worker de backend e coletar os resultados depois, sem manter a conexão aberta.
Ele não é indicado para vídeos longos, edição precisa quadro a quadro ou reprodução determinística de um plano específico. Pense nele como um rascunho generativo rápido: custo baixo de iteração, suficiente para revisão e scriptável de ponta a ponta.
Tudo abaixo usa a mesma interface da HiAPI — uma chave de API, uma URL base, uma estrutura de requisição — então o código que você escreve aqui pode migrar para outros endpoints de geração sem reaprender autenticação ou polling.
Antes de enviar a primeira requisição
Quatro coisas precisam estar prontas antes da primeira chamada bem-sucedida.
1. Chave de API
Crie a chave na sua conta HiAPI e guarde-a em uma variável de ambiente, não no código-fonte:
export HIAPI_API_KEY="your_key_here"
2. URL base e caminho do endpoint
Todas as requisições vão para a URL base da HiAPI, com o identificador do modelo no caminho. Trate a URL base como uma única constante no código, para alterá-la em um só lugar:
export HIAPI_BASE_URL="https://api.hiapi.ai"
3. Corpo da requisição JSON
A requisição é um POST com Content-Type: application/json e o token bearer no cabeçalho Authorization. A menos que você forneça a imagem do primeiro frame via URL, não há codificação de formulário nem upload multipart.
4. Imagem do primeiro frame (opcional)
Se pretende guiar a geração por imagem, garanta primeiro que ela esteja acessível por uma URL HTTPS pública. Caminhos locais de sistema de arquivos não funcionam — a API busca a imagem no lado do servidor.
Uma dica prática de atenção a custos: o endpoint é cobrado pela saída que você gera — a faixa de resolução e a duração do clipe contam. Consulte o painel de preços da HiAPI para o valor unitário atual e confirme ali antes de escalar trabalhos em lote. O hábito importante é: prototipe com a configuração mínima e só aumente as configurações depois que o prompt produzir o resultado desejado.
Construindo a requisição de geração
Uma requisição contém conceitualmente três partes: o caminho do modelo, o prompt (e opcionalmente a imagem) e as opções de geração. A estrutura é assim:
{
"prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}
Prompt
O campo prompt carrega a descrição do plano. Escreva como notas de direção: sujeito, comportamento de câmera, iluminação e atmosfera. Verbos de movimento específicos (“slow dolly-in”, “camera pans left”, “steam curls upward”) orientam o resultado de forma mais confiável do que apenas empilhar adjetivos.
Primeiro frame opcional
O campo image é opcional. Omita-o e o modelo gera o clipe inteiro apenas a partir do texto. Inclua-o e o clipe começa nesse frame, com o prompt descrevendo o que deve acontecer em seguida. Esta é a maior alavanca de consistência: prompts puramente textuais reimaginam a cena a cada execução, enquanto um primeiro frame fixo mantém a composição estável ao longo de várias iterações.
Se fornecer ambos, garanta que sejam coerentes. Um primeiro frame de paisagem desértica combinado com um prompt sobre uma rua urbana na chuva produz resultados confusos — o modelo precisa reconciliar duas instruções contraditórias.
Onde ficam as opções
resolution, duration e audio ficam no nível superior do mesmo corpo JSON, junto com prompt e image. Não há um objeto options aninhado para memorizar. Mantenha o corpo plano e legível — isso torna o registro em logs e a comparação de requisições muito mais fáceis ao depurar trabalhos em lote.
Escolhendo resolução e duração
Dois parâmetros governam tanto a aparência da saída quanto o custo da tarefa: a faixa de resolução e a duração do clipe.
Faixas de resolução
A HiAPI expõe o endpoint em várias faixas de resolução. A faixa mais baixa é o padrão adequado durante o desenvolvimento do prompt — renderiza mais rápido e permite iterar a redação sem pagar por detalhes que você vai descartar. Quando o prompt produzir de forma confiável a composição desejada, suba de faixa para a renderização final.
Um fluxo de trabalho prático:
- Escreva o prompt na faixa mais baixa.
- Gere duas ou três variações e compare.
- Fixe o prompt e renderize novamente em uma faixa mais alta.
Duração do clipe
A duração é especificada em segundos, e o endpoint é desenhado em torno de clipes curtos. Mantenha a duração moderada: clipes curtos tornam cada tarefa mais rápida, o custo de repetir após falha menor e, se depois precisar de uma sequência mais longa, você pode emendar vários clipes. Se um plano precisa de oito segundos na tela, duas gerações de quatro segundos costumam ser mais fáceis de controlar do que uma geração longa.
Como isso se traduz no orçamento
O endpoint é cobrado pela saída que você produz — resolução mais alta e duração maior aumentam a saída faturável de cada tarefa. Como o preço é calculado por unidade de geração e as faixas mudam com o tempo, leia os números atualizados no painel de preços da HiAPI em vez de fixar uma expectativa no código. Uma regra de planejamento válida sob qualquer mudança de preço: multiplique o número esperado de tarefas pelo tamanho da saída, prototipe na configuração mínima e escale a resolução por último.
Controlando o áudio nativo
A flag audio determina se o vídeo retornado traz uma faixa de áudio nativa gerada junto com a imagem.
{
"prompt": "Rain hammering a tin roof, a door creaks open slowly",
"audio": true
}
O que muda quando ativado
Com audio: true, o modelo gera sons que combinam com a cena descrita no prompt — ambiência, texturas do ambiente e eventos sonoros sugeridos pela ação. O vídeo de saída vem com fluxo de áudio, então o arquivo que você baixa já está completo, sem necessidade de tratamento de efeitos sonoros separado.
O que muda quando desativado
Com audio: false, você recebe um vídeo sem som. Isso é adequado quando:
- Você vai sobrepor sua própria música ou narração ao clipe em um editor.
- O clipe é um elemento de fundo em uma composição maior.
- Você está iterando apenas a imagem e não quer a geração de áudio no ciclo.
Escrevendo prompts para áudio
Se ativar o áudio, descreva a paisagem sonora como descreve a imagem. Pistas sonoras no prompt — chuva, passos, ruído de máquinas, a atmosfera específica de um ambiente — dão base ao modelo de áudio. Prompts puramente visuais ainda geram áudio, mas será ambiência genérica, não um som que combina com o plano.
Uma ressalva que vale testar cedo: o áudio muda bastante o caráter do clipe. Gere o mesmo prompt uma vez com a flag ativada e outra desativada, assista aos dois e decida qual modo o projeto realmente precisa antes de montar trabalhos em lote em torno dele.
Lidando com o ciclo de vida da tarefa assíncrona
A geração de vídeo leva mais tempo do que uma requisição HTTP típica deve ficar aberta, então o endpoint é assíncrono. Cada chamada segue o mesmo ciclo de três passos.
Passo 1: enviar
Faça POST do corpo JSON para o endpoint. Um envio bem-sucedido retorna imediatamente um identificador de tarefa — normalmente o id da tarefa — e um status indicando que ela está na fila ou em processamento. Nada foi renderizado ainda neste ponto.
Passo 2: consultar
Com o id da tarefa em mãos, consulte o endpoint de status da tarefa em intervalos fixos. Cada consulta retorna o status atual: queued, processing, completed ou failed. Você precisa tratar os quatro estados. Um backoff exponencial simples — começando em cerca de dois segundos, com limite no intervalo — evita martelar a API em tarefas longas e ainda captura rapidamente as curtas.
Passo 3: obter
Quando o status reportar conclusão, a resposta traz a URL do vídeo finalizado e os metadados da tarefa. Baixe-a, armazene-a ou entregue a URL ao frontend. Se o status reportar falha, capture a mensagem de erro da resposta e decida se ajusta o prompt e tenta de novo ou expõe a falha.
Proteções que devem estar embutidas
- Limite de tempo total. Limite o tempo total de consulta (por exemplo, alguns minutos) e marque a tarefa como falha no seu próprio código, em vez de entrar em loop infinito.
- Número máximo de consultas. Evite loops descontrolados quando o status nunca fica claro.
- Persistência do id da tarefa. Grave-o em banco de dados ou log assim que o receber. Se o processo cair no meio da consulta, você pode retomar em vez de gerar de novo e pagar duas vezes.
- Envio idempotente. Não reenvie por instabilidade de rede antes de confirmar que a primeira requisição falhou; tarefas duplicadas consomem saída real.
Faça esse ciclo corretamente uma vez e ele serve para todos os endpoints assíncronos da HiAPI.
Exemplos executáveis em curl e Python
curl: enviar, consultar, obter
Defina a chave e a URL base a partir de variáveis de ambiente e envie:
curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
"image": "https://your-bucket.example.com/first-frame.jpg",
"resolution": "720p",
"duration": 5,
"audio": false
}'
A resposta contém o id da tarefa. Obtenha o endpoint de status a partir da resposta e consulte:
curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
-H "Authorization: Bearer $HIAPI_API_KEY"
Repita até o status ser completed, então extraia a URL do vídeo do corpo da resposta e baixe:
curl -sS -o clip.mp4 "<VIDEO_URL>"
Python: o mesmo ciclo, encapsulado
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}
def generate_video(prompt, image_url=None, resolution="720p",
duration=5, audio=False, timeout=300):
payload = {
"prompt": prompt,
"resolution": resolution,
"duration": duration,
"audio": audio,
}
if image_url:
payload["image"] = image_url
resp = requests.post(
f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
headers=HEADERS, json=payload, timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["id"]
print(f"submitted: {task_id}")
deadline = time.time() + timeout
interval = 2
while time.time() < deadline:
status_resp = requests.get(
f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
)
status_resp.raise_for_status()
data = status_resp.json()
state = data.get("status")
if state == "completed":
return data["video_url"]
if state == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
interval = min(interval * 1.5, 10)
raise TimeoutError(f"job {task_id} did not finish in {timeout}s")
if __name__ == "__main__":
url = generate_video(
"A slow dolly-in on a glass coffee cup as steam curls upward, "
"morning light, shallow depth of field",
)
print("video ready:", url)
O script envia uma tarefa apenas de texto, consulta com backoff, impõe um limite de tempo e retorna a URL final. Passe image_url= para ancorar a geração a um primeiro frame, ou defina audio=True para incluir som nativo. A partir daqui, você pode colocar generate_video em uma fila de workers, uma rota FastAPI ou um loop em lote — a função é autocontida e sem estado, exceto pelo id de tarefa que cria.
Pontos comuns de falha e como evitá-los
A maioria das integrações que falham tropeça em um destes cinco problemas.
Rejeição no envio por parâmetros inválidos
A causa mais comum é a API não conseguir interpretar o corpo da requisição: falta de prompt, duração fora do intervalo suportado ou string de resolução não suportada. Consulte a referência do endpoint para os valores aceitos e valide localmente antes. Uma pequena ferramenta que verifica valores permitidos antes da chamada economiza uma ida e volta e um erro confuso.
Imagem do primeiro frame inacessível
A API busca image no lado do servidor, então uma URL que funciona no navegador ainda pode falhar — buckets privados, links assinados que expiram e proteção contra hotlink causam isso. Use uma URL HTTPS publicamente legível e verifique que ela resolve fora da sua rede antes de enviar.
Desistir da consulta
Duas variações do mesmo erro: desistir ao receber a primeira resposta processing e assumir falha, ou consultar agressivamente demais e atingir limite de requisições. O ciclo com backoff e limite mostrado acima resolve os dois: consulte conforme o plano, trate estados não terminais como normais e só lance exceção em falha explícita ou timeout.
Perder o id da tarefa
Se o processo morrer depois do envio e antes de salvar o resultado, a tarefa já foi paga mas fica inacessível. Grave o id da tarefa em armazenamento persistente imediatamente após o envio e, na inicialização, verifique se ainda há ids em andamento antes de enviar novas tarefas.
Saída grande demais em escala
Gerar lotes grandes em resolução alta e com durações longas multiplica rapidamente o volume de saída, e os arquivos gerados custam caro para armazenar e são lentos de servir. Prototipe em pequena escala, renderize final uma vez e mantenha regras de ciclo de vida do armazenamento. Como a cobrança está ligada à saída gerada, a correção mais barata quase sempre é um ciclo de iteração de protótipo menor.
Percorra esta lista em um ambiente de pré-lançamento e seu caminho de produção ficará tranquilo.
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