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.io/gemini/v1beta/models/<模型 ID>:generateContentPOST https://api.ofox.io/v1/chat/completions
SDKgoogle-genai，base_url 為 https://api.ofox.io/geminiOpenAI SDK，base_url 為 https://api.ofox.io/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.io/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 內容區塊。

最後更新於
思考