Gemini Pro API 可透過 Gemini API 存取，使用在 Google AI Studio 中建立的金鑰。若要直接發送 REST 請求，請呼叫模型的 generateContent 端點；若已有現成的 OpenAI SDK 整合，則可將客戶端指向 Google 的 OpenAI 相容基礎 URL，並使用當前的 Gemini 模型 ID，例如 gemini-3.1-pro-preview。重點在於「Gemini Pro」是產品系列搜尋詞，而非固定的 API 識別碼，因此正式環境應用程式應在固定使用某個 ID 前，先查閱 Google 的現行模型清單。
Gemini Pro API 設定一覽
您需要四個值來發送請求：
| 設定項目 | 值 |
|---|---|
| API 金鑰 | 在 Google AI Studio 建立 |
| 原生主機位址 | https://generativelanguage.googleapis.com |
| 原生 API 路徑 | /v1beta/models/{model}:generateContent |
| OpenAI 相容基礎 URL | https://generativelanguage.googleapis.com/v1beta/openai/ |
| 範例模型 ID | gemini-3.1-pro-preview |
Google 的 Gemini API 快速入門 說明了 API 金鑰建立方式與原生請求模式。其 OpenAI 相容性指南 則為已使用 OpenAI Python 或 JavaScript SDK 的應用程式，說明了相容性基礎 URL。
當您需要 Google 一推出就馬上使用 Gemini 專屬功能時，請使用原生 Gemini SDK 或 REST API。當您已經有 OpenAI 風格的客戶端，並希望減少遷移工作時，請使用相容性層。相容性雖然實用，但並不保證每個供應商專屬的選項都能完美對應到不同 API。
如何取得 Gemini 的 Google API 金鑰
在 Google AI Studio 中建立金鑰，然後將其儲存在環境變數中，而非直接寫入原始碼：
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
請將此視為伺服器端憑證。請勿將其提交至 Git、輸出至日誌，或嵌入瀏覽器 JavaScript 或行動應用程式套件中。若前端需要 Gemini 的輸出結果，請將使用者請求發送至您自己的後端，再由後端呼叫 Google API。
對於正式環境服務，也請決定誰擁有 Google Cloud 專案、金鑰如何輪換、哪些環境使用不同的憑證，以及在哪裡監控請求配額。Google 的 API 金鑰指引 說明了 Gemini API 金鑰如何與 Google Cloud 專案關聯。
如何呼叫原生 Gemini API 端點
原生 REST 路由會將模型 ID 放入 URL 中。以下範例要求當前的 Pro 預覽模型回傳一份簡潔的遷移檢查清單：
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"contents": [
{
"parts": [
{
"text": "建立一份七步驟檢查清單，用於將 Python API 從一個區域遷移至兩個區域。包含回滾檢查。"
}
]
}
]
}'
回應中包含含有生成內容的 candidates。正式應用程式應處理 candidate 清單為空、內容遭封鎖、逾時以及非 2xx 回應等情況，而非直接索引第一個回應物件。
URL 使用 v1beta，因為這是 Google 當前 Gemini API 範例中顯示的路由。請將 API 版本保留在設定檔中，這樣您就可以在不將端點字串散落在程式碼各處的情況下，測試新版本。
原生端點結構
路徑包含三個部分：
/v1beta/models/{model}:generateContent
v1beta是 API 版本。{model}是來自 Google Gemini 模型頁面 的確切模型 ID。generateContent是生成方法。
收到 404 回應通常表示模型 ID、API 版本或方法不符。在修改驗證程式碼之前，請先將完整路徑與目前的模型文件進行比對。
如何使用 OpenAI 相容客戶端搭配 Gemini
如果您的應用程式已使用 OpenAI Python 套件，請安裝並變更 API 金鑰、基礎 URL 和模型 ID：
pip install openai
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[
{
"role": "system",
"content": "您是一位簡潔的軟體架構審查者。",
},
{
"role": "user",
"content": "審查一個佇列工作者設計，並列出前五大失敗模式。",
},
],
)
print(response.choices[0].message.content)
對於已有現成 chat-completions 抽象層的團隊來說，這是最快的途徑。這也讓評估框架更易於重複使用：保持提示詞和回應檢查不變，然後切換供應商設定即可。
請不要因為兩個供應商接受相同的 SDK 呼叫，就假設它們的行為完全相同。系統指令、工具架構、多模態輸入、安全處理、串流事件、Token 計算和錯誤回傳格式都可能不同。在將正式流量切換過去之前，請先針對供應商執行專屬測試。
如何選擇與管理 Gemini 模型 ID
避免在應用程式邏輯中直接使用像 gemini-pro 這樣的行銷名稱。Google 可用的模型 ID 會隨著預覽模型的引入、升級和退役而持續變動。在檢查本指南的當下，Google 的官方模型頁面將 gemini-3.1-pro-preview 列為 Pro 類別的模型識別碼。
請改用設定層：
import os
GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")
這個小小的選擇能讓模型升級變成部署配置的變更，而非程式碼重寫。對於較大型的服務，請將這些欄位儲存在一起：
{
"provider": "google",
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": "gemini-3.1-pro-preview",
"timeout_seconds": 60
}
在將新模型導入正式環境之前：
- 確認該 ID 出現在 Google 目前的模型文件或 models API 中。
- 檢查該模型是預覽版、穩定版，還是已排定退役。
- 針對回答品質和工具呼叫正確性，執行您自己的評估集。
- 使用代表性的提示詞，測量延遲、Token 使用量和失敗率。
- 在轉移所有流量之前，先準備好一個備援模型或明確的失敗路徑。
速率限制並非單一通用數字。它們取決於模型和使用層級，因此請閱讀 Google 的 Gemini API 速率限制文件，並監控套用至您專案的限制。
如何建立可切換供應商的後端
OpenAI 相容介面可以減少程式碼變更，但供應商切換在您的應用程式自行定義合約時效果最佳。請將供應商設定保留在業務邏輯之外，並正規化您實際需要的輸出。
import os
from openai import OpenAI
PROVIDERS = {
"gemini": {
"api_key": os.environ["GEMINI_API_KEY"],
"base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
"model": os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview"),
},
"novita": {
"api_key": os.environ["NOVITA_API_KEY"],
"base_url": "https://api.novita.ai/openai",
"model": os.getenv("NOVITA_MODEL", "xiaomimimo/mimo-v2.5-pro"),
},
}
def generate(provider_name: str, prompt: str) -> str:
provider = PROVIDERS[provider_name]
client = OpenAI(
api_key=provider["api_key"],
base_url=provider["base_url"],
)
response = client.chat.completions.create(
model=provider["model"],
messages=[{"role": "user", "content": prompt}],
)
return response.choices[0].message.content or ""
這個範例刻意揭露差異而非隱藏它們。每個供應商都保留自己的憑證、基礎 URL 和模型 ID。應用程式收到一個正規化的字串，而供應商專屬的測試則可以涵蓋更豐富的行為，例如工具或多模態輸入。
Novita AI 的 LLM API 文件 對支援的模型使用 OpenAI 相容的 API 格式。當團隊想在無需重建整個客戶端層的情況下比較 Gemini 與開源模型時，這會很有用。
Gemini 如何融入代理後端
代理後端至少包含兩個獨立的職責：
- 推論： 模型決定要說什麼或呼叫哪個工具。
- 執行： 受控的執行環境執行檔案、Shell、瀏覽器或應用程式操作。
Gemini API 可以處理推論端。但不應將其視為執行邊界。如果模型提出了一個 Shell 命令，您的應用程式仍然需要驗證工具呼叫、授權該操作、在隔離環境中執行它、擷取結果，並決定要將哪些上下文傳回給模型。
Novita Agent Sandbox 專為隔離的代理執行工作流程而設計。一個實用的架構可以讓 Gemini 負責推理，同時讓沙箱分別處理程式碼或瀏覽器任務：
使用者請求
-> 代理服務
-> Gemini API 進行推理與工具選擇
-> 對提議動作進行政策檢查
-> Agent Sandbox 進行隔離執行
-> 工具結果回傳至代理服務
-> Gemini API 產生最終回應
這種分離方式讓模型可被替換，並將不受信任的執行與應用程式伺服器隔離開來。它也為後端提供了一個統一的場所來強制執行逾時、網路政策、檔案限制、稽核日誌和使用者授權。
對於第一個版本，請只暴露少數幾個狹義的工具，為其引數定義 JSON 架構，拒絕未知的欄位，並對執行時間和輸出大小設定嚴格的限制。只有在權限模型明確之後，才加入更廣泛的電腦使用或瀏覽器功能。
何時開源模型是更好的選擇
當您的應用程式需要 Google 的模型能力和受管 API 時，Gemini Pro 模型是強而有力的選擇。當您需要第二個供應商、想要評估模型相對於公開上游版本的行為，或偏好一個可透過 OpenAI 相容端點與其他基礎設施一起使用的模型時，開源模型可能是更好的選擇。
MiMo-V2.5-Pro 是 Novita AI 上目前的一個選項。Xiaomi 的上游模型卡將其描述為開源的混合專家模型，而 Novita AI 則提供託管模型 ID xiaomimimo/mimo-v2.5-pro。由於 Google 相容性端點和 Novita AI 都可以透過 OpenAI 風格的客戶端呼叫，因此前一節中的供應商可切換模式可以使用相同的提示詞和接受度檢查來評估它們。
不要僅根據標籤來選擇。從您的實際工作負載中建立一個小型評估集：程式碼審查意見、支援問題、基於檢索的答案、工具呼叫或長篇文件。在做出路由決策之前，請使用目前的供應商儀表板比較輸出品質、延遲、錯誤行為和成本。
常見 Gemini API 錯誤
400：請求無效
檢查 JSON 結構、訊息角色、工具定義和參數名稱。其他 OpenAI 相容供應商接受的選項，可能不被 Google 的相容性層接受。
401 或 403：驗證或權限失敗
確認 GEMINI_API_KEY 存在於處理程序環境中，且屬於預期的 Google Cloud 專案。也請檢查該專案和選定的模型是否適用於該帳戶和區域。
404：找不到模型或方法
將確切的模型 ID 與目前的 Gemini 模型清單進行比較。對於原生 REST 呼叫，請驗證 API 版本和 :generateContent 後綴。對於 OpenAI 相容呼叫，請驗證基礎 URL 是否以 /v1beta/openai/ 結尾。
429：超出速率限制
使用指數退避和抖動進行重試，但不要將重試視為容量規劃的替代方案。將突發工作排入佇列、限制並發請求，並檢查專案目前的使用層級和模型特定限制。
SDK 可以運作，但切換供應商後輸出不同
相容性涵蓋的是請求介面，而非相同的模型行為。請針對每個供應商和模型版本，重新執行提示詞、結構化輸出和工具呼叫測試。
結論
當您需要最清晰的路徑來使用 Gemini 專屬功能時，請從原生 Gemini API 開始。當您已經有 OpenAI 風格的後端或需要快速評估供應商時，請從 OpenAI 相容端點開始。在這兩種情況下，請將 API 金鑰保留在伺服器端，將模型 ID 放在設定檔中，測試確切的模型版本，並將模型推理與代理執行分開。
對於具備韌性的正式環境設計，請在相同的應用程式自有介面背後，至少保留一個替代模型。這能讓您的團隊擁有一個實用的方式來測試 Novita AI 上的開源選項、處理模型生命週期變更，並將代理執行路由到隔離的沙箱中，而不是將所有責任都耦合到單一 API 呼叫。
常見問題
還有名為 gemini-pro 的模型 ID 嗎？
請不要假設 gemini-pro 是當前的 ID。「Gemini Pro API」通常被用作搜尋 Google 較高能力 Gemini 模型的詞組，但應用程式必須使用來自當前 Gemini 模型頁面的確切 ID。本指南使用 gemini-3.1-pro-preview 作為已驗證的範例。
我從哪裡取得 Gemini 的 Google API 金鑰？
在 Google AI Studio 中建立 Gemini API 金鑰。請將其儲存在伺服器端的秘密中，例如 GEMINI_API_KEY，而非放在原始碼或前端 JavaScript 中。
Gemini API 端點是什麼？
原生主機位址是 https://generativelanguage.googleapis.com。生成內容的請求使用 /v1beta/models/{model}:generateContent。Google 的 OpenAI 相容基礎 URL 是 https://generativelanguage.googleapis.com/v1beta/openai/。
Gemini Studio API 與 Gemini API 不同嗎？
Google AI Studio 是開發人員用來實驗和建立金鑰的網頁介面。應用程式請求則是發送給 Gemini API。搜尋「Gemini Studio API」通常指的是這種 AI Studio 到 API 的工作流程。
Google Bard API 與 Gemini API 相同嗎？
Gemini 是當前的 API 和模型品牌。較舊的 Google Bard API 搜尋應使用當前的 Gemini API 文件、端點和模型 ID，而非舊的 Bard 範例。
我可以將 OpenAI SDK 與 Gemini 一起使用嗎？
可以。Google 提供了 OpenAI 相容端點的文件。將用戶端基礎 URL 設定為 Google 的相容性 URL，提供您的 Gemini API 金鑰，並選擇一個受支援的 Gemini 模型 ID。在依賴完全行為一致之前，請先測試供應商專屬功能。
Gemini 可以為 AI 代理執行程式碼嗎？
Gemini 可以推理程式碼並提議工具呼叫，但執行應在受控的執行環境中進行。將模型呼叫與隔離環境（例如 Agent Sandbox）分開，並在執行前驗證每個請求的動作。
