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

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

发布 2026-09-23 · 更新 2026-09-29 · KeepRouter Editorial · 6 分钟阅读

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

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

先确认需要哪一种路径

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

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

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

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 指南与 API 参考说明 KeepRouter 面向客户端的契约。

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

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

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

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

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

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

按完整工作负载比较费用

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

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

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

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

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

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

KeepRouter 当前可用的 Gemini 型号

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

常见问题

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

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

extra_body 能保证 Gemini 扩展透传吗？

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

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

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

图文请求怎样估算费用？

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

参考的一手资料

本文最近复核 2026-09-29

1. [1] Google Gemini OpenAI compatibility
2. [2] Google Gemini function calling
3. [3] KeepRouter OpenAPI
4. [4] Google Cloud OpenAI compatibility

继续阅读

• gemini 3.5 flash
• openai sdk
• OpenAI 兼容 API 迁移清单
• api cost calculator
• Doubao 多模态 Embedding：建立一个图文检索小样本
• KeepRouter Gemini API：模型选择、接入与费用核对