Skip to Content
模型用法Gemini概览

Gemini 系列

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

常见任务

控制思考 思考默认开启，耗时较长时如何降低思考量。Google 搜索 联网获取实时信息并返回来源。PDF 与音频 上传文档、音频进行分析。报错排查 回答被截断、模型已下线、超出上下文。在 Gemini CLI 中使用 接入配置与常见问题。

模型

支持文本、图片、音频与 PDF 输入，上下文约 1M token。完整的模型列表与实时价格请参阅模型页 ，也可通过 Models API 查询。生图模型见 Nano Banana。

常用模型 ID（调用时原样复制）
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-lite默认不思考，响应快
Gemini 3.5 Flashgoogle/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.ai/gemini/v1beta/models/<模型 ID>:generateContentPOST https://api.ofox.ai/v1/chat/completions
SDKgoogle-genai，base_url 为 https://api.ofox.ai/geminiOpenAI SDK，base_url 为 https://api.ofox.ai/v1
认证x-goog-api-key: <Key>，也接受 Authorization: Bearer <Key>Authorization: Bearer <Key>
流式:streamGenerateContent?alt=sse"stream": true
思考thinkingConfig，可返回思考摘要reasoning_effort 或 reasoning，返回 reasoning_details
Google 搜索tools: [{"google_search": {}}]，返回来源与搜索词web_search_options，只返回回答

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

Gemini 模型目前由 Google Vertex AI（google_vertex）提供。完整的请求参数见 Generate Content。

调用示例

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="用一句话解释什么是幂等性。",
)
print(resp.text)

提示缓存

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

项目说明
确认命中原生接口 usageMetadata.cachedContentTokenCount 大于 0；OpenAI 兼容接口 usage.prompt_tokens_details.cached_tokens 大于 0
稳定性隐式缓存为尽力而为，前缀相同的请求也可能未命中
确定性缓存需要稳定复用大段内容时，使用显式缓存，见 Gemini 显式缓存

常见报错

要点回答在中途截断，通常是思考占用了输出额度；不是报错，请检查 finishReason。
HTTP · 状态报错原文原因处理方法
200，finishReason: "MAX_TOKENS"—思考与回答的总长度达到 maxOutputTokens，回答被截断增大 maxOutputTokens，或用 thinkingLevel: "low" 降低思考量。OpenAI 兼容接口为 finish_reason: "length"
400 INVALID_ARGUMENTThe input token count exceeds the maximum number of tokens allowed 1048576.输入超过模型上下文缩短输入
410 model_deprecatedModel '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_foundModel 'google/gemini-9-pro' not found模型 ID 拼写错误从本页复制模型 ID
401—通过 ?key= 传入 Key改用 x-goog-api-key 请求头
请求超时—默认开启思考，复杂问题耗时较长使用流式输出，将客户端超时设置为 300 秒以上，或降低思考量

其他通用错误见错误处理。

官方文档

官方文档描述的是直连 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 内容块。

最后更新于
思考