Gemini family

Google’s Gemini text models, centered on the Gemini 3.x series. They can be called through the Gemini-native API (the official google-genai SDK works directly) or the OpenAI-compatible API.

Common tasks

Control thinking Thinking is on by default; how to reduce it when responses are slow.Google Search Fetch real-time information from the web and return sources.PDF & audio Upload documents and audio for analysis.Troubleshooting errors Truncated responses, retired models, context exceeded.Use in Gemini CLI Setup and common questions.

Models

The models accept text, image, audio and PDF input, with a context of about 1M tokens. For the full model list and live prices, see the model page , or query the Models API. For image generation models, see Nano Banana.

Common model IDs (copy them exactly)

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-liteNo thinking by default; fast responses

Gemini 3.5 Flashgoogle/gemini-3.5-flash

You can omit the google/ prefix. The native API path also works with or without the prefix: both models/google/gemini-3.8-flash:generateContent and models/gemini-3.8-flash:generateContent are valid.

Choosing an endpoint

Key pointUse the Gemini-native API when you need fine-grained control over thinking or Google Search sources.

	Gemini-native API (recommended)	OpenAI-compatible API
Endpoint	`POST https://api.ofox.io/gemini/v1beta/models/<model ID>:generateContent`	`POST https://api.ofox.io/v1/chat/completions`
SDK	`google-genai`, with `base_url` set to `https://api.ofox.io/gemini`	OpenAI SDK, with `base_url` set to `https://api.ofox.io/v1`
Authentication	`x-goog-api-key: <Key>`; `Authorization: Bearer <Key>` is also accepted	`Authorization: Bearer <Key>`
Streaming	`:streamGenerateContent?alt=sse`	`"stream": true`
Thinking	`thinkingConfig`; can return thought summaries	`reasoning_effort` or `reasoning`; returns `reasoning_details`
Google Search	`tools: [{"google_search": {}}]`; returns sources and search queries	`web_search_options`; returns the answer only

The native API does not accept the key as a ?key= URL parameter; that returns 401. Use a request header.

Gemini models are currently served by Google Vertex AI (google_vertex). For the full request parameters, see Generate Content.

Examples

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.io/gemini"},
)
 
resp = client.models.generate_content(
    model="google/gemini-3.8-flash",
    contents="Explain idempotency in one sentence.",
)
print(resp.text)

cURL

Terminal


curl "https://api.ofox.io/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": "Explain idempotency in one sentence."}]}]
  }'

Python (OpenAI SDK)

gemini_openai_sdk.py


import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])
 
resp = client.chat.completions.create(
    model="google/gemini-3.8-flash",
    messages=[{"role": "user", "content": "Explain idempotency in one sentence."}],
)
print(resp.choices[0].message.content)

Prompt caching

Gemini applies implicit caching automatically: when a request’s prefix matches a recent request and is long enough, the cached portion is billed at the cache read rate, with no changes to your request.

Item	Details
Confirming hits	Native API: `usageMetadata.cachedContentTokenCount` greater than 0; OpenAI-compatible API: `usage.prompt_tokens_details.cached_tokens` greater than 0
Reliability	Implicit caching is best-effort; requests with the same prefix may still miss
Deterministic caching	To reuse large content reliably, use explicit caching — see Gemini explicit caching

Common errors

Key pointA response cut off midway usually means thinking used up the output budget. It is not an error; check finishReason.

HTTP · status	Error message	Cause	Fix
200, `finishReason: "MAX_TOKENS"`	—	Thinking plus the answer reached `maxOutputTokens` and the answer was truncated	Increase `maxOutputTokens`, or reduce thinking with `thinkingLevel: "low"`. On the OpenAI-compatible API this is `finish_reason: "length"`
400 `INVALID_ARGUMENT`	`The input token count exceeds the maximum number of tokens allowed 1048576.`	Input exceeds the model’s context window	Shorten the input
410 `model_deprecated`	`Model 'google/gemini-3-pro-preview' is deprecated and no longer accepts requests; please switch to an active model`	The preview model has been retired	Switch to a stable model or a newer preview, such as `google/gemini-3.1-pro-preview`
404 `model_not_found`	`Model 'google/gemini-9-pro' not found`	Model ID misspelled	Copy the model ID from this page
401	—	Key passed via `?key=`	Use the `x-goog-api-key` header instead
Request timeout	—	Thinking is on by default, and complex questions take longer	Use streaming, set the client timeout to 300 seconds or more, or reduce thinking

For other general errors, see Error Handling.

Official docs

The official docs describe behavior when calling Google directly. When calling through OfoxAI, model IDs and endpoints on this page take precedence.

FAQ

How do I write a Gemini model ID?

The standard format is google/gemini-3.8-flash; you can also omit the google/ prefix. The native API path works with or without the prefix as well.

What should I do if Gemini responds slowly?

Except for Flash-Lite, Gemini thinks by default, and complex questions can take more than a minute. Pass thinkingLevel: "low" to reduce thinking, pass thinkingBudget: 0 to turn it off on some models, or switch to a Flash-Lite model, which does not think by default.

How do I turn off Gemini thinking?

3.5 Flash and 3 Flash Preview accept thinkingBudget: 0 to turn thinking off. 3.1 Pro Preview and 3.8 Flash cannot turn it off completely; use thinkingLevel: "low" to reduce it. The Flash-Lite series does not think by default.

Why is the Gemini answer truncated with finishReason MAX_TOKENS?

Thinking tokens also count toward maxOutputTokens. Increase maxOutputTokens or reduce thinking.

Can Gemini search the web?

Yes. On the native API, add {"google_search": {}} to tools; groundingMetadata in the response contains the search queries and sources. On the OpenAI-compatible API, pass web_search_options: {}.

How do I authenticate with the Gemini-native API?

Pass your OfoxAI API key in the x-goog-api-key header; Authorization: Bearer is also accepted. The ?key= URL parameter is not supported.

What does 410 model_deprecated mean?

The preview model has been retired, e.g. gemini-3-pro-preview. Switch to google/gemini-3.1-pro-preview or a stable model.

Can Gemini analyze audio and PDFs?

Yes. On the native API, pass base64-encoded files via inline_data; on the OpenAI-compatible API, use a file content block for PDFs and an input_audio content block for audio.