# Gemini family API: model IDs, choosing an endpoint, examples and common errors

Source: https://ofox.io/docs/develop/models/gemini

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](https://ofox.io/docs/develop/models/gemini/thinking) — Thinking is on by default; how to reduce it when responses are slow.
- [Google Search](https://ofox.io/docs/develop/models/gemini/grounding) — Fetch real-time information from the web and return sources.
- [PDF & audio](https://ofox.io/docs/develop/models/gemini/multimodal) — Upload documents and audio for analysis.
- [Troubleshooting errors](#errors) — Truncated responses, retired models, context exceeded.
- [Use in Gemini CLI](https://ofox.io/docs/integrations/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](https://ofox.io/models?provider=google), or query the [Models API](https://ofox.io/docs/api/openai/models). For image generation models, see [Nano Banana](https://ofox.io/docs/develop/models/nano-banana).

**Common model IDs (copy them exactly)**

- Gemini 3.8 Flash: `google/gemini-3.8-flash`
- Gemini 3.1 Pro Preview: `google/gemini-3.1-pro-preview`
- Gemini 3.5 Flash-Lite: `google/gemini-3.5-flash-lite` — No thinking by default; fast responses
- Gemini 3.5 Flash: `google/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 point**:Use 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](https://ofox.io/docs/develop/models/gemini/thinking) | `thinkingConfig`; can return thought summaries | `reasoning_effort` or `reasoning`; returns `reasoning_details` |
| [Google Search](https://ofox.io/docs/develop/models/gemini/grounding) | `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](https://ofox.io/docs/api/gemini/generate-content).

## Examples

**Python (google-genai)**

```python filename="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**

```bash filename="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)**

```python filename="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](https://ofox.io/docs/develop/advanced/gemini-explicit-cache) |

## Common errors

**Key point**:A 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](https://ofox.io/docs/develop/guides/error-handling).

## Official docs
- [Gemini API · Models](https://ai.google.dev/gemini-api/docs/models)
- [Gemini API · Thinking](https://ai.google.dev/gemini-api/docs/thinking)
- [Gemini API · Google Search](https://ai.google.dev/gemini-api/docs/google-search)
- [Gemini API · Structured output](https://ai.google.dev/gemini-api/docs/structured-output)
- [Gemini API · OpenAI compatibility](https://ai.google.dev/gemini-api/docs/openai)

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.