Gemini API 怎么配置 OpenAI 兼容接口？
简答：如果你要把 Gemini API 接入 OpenAI SDK 或其他 OpenAI 兼容客户端，先填写 Google 官方 Base URL、Gemini API Key 和当前可用的模型 ID，再调用 Chat Completions endpoint。最短验证命令是向 <code>https://generativelanguage.googleapis.com/v1beta/openai/chat/completions</code> 发送一条带 <code>Authorization: Bearer</code> 的 JSON 请求；返回 JSON 且能读取助手文本，就说明基础配置成功。
定义：Gemini API 的 OpenAI 兼容接口，是 Google 提供的一层兼容入口，让部分 OpenAI SDK 和 Chat Completions 客户端使用 OpenAI 风格的请求字段调用 Gemini 模型，但它仍有参数、能力和版本边界，不能等同于完整的 OpenAI API。
先照抄官方路径：三项配置加一条最小请求
本文按 2026-10-30 检索到的公开资料整理。本站是独立的 AI API 接入指南站，不代表 Google 或 SoleAPI 官方。若你的目标只是把 Gemini 接入 OpenAI 兼容客户端，优先先验证 Google 官方兼容入口，不要同时混用第三方网关的 Key、Base URL 或模型目录。
| 配置项 | Google 官方 OpenAI 兼容入口 | 填写规则 |
|---|---|---|
| Base URL | https://generativelanguage.googleapis.com/v1beta/openai/ | SDK 通常在此基础上拼接 chat/completions |
| API Key | GEMINI_API_KEY | 使用 Google AI Studio 或 Google Cloud 项目中的 Gemini API Key |
| 模型 | GEMINI_MODEL | 从当前 Gemini 模型文档或模型列表复制完整 ID |
| 协议 | Chat Completions | 请求体使用 messages，不要改成 Responses API 的 input |
Google 官方示例使用 OpenAI 风格的 chat.completions.create，并通过上述 Base URL、Bearer 鉴权和模型字段完成调用；官方同时说明 OpenAI 库兼容层仍可能存在功能边界，使用前应查看当前文档。可参考Google Gemini API 的 OpenAI 兼容性文档。
- 在 Google AI Studio 或 Google Cloud 项目中创建或查看 Gemini API Key。
- 把 Key 放入环境变量，不要写进前端代码、Git 仓库或公开日志。
- 从当前模型列表复制模型 ID，不要凭记忆修改版本后缀。
- 先发送一条关闭流式和工具调用的短文本请求。
Bash/zsh 最小验证示例如下。GEMINI_API_KEY 和 GEMINI_MODEL 是占位符；若当前模型目录没有该 ID，应替换为实际可用模型。
export GEMINI_API_KEY='YOUR_GEMINI_API_KEY'; export GEMINI_MODEL='YOUR_MODEL_ID'; curl --fail-with-body --connect-timeout 10 --max-time 60 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions' -H "Authorization: Bearer $GEMINI_API_KEY" -H 'Content-Type: application/json' -d '{"model":"'"$GEMINI_MODEL"'","messages":[{"role":"user","content":"请回复：连接成功"}]}'
成功判定：HTTP 请求成功、响应可以解析为 JSON，并且能从响应中找到助手文本。若返回 HTML、登录页或空响应，先检查域名、路径和代理，不要继续修改模型参数。
Python、Node.js 和 PowerShell 配置模板
Python 示例适用于支持 Chat Completions 的 OpenAI Python SDK。SDK 版本、参数支持范围和返回对象字段应以当前 SDK 文档为准。
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=os.environ["GEMINI_MODEL"], messages=[{"role":"user","content":"请用一句话介绍 Gemini API"}]); print(response.choices[0].message.content)
Node.js 示例使用 OpenAI JavaScript SDK 的 baseURL 配置：
import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.GEMINI_API_KEY, baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/" }); const response = await client.chat.completions.create({ model: process.env.GEMINI_MODEL, messages: [{ role: "user", content: "请回复：连接成功" }] }); console.log(response.choices[0].message.content);
PowerShell 可以先构造对象，再由系统转换 JSON，减少引号错误：
$headers = @{ Authorization = "Bearer $env:GEMINI_API_KEY"; "Content-Type" = "application/json" }; $body = @{ model = $env:GEMINI_MODEL; messages = @(@{ role = "user"; content = "请回复：连接成功" }) } | ConvertTo-Json -Depth 5; Invoke-RestMethod -Method Post -Uri "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" -Headers $headers -Body $body
Google 的官方兼容示例明确使用 messages、model 和 Chat Completions。若要使用 Gemini 的思考能力，官方文档提供了 reasoning_effort 与 Gemini 思考参数之间的映射，但不同模型的支持方式并不相同；先完成普通文本请求，再按目标模型文档逐项增加参数。不要同时传入互相重叠的思考参数。相关说明见官方 OpenAI 兼容文档。
模型 ID、Key 和 Base URL 怎么核验
模型名不能只看展示名称。Google 的模型接口可以返回模型元数据，包括模型名称、版本、输入限制和支持能力；模型请求应使用当前接口接受的模型 ID。可通过Google Gemini Models API 文档查看模型查询方式，并以当前模型页面为准。
- Key 核验：请求发往 Google 域名时使用 Gemini API Key；不要把第三方网关 Key 当作 Google Key 使用。
- Base URL 核验：官方 OpenAI 兼容入口包含
/v1beta/openai/。如果客户端会自动追加/chat/completions，填写 Base URL；如果客户端要求完整地址，则填写完整 endpoint，不要重复追加路径。 - 模型核验：优先从当前模型列表复制完整 ID。模型不存在、已停用或当前项目无权限时，不能通过随意改大小写或版本号解决。
- 环境变量核验：执行命令前确认变量非空；日志只打印变量是否存在，不要打印 Key 本身。
Google 官方 Key 文档建议使用环境变量，并说明 Key 的项目、权限和限制会影响请求。具体创建、限制和管理方式以Google Gemini API Key 文档为准。
OpenWebUI、Cursor、Dify 等客户端怎么填
客户端名称不同，字段位置也可能不同，但可先按这组通用字段填写：Provider 选择 OpenAI Compatible 或自定义 OpenAI；API Key 填 Gemini API Key；Base URL 填 https://generativelanguage.googleapis.com/v1beta/openai/；模型填当前可用的 Gemini 模型 ID；请求协议选择 Chat Completions。
| 客户端情况 | 应填写的重点 | 停止条件 |
|---|---|---|
| 支持自定义 OpenAI Provider | Key、Base URL、Model 三项先填，关闭流式测试 | 若客户端自动拼接路径，不能再把完整 endpoint 填入 Base URL |
| 只接受 Chat Completions | 使用 messages 请求格式 | 不要填 Responses API 的 input |
| 只支持 Responses API | Google 官方本文示例不能直接套用 | 改用客户端支持的接口或对应网关文档 |
| 支持工具调用或思考参数 | 先验证普通文本，再按模型文档增加字段 | 出现 400 时删除未确认支持的扩展参数 |
OpenWebUI、Cursor 和 Dify 的具体版本可能改变字段名称、路径拼接方式或协议支持范围，因此不能把一个客户端的配置截图直接套到另一个客户端。判断方法是查看客户端最终请求的 URL、请求体字段和响应状态；如果无法确认它调用的是 Chat Completions 还是 Responses API，先用 curl 完成最小请求，再回到客户端配置。
如果你实际使用的是某个兼容网关，其 Base URL、模型列表和协议入口只对该网关的 Key 生效。例如，站内公开的 SoleAPI 文档将其 OpenAI 兼容入口写为 /v1/responses，同时说明 /v1/chat/completions为历史兼容入口；这属于该服务自己的文档，不能替代 Google 官方配置，也不能据此推断其他网关的行为。详情可查看SoleAPI Responses API 文档和其快速开始文档。
400、401、404、429 和超时排查表
| 现象 | 先查什么 | 处理方式 |
|---|---|---|
| 400 | 请求体字段、JSON 格式、未支持参数 | 保留 model 与 messages，删除思考、工具或自定义扩展后重试 |
| 401 | Key 是否为空、失效、复制不完整或服务不匹配 | 确认请求头是 Authorization: Bearer，重新检查当前项目的 Key |
| 404 | 域名、路径和模型 ID | 检查是否重复添加 /v1beta/openai，再从模型列表复制 ID |
| 429 | 限流、配额、账单或并发状态 | 读取响应中的具体错误和 Retry-After；只有确认是临时限流且请求可安全重试时才退避 |
| 超时或流式中断 | 网络、客户端超时、代理缓冲和 SSE 处理 | 先关闭流式并发送短文本；不要仅凭一次超时判断模型不可用 |
排错顺序应固定为：确认 Key → 确认 Base URL → 确认 endpoint → 确认模型 ID → 发送最小请求 → 再增加流式、工具和思考参数。余额、权限、Key 无效或模型不可用时，不要无限自动重试；记录状态码、请求 ID和脱敏后的错误摘要即可。
常见问题
Gemini API 可以直接使用 OpenAI SDK 吗？
可以通过 Google 提供的 OpenAI 兼容入口使用 OpenAI SDK，但不是所有 OpenAI 参数和高级能力都自动兼容。官方示例主要使用 Chat Completions，SDK 版本和支持范围以当前官方文档为准。
Google 官方 Base URL 应该填到哪里？
通常将 https://generativelanguage.googleapis.com/v1beta/openai/ 填入 SDK 的 base_url 或 baseURL，请求方法再调用 Chat Completions。若客户端要求完整 endpoint，则使用该 Base URL 加上 chat/completions，不要重复拼接。
为什么提示模型不存在？
模型 ID可能已变化、当前项目没有权限，或你把展示名称当成了请求 ID。先查看当前模型列表，再复制完整的模型字段；不要凭记忆添加版本后缀。
Gemini 原生 API 和 OpenAI 兼容接口有什么区别？
原生接口使用 Google Gemini 自己的请求结构和 SDK；OpenAI 兼容接口使用 messages、Chat Completions 等 OpenAI 风格字段。两者的 Key、Base URL、请求体和高级参数不能混用。
可以把第三方网关的地址和 Google API Key 混用吗？
不能默认混用。请求发往 Google 域名时使用 Google Gemini API Key；请求发往第三方网关时使用该网关签发的 Key，并严格按照该网关当前文档填写路径和模型。具体服务的状态、额度和兼容能力应以其当前文档和实际响应为准。
常见问题
Gemini API 可以直接使用 OpenAI SDK 吗？
可以通过 Google 提供的 OpenAI 兼容入口使用 OpenAI SDK，但不是所有 OpenAI 参数和高级能力都自动兼容。官方示例主要使用 Chat Completions，SDK 版本和支持范围以当前官方文档为准。
Google 官方 Gemini OpenAI 兼容 Base URL 是什么？
通常填写 https://generativelanguage.googleapis.com/v1beta/openai/；完整 REST 请求再追加 chat/completions。不要把第三方网关的路径或 Key 混入这条官方配置。
为什么会出现 401 或 404？
401 优先检查 Key 是否为空、失效或与请求服务不匹配；404 优先检查 Base URL、endpoint 是否重复，以及模型 ID 是否来自当前模型列表。
Gemini 原生 API 和 OpenAI 兼容接口能混用吗？
不能直接混用。原生接口与 OpenAI 兼容接口的请求体、endpoint、SDK 和高级参数不同，应先确定协议，再填写对应配置。
reasoning_effort、thinking_level 和 thinking_budget 能同时使用吗？
不要默认同时使用。Google 文档说明不同 Gemini 模型的思考配置存在映射差异，先确认目标模型支持的字段，再逐项添加。