HiAPI
Blogue

Tutorial

Como chamar o gemini-omni-1.1-flash pela API HiAPI: guia com curl e Python

Nov 17, 2026
Imagem de capa em estilo arquitetônico abstrato: planos de concreto cinza-quente se entrecruzam sob a luz solar oblíqua, com sombras em azul-ardósia e finas juntas em tom de sálvia.
Nesta página

O que é preciso preparar antes da primeira requisição

Antes de escrever qualquer código, confirme quatro coisas. Cada uma delas pode poupar uma rodada de depuração.

Uma chave de API

Toda requisição à HiAPI precisa ser autenticada com uma chave de API. Gere uma no console da sua conta e certifique-se de que ela não vai para o controle de versão. Os exemplos abaixo a leem de uma variável de ambiente, para que a chave não apareça no histórico do shell nem em arquivos commitados:

export HIAPI_API_KEY="your_key_here"

URL base e caminho do endpoint

A URL base é a mesma para todos os modelos da HiAPI; apenas o identificador do modelo muda. Obtenha o caminho do endpoint e o método da requisição na documentação de referência da API, não de um artigo de blog, porque os caminhos são versionados e podem mudar. Mantenha a URL base como uma constante no seu cliente, assim futuras mudanças exigem alterar apenas uma linha.

Identificador do modelo

gemini-omni-1.1-flash é passado como string no payload da requisição. Copie exatamente — hífens e o sufixo de versão importam. Se houver erro de digitação, o erro geralmente é uma falha de validação e não uma falha de roteamento, o que confunde; veja a seção de depuração mais adiante.

Favorite a página do modelo

A página do modelo gemini-omni-1.1-flash é a fonte autoritativa para saber quais parâmetros existem, quais valores são aceitos e como é a estrutura da resposta. Trate-a como referência a conferir antes de cada alteração, e não como algo que se lê uma vez e se esquece.

Com esses quatro itens prontos, você já pode fazer a chamada.

Enviar uma requisição mínima com curl

Comece com a requisição o menor possível. O objetivo não é produzir um bom resultado — é provar que sua chave, seu endpoint e a estrutura do payload estão corretos. Depois que funcionar, cada alteração seguinte será incremental.

curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.1-flash",
    "input": {
      "prompt": "A câmera se aproxima lentamente de uma caneca de cerâmica sobre uma mesa de madeira, sob a luz suave da manhã"
    }
  }'

O significado de cada parte:

  • Método e URL — a chamada é um POST para o caminho do endpoint obtido na documentação de referência da API, prefixado com sua URL base.
  • Cabeçalho Authorization — carrega o token bearer. Variável ausente ou vazia aqui é a causa mais comum de 401.
  • Cabeçalho Content-Type — deve ser application/json. Sem ele, o servidor pode nem interpretar o corpo da requisição.
  • model — a string exata do identificador do modelo.
  • input — um objeto com os parâmetros de geração. O prompt fica aqui; resolução e duração também são adicionadas aqui, conforme detalhado abaixo.

Se a chamada retornar um identificador de tarefa ou uma resposta de estado aceito em vez da saída final, isso é normal — a geração é assíncrona. Guarde esse identificador; ele será usado na etapa de polling.

Portar a mesma chamada para Python

A versão em Python deve enviar exatamente o mesmo corpo JSON. Manter o payload idêntico é o que torna o porte confiável: se o curl funcionar e o Python não, o problema está no seu código Python, não no seu entendimento da API.

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"

payload = {
    "model": "gemini-omni-1.1-flash",
    "input": {
        "prompt": "A câmera se aproxima lentamente de uma caneca de cerâmica sobre uma mesa de madeira, sob a luz suave da manhã"
    },
}

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

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())

Alguns hábitos valem a pena ser adquiridos imediatamente:

  • Construa a URL com constantes, em vez de espalhar concatenações de strings pelo código.
  • Defina timeouts explícitos. Sem isso, uma requisição travada pode deixar o worker suspenso indefinidamente.
  • Chame raise_for_status(), para que respostas de erro sejam expostas como exceções, em vez de serem interpretadas silenciosamente como corpo de resposta de sucesso.
  • Serialize com json.dumps, não dependa de form encoding, que não gera corretamente o objeto aninhado input.

Depois que funcionar, você terá uma estrutura de requisição reutilizável. As duas próximas seções adicionam os parâmetros que realmente controlam a saída.

Configurar resolução e duração na requisição

Resolução e duração são campos comuns dentro do objeto input, lado a lado com o prompt. Conceitualmente, o payload é assim:

{
  "model": "gemini-omni-1.1-flash",
  "input": {
    "prompt": "...",
    "resolution": "<supported-value>",
    "duration": "<supported-value>"
  }
}

Regra essencial: não codifique esses valores de memória nem a partir de um tutorial lido meses atrás. Os valores suportados mudam com as atualizações do modelo, e enviar um valor não suportado gera erros de validação que parecem erros de payload. Antes de defini-los, sempre confirme os valores atualmente aceitos na página do modelo.

Um padrão prático

Coloque os valores na configuração, não no código:

payload = {
    "model": "gemini-omni-1.1-flash",
    "input": {
        "prompt": prompt,
        "resolution": settings.resolution,
        "duration": settings.duration,
    },
}

Isso traz três benefícios. Você pode ajustar a qualidade da saída sem mudar a lógica. Pode rodar testes baratos em baixa resolução durante o desenvolvimento e aumentar apenas na renderização final. Quando a plataforma adicionar valores suportados, você muda apenas um campo de configuração, sem vasculhar a base de código.

Há ainda duas armadilhas mais sutis que vale a pena apontar. Primeiro, resolução e duração geralmente estão relacionadas ao custo — a cobrança costuma acompanhar o que é produzido, então clipes mais longos e de maior resolução não são gratuitos. Segundo, se um campo for opcional, omita-o em vez de enviar string vazia ou null; alguns validadores rejeitam null explícito mesmo quando o campo em si é opcional.

Lidar com geração assíncrona: primeiro enviar, depois consultar

A geração leva tempo, então a API usa o padrão de enviar e depois consultar. Seu cliente deve tratar esses dois passos como operações distintas, com semânticas de retry diferentes.

Passo 1: enviar

A chamada de envio é a requisição que você já montou. Ela retorna o identificador da tarefa — dependendo do endpoint, pode ser um task ID, um job ID ou um campo semelhante. Faça o parse de forma defensiva:

created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
    raise RuntimeError(f"No job identifier in response: {created}")

Passo 2: consultar

Em seguida, use esse identificador para consultar o endpoint de status até a tarefa atingir um estado terminal. Um loop robusto tem quatro características: tempo máximo de espera, backoff, verificação de estado terminal e verificação de falha.

import time

def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
    deadline = time.time() + timeout
    delay = initial_delay
    while time.time() < deadline:
        status = fetch_status(job_id)          # GET no endpoint de status
        state = status.get("status")
        if state in ("succeeded", "completed"):
            return status
        if state in ("failed", "error", "cancelled"):
            raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
        time.sleep(delay)
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

Por que esses detalhes importam

  • Backoff exponencial evita bombardear o endpoint de status com uma tarefa que ainda está na fila e que leva um minuto para renderizar.
  • Prazo final rígido impede que uma tarefa travada bloqueie um worker para sempre. Ao atingir o timeout, registre o ID da tarefa para inspeção manual.
  • Estados terminais explícitos significam que você nunca entra em loop infinito em um estado inesperado. Trate estados desconhecidos como "continue esperando", mas registre um log.
  • Políticas de retry separadas: repetir a chamada de envio é mais arriscado do que repetir a chamada de status, porque pode criar tarefas duplicadas. Pode repetir o polling com segurança; repita o envio apenas em erros de transporte claros.

Diagnosticar modos de falha comuns

A maioria das falhas cai em poucas categorias. Investigue nesta ordem, porque sintomas posteriores costumam ser causados por problemas anteriores.

Erros de autenticação

Sintoma: 401 ou 403. Verifique primeiro: a chave realmente existe no ambiente em que o processo roda? Imprimir len(API_KEY) pega o caso clássico de variável não definida que deixa o token bearer vazio. Depois confirme que o formato do cabeçalho é Bearer <key>, com apenas um espaço no meio, e que a chave não foi revogada nem restrita a outro projeto.

Erros de formato do payload

Sintoma: 400 reclamando do corpo da requisição ou de campos ausentes. Verifique primeiro: compare seu corpo de requisição com a requisição curl que funciona. Causas comuns incluem falta do cabeçalho Content-Type: application/json, envio de dados form-encoded em vez de JSON, objeto input achatado quando a API espera aninhamento (ou o contrário), e conversões de tipo inesperadas — uma duração numérica enviada como string entre aspas pode falhar na validação.

Valores de parâmetro não suportados

Sintoma: 400 ou 422 apontando um campo específico, como resolution ou duration. Verifique primeiro: a página do modelo, que lista os valores atualmente suportados. Quase sempre é um valor hardcoded desatualizado, não um defeito no código. Se um valor que funcionava antes agora falha, assuma primeiro que o modelo foi atualizado e releia a documentação, antes de assumir falha do serviço.

Erro de digitação no identificador do modelo

Sintoma: erro de validação ou de recurso não encontrado, sem menção ao seu prompt. Verifique primeiro: imprima a string de model e compare caractere por caractere com a documentação. Um espaço extra no final ou a ordem de versão invertida passam facilmente despercebidos.

Timeouts e falhas transitórias

Sintoma: timeout de conexão, 429 ou respostas 5xx. Verifique primeiro: você definiu timeouts? Adicione timeouts e então adicione retries limitados com backoff apenas para 429 e 5xx — não repita erros 4xx além de 429, porque a requisição falhará da mesma forma toda vez. Para tarefas longas, lembre-se de que o resultado final é obtido por polling; timeout na chamada de envio não significa falha na geração.

Tecnicamente válido, mas o resultado não é o esperado

A requisição foi bem-sucedida, mas a saída não atingiu o esperado. Isso é um problema de prompt, não de API. Torne o prompt específico quanto a sujeito, movimento de câmera, iluminação e ritmo, e altere apenas uma variável por vez para atribuir diferenças.

Encapsular em uma função de cliente reutilizável

O objetivo do encapsulamento é simples: sua lógica de negócio não deve conter identificadores de modelo, nomes de parâmetros nem loops de polling. Todos os detalhes específicos do modelo ficam concentrados em um único lugar.

def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
    payload = {
        "model": "gemini-omni-1.1-flash",
        "input": {"prompt": prompt},
    }
    if resolution is not None:
        payload["input"]["resolution"] = resolution
    if duration is not None:
        payload["input"]["duration"] = duration

    created = post_json(ENDPOINT, payload)
    job_id = created.get("id") or created.get("job_id")
    if not job_id:
        raise RuntimeError(f"No job identifier: {created}")

    return wait_for_job(job_id, timeout=timeout)

O que isso traz para você

  1. Trocar de modelo exige uma linha. Quando chega um modelo mais novo, você muda a constante e os parâmetros padrão; os pontos de chamada não são afetados.
  2. Parâmetros opcionais são tratados corretamente. Valores omitidos não são enviados, evitando o problema de rejeição de null descrito antes.
  3. O polling fica invisível para quem chama. Quem chama recebe o resultado ou uma exceção, nunca um task ID que precisa gerenciar sozinho.
  4. Testes ficam fáceis. Você pode mockar post_json e wait_for_job separadamente, isolando o teste da construção do payload e da lógica de polling.

Organização em camadas

Mantenha a estrutura plana e explícita: camada de transporte (HTTP, cabeçalhos, timeouts, retries), camada de modelo (construção do payload para gemini-omni-1.1-flash) e camada de tarefa (envio e polling). Uma única função generate_video compõe tudo, e cada camada é pequena o suficiente para raciocinar sobre ela quando algo dá errado.

Primeiro use curl para confirmar a configuração de conexão, depois passe para Python para o trabalho real, releia a página do modelo sempre que os parâmetros mudarem, e coloque o loop de polling atrás de uma interface, para que ele nunca vaze para o código da aplicação.

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