Família Gemini

Os modelos de texto Gemini do Google, principalmente a série Gemini 3.x. Podem ser chamados pelo endpoint nativo do Gemini (o SDK oficial google-genai funciona diretamente) ou pelo endpoint compatível com OpenAI.

Tarefas comuns

Controlar o thinking O thinking vem ativado por padrão; como reduzi-lo quando demora demais.Pesquisa Google Buscar informações em tempo real na web e retornar as fontes.PDF e áudio Enviar documentos e áudio para análise.Solução de erros Resposta truncada, modelo descontinuado, contexto excedido.Usar no Gemini CLI Configuração e perguntas frequentes.

Modelos

Aceitam entrada de texto, imagem, áudio e PDF, com contexto de cerca de 1M tokens. A lista completa de modelos e os preços atualizados estão na página de modelos ; também é possível consultá-los pela Models API. Os modelos de geração de imagens estão em Nano Banana.

IDs de modelo comuns (copie exatamente como estão)

Gemini 3.8 Flashgoogle/gemini-3.8-flash

Gemini 3.1 Pro Previewgoogle/gemini-3.1-pro-preview

Gemini 3.5 Flash-Litegoogle/gemini-3.5-flash-liteSem thinking por padrão; resposta rápida

Gemini 3.5 Flashgoogle/gemini-3.5-flash

O prefixo google/ do ID de modelo pode ser omitido. No endereço do endpoint nativo, o prefixo também é opcional: tanto models/google/gemini-3.8-flash:generateContent quanto models/gemini-3.8-flash:generateContent funcionam.

Escolha do endpoint

ResumoPara controlar o thinking em detalhe ou obter as fontes da Pesquisa Google, use o endpoint nativo do Gemini.

	Endpoint nativo do Gemini (recomendado)	Endpoint compatível com OpenAI
Endereço	`POST https://api.ofox.ai/gemini/v1beta/models/<ID do modelo>:generateContent`	`POST https://api.ofox.ai/v1/chat/completions`
SDK	`google-genai`, com `base_url` `https://api.ofox.ai/gemini`	SDK da OpenAI, com `base_url` `https://api.ofox.ai/v1`
Autenticação	`x-goog-api-key: <Key>`; também aceita `Authorization: Bearer <Key>`	`Authorization: Bearer <Key>`
Streaming	`:streamGenerateContent?alt=sse`	`"stream": true`
Thinking	`thinkingConfig`; pode retornar resumos do thinking	`reasoning_effort` ou `reasoning`; retorna `reasoning_details`
Pesquisa Google	`tools: [{"google_search": {}}]`; retorna fontes e termos de busca	`web_search_options`; retorna apenas a resposta

O endpoint nativo não aceita a Key pelo parâmetro de URL ?key=, que retorna 401. Use o cabeçalho.

Atualmente, os modelos Gemini são oferecidos pelo Google Vertex AI (google_vertex). Os parâmetros completos de requisição estão em Generate Content.

Exemplos de chamada

Python (google-genai)

gemini_basic.py


import os
from google import genai
 
client = genai.Client(
    api_key=os.environ["OFOX_API_KEY"],
    http_options={"api_version": "v1beta", "base_url": "https://api.ofox.ai/gemini"},
)
 
resp = client.models.generate_content(
    model="google/gemini-3.8-flash",
    contents="Explique em uma frase o que é idempotência.",
)
print(resp.text)

cURL

Terminal


curl "https://api.ofox.ai/gemini/v1beta/models/google/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explique em uma frase o que é idempotência."}]}]
  }'

Python (SDK da OpenAI)

gemini_openai_sdk.py


import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.ai/v1", api_key=os.environ["OFOX_API_KEY"])
 
resp = client.chat.completions.create(
    model="google/gemini-3.8-flash",
    messages=[{"role": "user", "content": "Explique em uma frase o que é idempotência."}],
)
print(resp.choices[0].message.content)

Cache de prompt

O Gemini faz cache implícito automaticamente: quando o prefixo da requisição coincide com o de requisições recentes e é longo o suficiente, a parte em cache é cobrada pelo preço de leitura de cache, sem alterações na requisição.

Item	Descrição
Confirmar acerto	No endpoint nativo, `usageMetadata.cachedContentTokenCount` é maior que 0; no endpoint compatível com OpenAI, `usage.prompt_tokens_details.cached_tokens` é maior que 0
Estabilidade	O cache implícito é de melhor esforço; requisições com o mesmo prefixo podem não acertar o cache
Cache determinístico	Para reutilizar de forma estável grandes blocos de conteúdo, use o cache explícito; consulte Cache explícito do Gemini

Erros comuns

ResumoUma resposta cortada no meio geralmente significa que o thinking consumiu a cota de saída. Não é um erro: verifique o finishReason.

HTTP · status	Mensagem de erro original	Causa	Solução
200, `finishReason: "MAX_TOKENS"`	—	O tamanho total do thinking e da resposta atingiu `maxOutputTokens`, e a resposta foi truncada	Aumente `maxOutputTokens` ou reduza o thinking com `thinkingLevel: "low"`. No endpoint compatível com OpenAI, aparece como `finish_reason: "length"`
400 `INVALID_ARGUMENT`	`The input token count exceeds the maximum number of tokens allowed 1048576.`	A entrada excede o contexto do modelo	Reduza a entrada
410 `model_deprecated`	`Model 'google/gemini-3-pro-preview' is deprecated and no longer accepts requests; please switch to an active model`	O modelo em versão preview foi descontinuado	Use a versão estável ou uma preview mais nova, como `google/gemini-3.1-pro-preview`
404 `model_not_found`	`Model 'google/gemini-9-pro' not found`	ID do modelo digitado incorretamente	Copie o ID do modelo desta página
401	—	Key enviada por `?key=`	Use o cabeçalho `x-goog-api-key`
Timeout da requisição	—	O thinking vem ativado por padrão, e perguntas complexas demoram	Use streaming, defina o timeout do cliente em 300 segundos ou mais, ou reduza o thinking

Outros erros gerais estão em Tratamento de erros.

Documentação oficial

A documentação oficial descreve o comportamento das chamadas diretas ao Google. Ao chamar pela OfoxAI, prevalecem os IDs de modelo e os endereços de endpoint desta página.

Perguntas frequentes

Como escrever o ID de modelo do Gemini?

O formato padrão é google/gemini-3.8-flash; também é possível omitir o prefixo google/. No endereço do endpoint nativo, o prefixo também é opcional.

O que fazer quando o Gemini responde muito devagar?

Exceto o Flash-Lite, o Gemini vem com thinking ativado por padrão, e perguntas complexas podem levar mais de 1 minuto. Envie thinkingLevel: "low" para reduzir o thinking, envie thinkingBudget: 0 para desativá-lo em alguns modelos ou use um modelo Flash-Lite, que não faz thinking por padrão.

Como desativar o thinking do Gemini?

No 3.5 Flash e no 3 Flash Preview, envie thinkingBudget: 0 para desativar o thinking; no 3.1 Pro Preview e no 3.8 Flash, não é possível desativá-lo completamente, mas thinkingLevel: "low" reduz o thinking. A série Flash-Lite não faz thinking por padrão.

A resposta do Gemini foi truncada com finishReason igual a MAX_TOKENS?

Os tokens de thinking também contam em maxOutputTokens. Aumente maxOutputTokens ou reduza o thinking.

O Gemini pode fazer buscas na web?

Sim. No endpoint nativo, adicione {"google_search": {}} em tools; o groundingMetadata da resposta traz os termos de busca e as fontes. No endpoint compatível com OpenAI, envie web_search_options: {}.

Como autenticar no endpoint nativo do Gemini?

Envie a API Key da OfoxAI pelo cabeçalho x-goog-api-key; Authorization: Bearer também é aceito. O parâmetro de URL ?key= não é suportado.

Erro 410 model_deprecated?

Esse modelo em versão preview foi descontinuado, como o gemini-3-pro-preview. Use google/gemini-3.1-pro-preview ou um modelo em versão estável.

O Gemini consegue analisar áudio e PDF?

Sim. No endpoint nativo, envie o arquivo codificado em base64 por inline_data; no endpoint compatível com OpenAI, use o bloco de conteúdo file para PDF e o bloco de conteúdo input_audio para áudio.