# 用 OpenAI SDK 调用 Gemini：区分原生、兼容端点和网关路径

> Google 为 Gemini 提供 OpenAI 兼容接口，网关也可以提供自己的兼容线路。SDK 可以复用，但 Base URL、密钥、模型 ID、支持字段与计费仍由具体服务决定。

_发布 2026-09-23 · 更新 2026-09-29 · [KeepRouter Editorial](https://keeprouter.com/editorial-policy#editorial-team) · 6 分钟阅读_

![Responses API 与 Chat Completions 接入协议决策矩阵](https://keeprouter.com/editorial/blog/responses-api-vs-chat-completions.png)

_逐条核验 Gemini 访问路径的操作与必要字段。_

使用 OpenAI SDK 调用 Gemini，可以减少客户端代码数量，但 SDK 本身不会替你选择由哪家服务处理请求。Google 自己的兼容端点与 KeepRouter 兼容线路，拥有不同的地址、凭证、目录和账单。应先选择调用路径，再检查应用实际需要的功能。

一个适合起步的工作负载是客服助手：平时读取文本，偶尔接收图片，再调用一次内部查询工具。它比一句问候更能暴露集成问题，规模又足够小，便于逐项检查。可以从 [KeepRouter 的 Gemini 目录条目](/models/gemini-3.5-flash)查看候选线路；网关中的模型 ID，不应被直接当成上游模型命名空间或完整能力证明。

## 先确认需要哪一种路径

| 路径 | 可能选择它的原因 | 需要保持独立的配置 |
|---|---|---|
| Google 原生 Gemini API | 功能依赖 Google 原生对象 | SDK、凭证、模型可用性与原生能力 |
| Google OpenAI 兼容端点 | 现有 OpenAI 客户端已覆盖所需操作 | Google Key、Google Base URL、兼容字段 |
| KeepRouter 兼容线路 | 希望统一账户及已评估模型的客户端配置 | KeepRouter Key、公开模型 ID、端点及客户价格 |

Google 的 [OpenAI 兼容文档](https://ai.google.dev/gemini-api/docs/openai)列出支持的操作和专有扩展。应阅读实际使用操作的章节。文本请求成功，不能直接说明图片载荷、某个推理参数或完整工具接续也能成功。用一张小型请求矩阵记录这些结论，比给整个集成贴上“全面兼容”的标签更有用。

## 配置客户端时，不要混用凭证

下面的示例只指向 KeepRouter。将 `KEEPROUTER_MODEL` 设置为当前目录中所选 Gemini 的准确 ID。通过环境变量指定，可以避免文章把某个已经退役或不可用的选择悄悄固化。项目锁文件还应记录 SDK 版本。Key 必须允许所选模型，付费模型还需要足够余额；给账户充值不会自动扩大仅允许 free 的 Key 范围。

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://keeprouter.com/v1",
    api_key=os.environ["KEEPROUTER_KEY"],
    timeout=30.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model=os.environ["KEEPROUTER_MODEL"],
    messages=[{"role": "user", "content": "Return a short title for a test support ticket."}],
)
print(response.id, response.model)
print(response.usage.model_dump() if response.usage else "usage missing")
```

如果使用 Google 自己的兼容服务，官方文档给出的地址是 `https://generativelanguage.googleapis.com/v1beta/openai/`，并使用 Google 凭证。将它与网关配置分别保存，避免把一家服务的 Key 与另一家的地址拼在一起。排查认证时，只显示目标主机与密钥是否存在，不应输出密钥内容。

以上是最小请求模板，不是已经发布的性能测试。扩大调用前，应补充所选线路明确支持的输出上限字段。[OpenAI SDK 指南](/use-cases/openai-sdk)与 [API 参考](/api/docs)说明 KeepRouter 面向客户端的契约。

## 逐项测试会改变行为的字段

为每一种必要能力准备一个固定案例，不要在第一笔请求中加入所有可选参数。

| 案例 | 成功条件 | 常见误判 |
|---|---|---|
| 文本 | 应用取得合格答案 | HTTP 200 就等于任务完成 |
| 图片加问题 | 正确识别已知图片事实 | 支持文本就支持视觉 |
| 函数调用 | 参数可解析、工具结果可返回、回答可结束 | 发出工具定义就证明能接续 |
| 结构化输出 | 通过应用自己的 Schema 校验 | 看起来像 JSON 就有格式约束 |
| 流式输出 | 终止状态和用量都被处理 | 拼接文字就覆盖了全部事件 |
| 专有扩展 | 线路有文档且实际遵守字段 | extra_body 中任意字段都会原样透传 |

Google 为没有直接对应 OpenAI 字段的能力提供专有扩展。它们属于 Google 的具体契约。经过网关之前，应确认所选线路会翻译、转发还是拒绝该字段。如果没有公开契约，可以让依赖它的功能继续走原生路径，或做范围明确的兼容实验，并只对测试过的行为给出结论。

## 保留工具历史和多模态输入结构

工具测试应走完一整轮：模型选择工具，应用校验参数，工具返回无害结果，模型继续完成回答。记录 SDK 发送的调用 ID 和消息顺序。如果应用删掉了模型消息里不认识的字段，即使首轮回答正常，也可能丢失后续步骤必需的信息。

图片测试使用一张你控制的小图片，确认线路接受的输入表达方式。远程 URL 还涉及能否访问、跳转与过期时间；看起来像模型报错的问题，可能实际上是媒体下载失败。应把图片获取失败与视觉理解失败分开记录。视频、音频和媒体生成则需要自己的明确操作，不能从模型家族名称推导出来。

## 按完整工作负载比较费用

把一次完成的客服任务作为比较单位，记录输入、缓存输入、输出、重试与模态专用单位。若请求同时发送问题和图片，仅用问题的字符数无法估算全部输入费用。通过 KeepRouter 调用时，可以在 [API 费用计算器](/tools/api-cost-calculator)选择准确目录模型并填写报告用量；厂商直连账单应按其费率另行计算；工具尚未表达的计费类别应另行保留。

在候选路径上运行同一组小案例，再选择生产路径。分别判断质量、延迟和价格；若只有一条路径支持必要能力，它就是满足条件的候选，不能因为另一条不相关的文本单价更低就忽略功能缺口。应用也可以保留原生专有能力的路线，同时将普通文本工作交给兼容线路。

## 留下可供升级时复查的记录

保存 SDK 版本、端点类型、公开模型 ID、必要字段、通过的案例以及验证日期。任何一项变化后，都可使用 [API 迁移清单](/zh/blog/openai-compatible-api-migration-checklist)重新检查。最终交付应是一份其他开发者能够重跑的记录，而不是所有 Gemini 模型永久等同于所有 OpenAI 模型的承诺。

## 用一次工具对话定位兼容差异

选择无副作用、JSON Schema 简单的查询工具，检查首轮参数，再用匹配调用标识返回合成结果，确认最终回答使用了该结果。参考 [Google 函数调用文档](https://ai.google.dev/gemini-api/docs/function-calling)，请求形态则遵循目标端点。这样能检查一个具体 Agent 交互，无需移动真实客户数据，也不必假设原生与兼容接口的工具历史可以混用。

## KeepRouter 当前可用的 Gemini 型号

2026-09-29，九个 Gemini 聊天 ID 已完成限制输出长度的文字调用检查。[Gemini 模型与价格指南](/zh/blog/gemini-api-models-pricing-guide)列出确切 ID、OpenAI SDK 示例，以及流式、JSON 和完整工具往返分别验证的型号。请按当前模型详情页价格，结合自己的任务与通过标准比较成本。

## 常见问题

### Google 兼容端点和 KeepRouter 是同一端点吗？

不是。两者的 URL、Key、目录与账单不同，应分别配置。

### extra_body 能保证 Gemini 扩展透传吗？

不能。应确认所选服务如何处理该扩展，并测试具体请求。

### 所有 Gemini 请求都应使用原生 API 吗？

功能依赖原生契约时应使用它；经过独立验证的操作也可以使用兼容线路。

### 图文请求怎样估算费用？

应使用报告用量与所选服务计费单位；只统计文字字符数无法覆盖图片输入。

## 参考的一手资料

_本文最近复核 2026-09-29_

1. [Google Gemini OpenAI compatibility](https://ai.google.dev/gemini-api/docs/openai)
2. [Google Gemini function calling](https://ai.google.dev/gemini-api/docs/function-calling)
3. [KeepRouter OpenAPI](https://keeprouter.com/api/openapi.json)
4. [Google Cloud OpenAI compatibility](https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/migrate/openai/overview)

## 继续阅读

- [gemini 3.5 flash](https://keeprouter.com/models/gemini-3.5-flash.md)
- [openai sdk](https://keeprouter.com/use-cases/openai-sdk.md)
- [OpenAI 兼容 API 迁移清单](https://keeprouter.com/zh/blog/openai-compatible-api-migration-checklist.md)
- [api cost calculator](https://keeprouter.com/tools/api-cost-calculator)
- [Doubao 多模态 Embedding：建立一个图文检索小样本](https://keeprouter.com/zh/blog/doubao-multimodal-embedding-retrieval.md)
- [KeepRouter Gemini API：模型选择、接入与费用核对](https://keeprouter.com/zh/blog/gemini-api-models-pricing-guide.md)

## 迁移前，先检查你的请求

在浏览器中检查型号 ID 与请求字段，无需 API Key，也不发送推理请求。

[检查示例配置](https://keeprouter.com/tools/api-migration-checker)

[创建 Key，测试免费模型](https://keeprouter.com/login?returnTo=%2Fconsole%2Fkeys%3Fmodel%3Dfree)

免费测试使用 free 模型；其他付费型号需要足够预付额度。

[全部文章](https://keeprouter.com/zh/blog.md) · [模型与价格](https://keeprouter.com/models.md)