Como usar o gemini-omni-1.2-flash com a API HiAPI: curl e Python

Como é uma requisição ao gemini-omni-1.2-flash

Antes de escrever a primeira linha de código, é útil entender exatamente do que uma chamada ao gemini-omni-1.2-flash é composta na HiAPI. Cada requisição que você envia é um objeto JSON, entregue a um único endpoint e autenticado com sua chave de API da HiAPI. Essa estrutura é consistente entre os modelos, ou seja, uma vez que você a domine para este modelo, poderá reutilizar o mesmo padrão em outros contextos.

Em alto nível, uma requisição contém quatro tipos de informação:

• Identificador do modelo —— a string gemini-omni-1.2-flash, que informa à HiAPI para qual modelo rotear sua tarefa.
• Entrada —— o conteúdo que você deseja que o modelo processe. Dependendo da modalidade que você está usando, ela se apresenta como prompt ou campo de entrada estruturado.
• Parâmetros de geração —— opções que moldam a saída, como duração e resolução. São os botões que você ajustará ao longo deste guia.
• Metadados da requisição —— qualquer informação necessária para a plataforma identificar e rastrear sua tarefa, como uma referência do lado do cliente para correlação.

Estrutura da resposta

A previsibilidade da resposta é igualmente alta. Chamadas síncronas retornam o resultado diretamente no campo de resultado. Chamadas assíncronas retornam um handle de tarefa —— um identificador usado para consultar o status e, por fim, obter a saída. Saber desde cedo com qual dos dois você está lidando economiza muito tempo de depuração depois.

Por que a estrutura importa

A maioria das falhas de primeira integração tem origem na estrutura da requisição: campos ausentes, tipos de parâmetro errados ou a suposição de que a chamada é síncrona quando não é. Se você internalizar essa anatomia antes de escrever código, os exemplos em curl e Python a seguir serão meras traduções diretas, em vez de feitiços misteriosos.

Um hábito útil: guarde o corpo JSON exato que você envia em uma variável ou arquivo. Quando algo der errado, você quer ver exatamente o que foi enviado, em vez de reconstruí-lo de memória.

Autenticação em uma linha

Cada requisição carrega sua chave de API no cabeçalho de autorização. Trate a chave como um segredo: carregue-a a partir de uma variável de ambiente em vez de codificá-la diretamente, e nunca a envie ao controle de versão. Essa única disciplina evita o erro de segurança mais comum em integrações de API.

Envie sua primeira requisição funcional com curl

A forma mais rápida de confirmar que a chave, o endpoint e a estrutura da requisição estão corretos é uma chamada curl. Ela elimina cada camada de abstração entre você e a API, então, se funcionar, você sabe que o problema (se houver) está no seu código, não na configuração do seu ambiente.

Passo 1: Salve sua chave

Coloque a chave de API da HiAPI em uma variável de ambiente, para que ela não apareça no histórico do seu shell nem em scripts compartilhados:

export HIAPI_API_KEY="your_key_here"

Passo 2: Construa o corpo da requisição

Grave o corpo JSON em um arquivo. Isso mantém o comando curl legível e lhe dá um artefato reutilizável:

cat > request.json <<'EOF'
{
  "model": "gemini-omni-1.2-flash",
  "input": {
    "prompt": "Descreva o que você deseja que o modelo gere."
  },
  "parameters": {
    "duration": 5,
    "resolution": "720p"
  }
}
EOF

Os valores concretos dos parâmetros dependem do seu caso de uso; o que importa aqui é a estrutura. Na primeira chamada, mantenha duration e resolution moderados, para obter rapidamente e com baixo custo um sinal de que o pipeline funciona.

Passo 3: Envie a requisição

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json

Passo 4: Leia a resposta

Se a requisição for síncrona, você verá o resultado gerado no corpo da resposta. Se for assíncrona, receberá um handle de tarefa —— um ID de tarefa mais um campo de status. Anote esse ID; você precisará dele para o polling.

Se o seu terminal suportar, passe a saída por um formatador JSON ou salve-a em arquivo para inspeção cuidadosa:

curl -sS -X POST "https://api.hiapi.ai/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @request.json > response.json

Passo 5: Confirme antes de escalar

Não comece a ajustar duração, resolução ou processamento em lote antes que esta chamada bruta funcione e você consiga ler a saída. A primeira requisição bem-sucedida é sua linha de base; tudo depois disso são mudanças incrementais que você pode comparar com ela.

Porte a chamada para Python

Depois que o curl funcionar, portar para Python é um trabalho mecânico. O objetivo é escrever um cliente pequeno e legível que espelhe exatamente a requisição, para que, se a chamada Python falhar, você possa comparar campo a campo com a versão curl.

Um cliente mínimo

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/generate"

payload = {
    "model": "gemini-omni-1.2-flash",
    "input": {
        "prompt": "Descreva o que você deseja que o modelo gere."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720p"
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, json=payload, timeout=60)
response.raise_for_status()

data = response.json()
print(json.dumps(data, indent=2))

Pontos de atenção

• json=payload serializa o dicionário para você, e é por isso que o corpo fica idêntico ao do arquivo curl, em vez de ser uma string montada manualmente.
• raise_for_status() transforma respostas não 2xx em exceções, de modo que as falhas aparecem imediatamente, em vez de retornar silenciosamente um corpo de erro que você tentaria interpretar como resultado.
• timeout=60 impede que o script fique pendurado indefinidamente quando a conexão trava. Escolha um valor de acordo com o tempo que você espera que a geração leve.

Lide com os dois formatos de resposta

Como uma chamada pode retornar um resultado ou um handle de tarefa, ramifique o tratamento da resposta em vez de presumir um único formato:

if "job_id" in data:
    print("Tarefa assíncrona iniciada:", data["job_id"])
else:
    print("Resultado pronto")

Essa pequena verificação é a diferença entre um cliente que funciona nos dois modos e um que quebra na primeira vez que a plataforma decide que sua tarefa precisa rodar de forma assíncrona.

Coloque tudo em uma função

Envolva a chamada em uma função que receba prompt, duração e resolução como parâmetros. Assim, quando você começar a ajustar, rodar o mesmo código com parâmetros diferentes se torna trivial, e a estrutura da requisição fica definida em um só lugar.

Tarefas assíncronas e polling de resultados

Algumas requisições ao gemini-omni-1.2-flash terminam rápido o suficiente para retornar o resultado inline. Outras levam mais tempo e a HiAPI retorna um handle de tarefa. Sua integração precisa lidar com os dois casos, e é no caminho assíncrono que a maioria dos clientes frágeis quebra.

Identifique a resposta assíncrona

Uma resposta assíncrona contém um identificador de tarefa e um status. Em vez da saída concluída, você recebe uma promessa: o trabalho foi aceito e será processado. Sua tarefa é voltar para verificar.

Faça polling corretamente

A abordagem ingênua —— martelar o endpoint de status em um laço apertado while True —— tem duas desvantagens: desperdiça seu orçamento de limite de taxa e gera carga desnecessária na plataforma, sem que você receba o resultado mais rápido.

Um padrão melhor usa recuo de intervalo com limite máximo:

import time

def poll_job(job_id, base_delay=1.0, max_delay=10.0, max_wait=300.0):
    elapsed = 0.0
    delay = base_delay
    while elapsed < max_wait:
        status = get_job_status(job_id)
        if status["state"] == "succeeded":
            return status
        if status["state"] == "failed":
            raise RuntimeError(status.get("error", "job failed"))
        time.sleep(delay)
        elapsed += delay
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"job {job_id} did not finish in time")

Três regras do polling

• Comece pequeno e cresça devagar. Um intervalo inicial curto captura tarefas rápidas com baixo custo; dobrar até o limite evita verificar tarefas lentas com frequência excessiva.
• Sempre defina um tempo máximo de espera. Sem ele, uma tarefa travada pendura seu processo para sempre. Um timeout que lança exceção é muito melhor do que um travamento silencioso.
• Distinga sucesso, falha e pendente. Apenas dois deles devem interromper o laço, e apenas um deve retornar resultado.

Prefira webhooks quando disponíveis

Se sua carga for alta, fazer polling de cada tarefa não escala bem. Onde a HiAPI oferece callbacks de conclusão, use-os para receber resultados em vez de perguntar repetidamente. Para ferramentas interativas e scripts de baixo volume, o polling com recuo é perfeitamente suficiente.

De qualquer forma, trate o handle de tarefa como o identificador persistente do trabalho. Armazene-o, registre-o e use-o para reconciliar resultados mais tarde.

Escolha duração e resolução

Duração e resolução são os dois parâmetros que impactam mais diretamente sua saída —— e também sua fatura e o tempo de espera. Não há um valor único correto para nenhum deles; a escolha certa depende do que você está construindo. O importante é escolhê-los de forma consciente, em vez de copiar números de exemplos.

Duração

A duração controla o comprimento da saída gerada. Durações maiores lhe dão mais conteúdo, mas exigem mais poder de processamento para gerar, o que afeta tanto a latência quanto a forma como a requisição é cobrada (a cobrança é baseada na duração da saída). Algumas orientações práticas:

• Comece curto durante os testes. Uma duração breve prova que o pipeline funciona de ponta a ponta, sem perder tempo em cada iteração.
• Faça a duração corresponder ao propósito. Um clipe curto para pré-visualização ou miniatura não precisa do comprimento de uma entrega final.
• Não alongue por especulação. Gere o comprimento que você realmente vai usar; cortar depois não lhe traz nenhum benefício.

Resolução

A resolução controla a fidelidade da saída. Resolução mais alta significa mais detalhes e maior payload, com aumento correspondente no tempo de processamento e no custo. As compensações a ponderar:

• Pré-visualizações e trabalho de rascunho não precisam de alta resolução —— é uma verificação de correção, não o produto final.
• Entregas finais podem valer uma configuração mais alta, especialmente quando a saída é exibida em tamanho real.
• Banda e armazenamento também importam: saídas em alta resolução são mais pesadas para transferir e reter.

Ajuste uma variável por vez

Ao ajustar parâmetros, mude apenas um de cada vez e compare com sua chamada curl de linha de base. Alterar duração e resolução ao mesmo tempo impede atribuir mudanças de qualidade, latência ou custo a qualquer um deles. Mantenha uma pequena matriz registrando as configurações que você testou e o comportamento observado.

Raciocine sobre custo como uma fórmula, não um número

Como os preços ficam no painel de preços do site, trate o custo como uma função: o custo total escala com a duração da saída e, para resoluções mais altas, também com o tamanho da saída final e o volume de processamento. Seu trabalho é saber quais parâmetros movem essa função e então consultar o preço atual antes de comprometer volume de produção. Assim, suas estimativas continuam corretas mesmo se os preços mudarem.

Erros comuns e como corrigi-los

A maioria das falhas de primeira integração se enquadra em algumas poucas categorias. Verifique-as nesta ordem —— cada passo depende do anterior estar correto, então pular etapas fará você perseguir sintomas superficiais.

1. Estrutura da requisição

Sintoma: erros de validação, ou mensagens sobre campo ausente ou inesperado.

Correção: confirme que o corpo é JSON válido (vírgulas finais são o culpado clássico), confirme que o campo model é exatamente gemini-omni-1.2-flash e compare seu payload linha a linha com o exemplo curl funcional. Se o curl funcionar e o Python não, compare os dois corpos de requisição.

2. Parâmetros

Sintoma: erro apontando para duration ou resolution, ou tamanho de saída inesperado.

Correção: verifique os tipos (números onde devem ser números, strings onde devem ser strings) e confirme que os valores estão dentro das faixas aceitáveis. Se um parâmetro estiver sendo ignorado silenciosamente, confirme que ele está aninhado onde a API espera, e não no nível superior.

3. Autenticação

Sintoma: respostas 401 ou 403.

Correção: confirme que a chave está presente no cabeçalho Authorization com o prefixo Bearer, confirme que a variável de ambiente realmente contém um valor (uma string vazia parece muito com uma chave errada) e confirme que você não copiou espaços em branco ou aspas ao redor da chave. Se suspeitar de vazamento da chave, regenere-a.

4. Estado da tarefa

Sintoma: você faz polling e nunca vê sucesso, ou trata uma tarefa pendente como falha.

Correção: confirme que está consultando o ID de tarefa correto, confirme que o laço reconhece todos os estados (pending, running, succeeded, failed) e confirme que o tempo máximo de espera é longo o suficiente para tarefas realistas. Registre cada transição de estado, para ver onde está travando.

5. Limites de taxa e falhas transitórias

Sintoma: respostas 429 ou erros 5xx intermitentes.

Correção: recue e tente novamente com jitter, em vez de repetir imediatamente. Se estiver fazendo polling de muitas tarefas, reduza a concorrência. Erros transitórios são normais; clientes com retentativas inteligentes superam isso.

Uma disciplina de depuração

Quando algo der errado, mude apenas uma coisa e execute novamente a requisição o menor possível. Guarde o corpo bruto da resposta —— mensagens de erro geralmente apontam o campo ou a condição exata, e lê-las com atenção economiza mais tempo do que qualquer suposição.

Checklist de integração para produção

Um script que rodou uma vez no seu notebook não é uma integração. Antes de ir ao ar, preencha estas lacunas.

Retentativas com recuo

Envolva as chamadas de rede em uma política de retentativas que trate falhas transitórias —— timeouts, redefinições de conexão, respostas 429 e 5xx. Use backoff exponencial com jitter, limite o número de tentativas e nunca repita requisições que falharam na validação; repetir um corpo malformado só falha de novo mais devagar.

Defina timeouts em tudo

Defina timeouts explícitos para cada chamada HTTP. Distinga timeout de conexão e timeout de leitura, e garanta que o timeout da requisição de geração seja pelo menos tão longo quanto o tempo real de geração —— mas com um teto.

Implemente idempotência em torno das tarefas

Uma instabilidade de rede pode ocorrer entre o servidor aceitar sua requisição e você ver a resposta. Se repetir cegamente, você pode criar tarefas duplicadas. Anexe a cada requisição lógica uma referência gerada pelo cliente, para que você possa detectar e reutilizar uma tarefa existente em vez de criar outra, e armazene o handle de tarefa em armazenamento persistente com essa referência como chave.

Logs que respondem a perguntas

Registre, para cada requisição, o nome do modelo, os valores dos parâmetros (duração, resolução), o handle de tarefa, as transições de estado e a latência. Nunca registre chaves de API nem o conteúdo completo de prompts que possam conter dados sensíveis. Quando algo der errado às 3 da manhã, são esses logs que permitem reconstruir exatamente o que aconteceu.

Observabilidade e alertas

Acompanhe taxas de sucesso, distribuição de erros por tipo e latência de ponta a ponta, tanto de requisições quanto do ciclo de vida das tarefas. Alerte sobre taxas de erro sustentadas, não sobre falhas isoladas. Um painel que separa erros de validação de erros transitórios lhe diz imediatamente se você tem um bug ou se a rede está ruim.

Higiene de configuração

Coloque endpoint, nome do modelo e parâmetros padrão em configuração, em vez de espalhá-los pelo código. Carregue a chave de API de um gerenciador de segredos ou variável de ambiente. Se preços e limites forem relevantes para seu planejamento, consulte o painel de preços em vez de codificar números, pois eles mudam.

Percorra este checklist e sua integração com o gemini-omni-1.2-flash estará pronta para lidar com tráfego real, não apenas com o primeiro teste. Comece com a chamada curl funcional, porte para Python e construa a partir daí.