Gemini API 接口地址（Base URL）是什麼：原生端點與 OpenAI 兼容調用寫法

本文根據 Gemini API 官方文檔（OpenAI compatibility、API versions explained、Quickstart、Interactions API、Using Gemini API keys）整理，資料核對於 2026-10-10。本文只列官方公佈的接口地址。

適用於誰

• 在第三方客戶端或自己的代碼裏需要填「接口地址 / Base URL」，不確定 Gemini 官方地址是什麼的人；
• 已經用 OpenAI SDK 寫好了程序，想換成 Gemini 模型試試的開發者；
• 搜「gemini api 接口地址」「base url」「openai 兼容」「endpoint」的人。

結論先說

1. 官方域名只有一個：generativelanguage.googleapis.com。
2. 原生接口的基礎地址是 https://generativelanguage.googleapis.com/v1beta（也有穩定版 /v1），鑑權用請求頭 x-goog-api-key。
3. OpenAI 兼容接口的 Base URL 是 https://generativelanguage.googleapis.com/v1beta/openai/，鑑權用 Authorization: Bearer 你的密鑰。
4. 用 OpenAI SDK 調 Gemini 只改三處：api_key 換成 Gemini API 密鑰，base_url 換成上面的兼容地址，model 換成 Gemini 的模型 ID。
5. 官方的態度：兼容層還在 beta；如果你本來沒在用 OpenAI 的庫，官方建議直接調 Gemini API。

一、官方端點一覽

用官方 SDK（google-genai、@google/genai）時不需要自己填地址，SDK 已經內置。只有直接發 HTTP 請求，或者在別的工具裏配置時才需要這些地址。

二、鑑權：兩種請求頭別混用

原生接口用 x-goog-api-key：

bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "用一句話介紹你自己"
  }'

OpenAI 兼容接口用 Authorization: Bearer：

bash
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "用一句話介紹你自己"}]
  }'

兩種方式用的是同一把 Gemini API 密鑰，在 AI Studio 創建，方法見本站《Gemini API Key 怎麼獲取：在 AI Studio 創建密鑰、設定環境變量與安全限制》。

三、v1 和 v1beta 有什麼區別

官方《API versions explained》的說明：

• v1 是穩定版：其中的功能在這個大版本的生命週期內都受支持，有不兼容改動時會出新的大版本。官方說明 Interactions API 及其核心功能已在 v1 正式可用。
• v1beta 包含仍在開發中的早期功能，可能隨反饋調整，好處是能先用上新能力。
• 所有模型在兩個版本里都能用，差別在功能：函數調用、結構化輸出、思考、系統指令、代碼執行、Google 搜尋接地、URL 上下文、文件搜尋等在 v1 和 v1beta 都有；語音輸出、Flex / Priority 服務檔、Computer Use、MCP 伺服器工具、Live API、Agents API、Webhooks、上下文緩存目前只在 v1beta。
• 官方 SDK 預設用 v1beta，以便訪問預覽功能。想固定用穩定版，可以這樣指定：

python
from google import genai

client = genai.Client(http_options={"api_version": "v1"})

javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1" } });

排錯時也要想到版本：官方排錯頁提醒，某個功能如果還在 Beta，就只能在 /v1beta 下使用；在舊版本端點上用新功能會報 400。

四、用 OpenAI SDK 調 Gemini（官方寫法）

Python：

python
from openai import OpenAI

client = OpenAI(
    api_key="你的 Gemini API 密鑰",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {"role": "system", "content": "你是一個簡潔的中文助手。"},
        {"role": "user", "content": "解釋一下什麼是向量數據庫"},
    ],
)
print(response.choices[0].message.content)

JavaScript：

javascript
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await openai.chat.completions.create({
  model: "gemini-3.8-flash",
  messages: [{ role: "user", content: "解釋一下什麼是向量數據庫" }],
});
console.log(response.choices[0].message.content);

官方把它概括為「只改三行」：密鑰、base_url、模型名。流式輸出照常加 stream=True，逐塊讀取 chunk.choices[0].delta。

五、兼容接口支持什麼

官方 OpenAI compatibility 頁面演示過的能力：

關於思考：官方說明不傳 reasoning_effort 時使用模型自己的預設等級；Gemini 2.5 Pro 和 Gemini 3 系列不能關閉思考（"none" 只對部分 2.5 模型有效）。

Gemini 獨有的功能通過 extra_body 傳。官方列出的字段裏，對話接口可用的有 cached_content（對應上下文緩存）和 thinking_config（對應 Gemini 的思考配置）。

六、限制和選擇建議

• 仍是 beta：官方原話是對 OpenAI 庫的支持仍處於 beta 階段，功能還在擴展。
• 新功能不一定同步：官方說明今後新模型、新工具和智能體功能會先在 Interactions API 上線。伺服器端儲存對話狀態（previous_interaction_id）、後台執行、託管智能體這些都是原生接口的能力。
• 官方的建議：還沒用 OpenAI 庫的，直接用 Gemini API；已有大量 OpenAI 代碼、想低成本試用 Gemini 的，再用兼容層。
• 密鑰還是同一把：兼容接口用的就是 Gemini API 密鑰，用量記在密鑰所屬的項目上；官方說明速率限制和計費都按項目計算，不區分密鑰。

原生 SDK 的用法見本站《Gemini API Python 調用教學：安裝 google-genai SDK、流式輸出、多輪對話與傳圖片》。

常見問題

Q：第三方客戶端讓我填 Base URL，填哪個？

看它用的是哪種協議。按 OpenAI 格式發請求的，填 https://generativelanguage.googleapis.com/v1beta/openai/；按 Gemini 原生格式的，基礎地址是 https://generativelanguage.googleapis.com/v1beta。具體填到哪一級路徑，以該工具自己的說明為準。

Q：模型名填什麼？

填官方 Models 頁的模型 ID，例如 gemini-3.8-flash、gemini-3.5-flash-lite、gemini-3.1-pro-preview。可以調用模型列表接口確認自己的密鑰能看到哪些模型。

Q：返回 404？

多半是地址或模型名不對：檢查路徑裏的版本號（v1beta）、兼容接口是否漏了 /openai/、模型 ID 是否拼錯或已下線。

Q：返回 401 或提示密鑰無效？

檢查請求頭有沒有用對：原生接口是 x-goog-api-key，兼容接口是 Authorization: Bearer。

Q：這個地址和 Google Cloud 上的企業版是一回事嗎？

不是。官方把面向開發者的這套叫 Gemini Developer API（本文講的就是它），另有面向企業的 Gemini 平台 API（Gemini Enterprise Agent Platform），兩者都可以通過同一個 Google GenAI SDK 訪問，但初始化方式不同（企業版要指定 Google Cloud 項目和區域）。官方的建議是多數開發者用 Gemini Developer API，除非需要特定的企業級管控。

Q：這些地址在哪些地區可用？

Gemini API 只在官方 Available regions 頁面列出的國家和地區提供，該列表目前沒有列出中國大陸。請遵守所在地法律和服務條款。

參考資料

• OpenAI compatibility（官方）：https://ai.google.dev/gemini-api/docs/openai
• API versions explained（官方）：https://ai.google.dev/gemini-api/docs/api-versions
• Gemini API quickstart（官方）：https://ai.google.dev/gemini-api/docs/quickstart
• Gemini API quickstart（generateContent 版，官方）：https://ai.google.dev/gemini-api/docs/generate-content/quickstart
• Interactions API（官方）：https://ai.google.dev/gemini-api/docs/interactions-overview
• Using Gemini API keys（官方）：https://ai.google.dev/gemini-api/docs/api-key
• Files API（官方）：https://ai.google.dev/gemini-api/docs/files
• Gemini Developer API vs. Gemini platform（官方）：https://ai.google.dev/gemini-api/docs/migrate-to-cloud
• Available regions for Google AI Studio and Gemini API（官方）：https://ai.google.dev/gemini-api/docs/available-regions
• API errors（官方）：https://ai.google.dev/gemini-api/docs/api-errors