通过 Gemini API 访问 Gemini Pro 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://generativelativelanguage.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 从一个区域迁移到两个区域。包含回滚检查。"
}
]
}
]
}'
响应包含带有生成内容的候选项。实际应用程序应处理空候选项列表、被阻止的内容、超时和非 2xx 响应，而不是直接索引到第一个响应对象中。
URL 使用 v1beta，因为这是 Google 当前 Gemini API 示例中显示的路由。将 API 版本保留在配置中，以便您可以在不将端点字符串分散到整个代码库的情况下测试新版本。
原生端点剖析
路径包含三个部分：
/v1beta/models/{model}:generateContent
v1beta是 API 版本。{model}是来自 Google Gemini 模型页面 的确切模型 ID。generateContent是生成方法。
404 响应通常意味着模型 ID、API 版本或方法不匹配。在更改身份验证代码之前，请将完整路径与当前模型文档进行比较。
如何将 Gemini 与 OpenAI 兼容客户端一起使用
如果您的应用程序已使用 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)
这对于拥有现有聊天补全抽象层的团队来说是最快捷的路径。它也使评估工具更易于重用：保持提示和响应检查不变，然后交换提供商配置。
不要仅仅因为两个提供商接受相同的 SDK 调用就假设行为一致。系统指令、工具模式、多模态输入、安全处理、流式事件、令牌核算和错误负载可能不同。在改变生产流量之前，请运行特定于提供商的测试。
如何选择和管理 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 当前的模型文档或模型 API 中。
- 检查该模型是预览版、稳定版还是计划退役版。
- 针对答案质量和工具调用正确性运行您自己的评估集。
- 使用代表性提示测量延迟、令牌使用率和失败率。
- 在转移所有流量之前，添加一个备用模型或清晰的故障路径。
速率限制不是单一的通用数字。它们取决于模型和使用层级，因此请阅读 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 智能体沙箱 专为隔离的智能体执行工作流而设计。一个实用的架构可以让 Gemini 负责推理，而沙箱则分别处理代码或浏览器任务：
用户请求
-> 智能体服务
-> Gemini API 用于推理和工具选择
-> 对提议操作进行策略检查
-> 智能体沙箱用于隔离执行
-> 工具结果返回给智能体服务
-> Gemini API 用于最终响应
这种分离使模型可替换，并将不受信任的执行与应用程序服务器隔离开来。它还使后端有一个地方来强制执行超时、网络策略、文件限制、审计日志记录和用户授权。
对于第一个版本，只暴露几个狭窄的工具，为其参数定义 JSON 模式，拒绝未知字段，并对执行时间和输出大小设置硬性限制。只有在权限模型清晰之后，才添加更广泛的计算机使用或浏览器功能。
何时开源模型是更好的选择
Gemini Pro 模型是当您的应用程序需要 Google 的模型能力和托管 API 时的强大选择。当您需要第二个提供商、希望根据可见的上游发布评估模型行为，或者更喜欢通过 OpenAI 兼容端点与其他基础设施一起使用的模型时，开源模型可能是更好的选择。
MiMo-V2.5-Pro 是 Novita AI 上的一个当前选项。小米的上游模型卡将其描述为开源的专家混合模型，而 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 是开发人员用来试验和创建密钥的 Web 界面。应用程序请求则发送到 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 可以推理代码并提出工具调用，但执行应在受控的运行时中进行。将模型调用与诸如智能体沙箱之类的隔离环境分开，并在运行每个请求的操作之前对其进行验证。
