# Gemini 系列 API：模型 ID、接口选择、调用示例与常见报错

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

Google 的 Gemini 文本模型，以 Gemini 3.x 系列为主。支持 **Gemini 原生接口**（官方 `google-genai` SDK 可直接使用）与 **OpenAI 兼容接口**两种调用方式。

## 常见任务

- [控制思考](https://ofox.io/zh/docs/develop/models/gemini/thinking) — 思考默认开启，耗时较长时如何降低思考量。
- [Google 搜索](https://ofox.io/zh/docs/develop/models/gemini/grounding) — 联网获取实时信息并返回来源。
- [PDF 与音频](https://ofox.io/zh/docs/develop/models/gemini/multimodal) — 上传文档、音频进行分析。
- [报错排查](#errors) — 回答被截断、模型已下线、超出上下文。
- [在 Gemini CLI 中使用](https://ofox.io/zh/docs/integrations/gemini-cli) — 接入配置与常见问题。

## 模型
支持文本、图片、音频与 PDF 输入，上下文约 1M token。完整的模型列表与实时价格请参阅[模型页](https://ofox.io/zh/models?provider=google)，也可通过 [Models API](https://ofox.io/zh/docs/api/openai/models) 查询。生图模型见 [Nano Banana](https://ofox.io/zh/docs/develop/models/nano-banana)。

**常用模型 ID（调用时原样复制）**

- 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` — 默认不思考，响应快
- Gemini 3.5 Flash: `google/gemini-3.5-flash`

模型 ID 可省略 `google/` 前缀。原生接口的地址中同样可以带或不带前缀，例如 `models/google/gemini-3.8-flash:generateContent` 与 `models/gemini-3.8-flash:generateContent` 均可。

## 接口选择

**要点**:需要精细控制思考、获取 Google 搜索来源时，请使用 Gemini 原生接口。

| | Gemini 原生接口（推荐） | OpenAI 兼容接口 |
|---|---|---|
| 地址 | `POST https://api.ofox.io/gemini/v1beta/models/<模型 ID>:generateContent` | `POST https://api.ofox.io/v1/chat/completions` |
| SDK | `google-genai`，`base_url` 为 `https://api.ofox.io/gemini` | OpenAI SDK，`base_url` 为 `https://api.ofox.io/v1` |
| 认证 | `x-goog-api-key: <Key>`，也接受 `Authorization: Bearer <Key>` | `Authorization: Bearer <Key>` |
| 流式 | `:streamGenerateContent?alt=sse` | `"stream": true` |
| [思考](https://ofox.io/zh/docs/develop/models/gemini/thinking) | `thinkingConfig`，可返回思考摘要 | `reasoning_effort` 或 `reasoning`，返回 `reasoning_details` |
| [Google 搜索](https://ofox.io/zh/docs/develop/models/gemini/grounding) | `tools: [{"google_search": {}}]`，返回来源与搜索词 | `web_search_options`，只返回回答 |

原生接口不支持通过 URL 参数 `?key=` 传入 Key，会返回 401，请使用请求头。

Gemini 模型目前由 Google Vertex AI（`google_vertex`）提供。完整的请求参数见 [Generate Content](https://ofox.io/zh/docs/api/gemini/generate-content)。

## 调用示例

**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="用一句话解释什么是幂等性。",
)
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": "用一句话解释什么是幂等性。"}]}]
  }'
```

**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": "用一句话解释什么是幂等性。"}],
)
print(resp.choices[0].message.content)
```

## 提示缓存
Gemini 自动进行隐式缓存：请求前缀与近期请求一致且足够长时，命中部分按缓存读取单价计费，无需修改请求。

| 项目 | 说明 |
|---|---|
| 确认命中 | 原生接口 `usageMetadata.cachedContentTokenCount` 大于 0；OpenAI 兼容接口 `usage.prompt_tokens_details.cached_tokens` 大于 0 |
| 稳定性 | 隐式缓存为尽力而为，前缀相同的请求也可能未命中 |
| 确定性缓存 | 需要稳定复用大段内容时，使用显式缓存，见 [Gemini 显式缓存](https://ofox.io/zh/docs/develop/advanced/gemini-explicit-cache) |

## 常见报错

**要点**:回答在中途截断，通常是思考占用了输出额度；不是报错，请检查 finishReason。

| HTTP · 状态 | 报错原文 | 原因 | 处理方法 |
|---|---|---|---|
| 200，`finishReason: "MAX_TOKENS"` | — | 思考与回答的总长度达到 `maxOutputTokens`，回答被截断 | 增大 `maxOutputTokens`，或用 `thinkingLevel: "low"` 降低思考量。OpenAI 兼容接口为 `finish_reason: "length"` |
| 400 `INVALID_ARGUMENT` | `The input token count exceeds the maximum number of tokens allowed 1048576.` | 输入超过模型上下文 | 缩短输入 |
| 410 `model_deprecated` | `Model 'google/gemini-3-pro-preview' is deprecated and no longer accepts requests; please switch to an active model` | 预览版模型已下线 | 改用正式版或新的预览版，如 `google/gemini-3.1-pro-preview` |
| 404 `model_not_found` | `Model 'google/gemini-9-pro' not found` | 模型 ID 拼写错误 | 从本页复制模型 ID |
| 401 | — | 通过 `?key=` 传入 Key | 改用 `x-goog-api-key` 请求头 |
| 请求超时 | — | 默认开启思考，复杂问题耗时较长 | 使用流式输出，将客户端超时设置为 300 秒以上，或降低思考量 |

其他通用错误见[错误处理](https://ofox.io/zh/docs/develop/guides/error-handling)。

## 官方文档
- [Gemini API · 模型](https://ai.google.dev/gemini-api/docs/models)
- [Gemini API · 思考](https://ai.google.dev/gemini-api/docs/thinking)
- [Gemini API · Google 搜索](https://ai.google.dev/gemini-api/docs/google-search)
- [Gemini API · 结构化输出](https://ai.google.dev/gemini-api/docs/structured-output)
- [Gemini API · OpenAI 兼容](https://ai.google.dev/gemini-api/docs/openai)

官方文档描述的是直连 Google 时的行为。在 OfoxAI 上调用时，模型 ID 与接口地址以本页为准。

## 常见问题

**Gemini 的模型 ID 怎么写？**

标准写法为 google/gemini-3.8-flash，也可以省略 google/ 前缀。原生接口地址中同样可带可不带前缀。

**Gemini 响应很慢怎么办？**

除 Flash-Lite 外，Gemini 默认开启思考，复杂问题可能耗时 1 分钟以上。可传 thinkingLevel: "low" 降低思考量，部分模型可传 thinkingBudget: 0 关闭思考，或改用默认不思考的 Flash-Lite 模型。

**Gemini 怎么关闭思考？**

3.5 Flash、3 Flash Preview 可传 thinkingBudget: 0 关闭思考；3.1 Pro Preview、3.8 Flash 无法完全关闭，可用 thinkingLevel: "low" 降低思考量。Flash-Lite 系列默认不思考。

**Gemini 的回答被截断了，finishReason 是 MAX_TOKENS？**

思考 token 也计入 maxOutputTokens。请增大 maxOutputTokens，或降低思考量。

**Gemini 能联网搜索吗？**

能。原生接口在 tools 中加入 {"google_search": {}}，响应的 groundingMetadata 中有搜索词与来源；OpenAI 兼容接口传 web_search_options: {}。

**Gemini 原生接口怎么认证？**

使用 x-goog-api-key 请求头传入 OfoxAI API Key，也接受 Authorization: Bearer。不支持 URL 参数 ?key=。

**报错 410 model_deprecated？**

该预览版模型已下线，例如 gemini-3-pro-preview。请改用 google/gemini-3.1-pro-preview 或正式版模型。

**Gemini 能分析音频和 PDF 吗？**

能。原生接口通过 inline_data 传入 base64 编码的文件；OpenAI 兼容接口中 PDF 用 file 内容块，音频用 input_audio 内容块。