Gemini API 怎么用 OpenAI SDK 调用？Python 接入与中转配置教程

如果你的项目已经使用 OpenAI SDK，现在又想接入 Gemini，通常会遇到一个问题：

能不能继续用现有代码调用 Gemini，而不用重新写一套接口？

可以，前提是你使用的 Gemini 中转 API 支持 OpenAI Chat Completions 兼容格式。

在这种情况下，最小接入通常只需要配置三个参数：

• api_key：中转平台提供的 API Key
• base_url：平台文档中的 OpenAI 兼容接口地址
• model：平台实际支持的 Gemini 模型名称

这篇文章重点讲解 使用 Python 和 OpenAI SDK 调用 Gemini API 的方法，适合已经有 OpenAI 接口代码，或者希望通过统一接口接入多个大模型的开发者。

大模型 API 中转服务入口：

平台地址：https://quanzil.com

平台地址：https://quanzil.net

具体支持的 Gemini 模型、接口地址、价格和功能，请以平台后台与开发文档为准。

---

为什么用 OpenAI SDK 调用 Gemini

接入多个大模型时，开发者经常需要处理不同的请求格式、返回结构和错误信息。

如果你的项目分别对接多个厂商的原生 API，通常需要维护各自的：

• 鉴权方式
• SDK 和依赖
• 消息结构
• 流式响应处理
• 错误处理逻辑

对于聊天助手、内容生成、摘要和知识库问答这类应用，使用 OpenAI 兼容接口，可以复用一部分现有代码。

例如，业务层继续使用：

client.chat.completions.create(...)

通过修改模型配置，调用平台支持的 Gemini 模型。

不过，兼容接口不代表所有功能都完全一致。图片输入、工具调用、结构化输出和其他高级功能，需要分别确认平台是否支持。

如果你还不清楚中转 API 的作用，可以先阅读：

• API中转站是什么？一篇看懂大模型 API 中转的作用与适用场景
• 大模型 API 中转和官方 API 有什么区别？开发者如何选择

---

Gemini 官方 API 和中转 API 的配置有什么区别

使用 Gemini 官方接口和使用 Gemini 中转 API，不能直接混用配置。

配置项	Gemini 官方接口	OpenAI 兼容中转接口
API Key	对应官方服务的凭据	中转平台签发的 Key
请求地址	官方文档中的地址	中转平台提供的 Base URL
调用格式	按官方接口说明配置	按平台支持的 OpenAI 兼容格式配置
模型名称	官方支持的模型 ID	平台模型列表中的 ID
计费与额度	对应官方账户	对应中转平台账户

最容易出错的情况是：使用一个平台的 Key，却请求另一个平台的地址。

接入前，先确认 API Key、Base URL 和模型名称来自同一套服务配置。

本文后续示例使用 OpenAI 兼容中转接口。

---

调用 Gemini API 前需要准备什么

先从平台后台或开发文档确认以下信息。

1. API Key

API Key 用于请求鉴权。

通过 OpenAI SDK 调用时，SDK 会根据 api_key 配置处理相应的请求头。

建议将 Key 放在服务端环境变量中，避免写进前端代码或公开仓库。

2. Base URL

Base URL 是 SDK 发送请求时使用的接口基础地址。

例如，平台文档可能提供：

https://your-api-domain.com/v1

这里的域名是占位示例，需要替换成平台实际提供的地址。

如果使用 OpenAI SDK，一般配置的是基础地址；SDK 再根据调用方法拼接相应接口路径。

3. Gemini 模型名称

模型名称必须与平台支持列表一致。

不要根据网页产品名称自行猜测模型 ID，也不要默认某个历史版本仍然可用。

下面的代码通过 GEMINI_MODEL 环境变量读取模型名称，方便你填写平台当前支持的 Gemini 模型。

---

第一步：安装 Python OpenAI SDK

在终端执行：

python -m pip install --upgrade openai

如果项目使用虚拟环境，先激活对应环境，再安装依赖。

安装完成后，可以检查：

python -m pip show openai

如果运行代码时提示：

ModuleNotFoundError: No module named 'openai'

通常需要检查安装依赖时使用的 Python，是否与运行脚本时使用的 Python 一致。

---

第二步：配置 API Key、Base URL 和模型

在 macOS 或 Linux 终端中设置环境变量：

export OPENAI_API_KEY="替换为你的中转平台API Key"
export OPENAI_BASE_URL="替换为平台文档中的Base URL"
export GEMINI_MODEL="替换为平台支持的Gemini模型ID"

如果使用 Windows PowerShell：

$env:OPENAI_API_KEY="替换为你的中转平台API Key"
$env:OPENAI_BASE_URL="替换为平台文档中的Base URL"
$env:GEMINI_MODEL="替换为平台支持的Gemini模型ID"

这里沿用 OPENAI_API_KEY 和 OPENAI_BASE_URL 的命名，是为了方便配置 OpenAI SDK。

这些变量名并不表示你必须使用 OpenAI 官方服务。 实际请求发送到哪里，取决于你设置的 Base URL。

以上命令通常只对当前终端会话生效。部署到服务器、容器或云平台时，需要在对应运行环境中配置变量。

---

第三步：用 Python 发起第一次 Gemini 调用

创建一个 Python 文件，例如 gemini_demo.py：

import os
from openai import OpenAI

required_vars = [
    "OPENAI_API_KEY",
    "OPENAI_BASE_URL",
    "GEMINI_MODEL",
]

missing_vars = [
    name for name in required_vars
    if not os.environ.get(name)
]

if missing_vars:
    raise RuntimeError(
        "缺少环境变量：" + ", ".join(missing_vars)
    )

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
    timeout=60.0,
    max_retries=2,
)

response = client.chat.completions.create(
    model=os.environ["GEMINI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "请用三句话介绍 Gemini API 的用途。",
        }
    ],
)

if not response.choices:
    raise RuntimeError("接口未返回 choices，请检查响应和平台文档。")

print(response.choices[0].message.content)

运行：

python gemini_demo.py

当终端输出模型回复时，说明这次调用的鉴权、请求地址和模型配置已经能够正常工作。

建议先完成这个最小请求，再增加业务参数和复杂提示词，方便定位问题。

---

Gemini Base URL 应该怎么填

这是使用 OpenAI SDK 接入 Gemini 时最常见的配置问题之一。

假设平台提供的完整聊天接口地址为：

https://your-api-domain.com/v1/chat/completions

那么 SDK 的 Base URL 通常应设置为：

https://your-api-domain.com/v1

而不是再次填写完整的 /chat/completions 路径。

调用方式	通常填写的地址
requests.post() 或 cURL	完整接口地址
OpenAI(base_url=...)	平台提供的接口基础地址

部分平台会使用不同的路径结构，因此最终应按平台针对 OpenAI SDK 给出的配置说明填写。

遇到 404 时，优先检查 Base URL 和接口路径是否匹配。

---

如何实现 Gemini 流式输出

如果你在开发 AI 聊天页面，通常希望模型生成一部分内容，就先展示一部分内容。

这就是 流式输出。

在支持该功能的 OpenAI 兼容接口中，可以设置：

stream=True

下面的示例复用前面已经创建的 client：

stream = client.chat.completions.create(
    model=os.environ["GEMINI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "请介绍如何通过 API 中转站接入 Gemini。",
        }
    ],
    stream=True,
)

for chunk in stream:
    if not chunk.choices:
        continue

    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)

print()

流式输出适合：

• AI 聊天助手
• 在线问答
• 长文生成
• 代码解释
• 需要尽快展示首段回答的页面

它可以改善等待体验，但不会自动降低 token 费用。计费仍应以平台实际规则为准。

---

Gemini API 怎么实现多轮对话

通过 Chat Completions 兼容接口实现多轮对话时，通常需要将相关历史消息一并传入。

例如：

messages = [
    {
        "role": "user",
        "content": "我准备开发一个电商客服机器人。",
    },
    {
        "role": "assistant",
        "content": "可以先整理商品信息、物流规则和售后政策。",
    },
    {
        "role": "user",
        "content": "如果用户问退货流程，应该怎样回答？",
    },
]

response = client.chat.completions.create(
    model=os.environ["GEMINI_MODEL"],
    messages=messages,
)

print(response.choices[0].message.content)

第二次提问时，模型就能结合前面的电商客服场景进行回答。

需要注意：这类请求通常不会自动保存你的业务对话历史。 应用需要自行管理上下文，并在后续请求中传入需要保留的消息。

随着对话增长，输入 token 和调用成本也可能增加。可以根据业务需要保留最近几轮消息，或者对较早的内容生成摘要。

---

Gemini API 能不能直接替换原来的 GPT 调用

如果你的项目使用的是基础文本对话，并且平台支持相同的 OpenAI 兼容格式，通常可以复用主要调用逻辑。

例如，原来使用：

response = client.chat.completions.create(
    model=original_model,
    messages=messages,
)

切换到 Gemini 时，可以将 model 改为平台支持的 Gemini 模型 ID。

如果你同时更换服务提供商，还需要修改 API Key 和 Base URL。

但上线前仍然需要验证：

• 提示词在新模型上的效果
• 输出格式是否满足业务要求
• 响应速度与超时情况
• 工具调用或结构化输出是否兼容
• 输入输出限制和实际价格

接口格式相近，可以减少代码修改；实际业务效果仍需要使用真实样例测试。

---

Gemini Flash 和 Pro 应该怎么选

Gemini 不同系列、不同版本的能力和价格会变化。选择时，建议结合平台当前支持的模型进行比较。

业务需求	可以优先测试的方向	主要观察指标
简单问答、分类、短摘要	Flash 类模型	成本、速度、准确率
复杂分析、代码、长文理解	Pro 类模型	任务完成质量、延迟
图片理解、图文问答	支持图片输入的模型	图片格式支持、识别效果
大量重复任务	满足质量要求的低成本模型	总成本、失败率、吞吐量

Flash 类模型通常更注重速度和效率，Pro 类模型通常面向更复杂的任务。

不过，不能只按系列名称判断。不同版本之间可能存在明显差异，建议准备一组真实业务问题，对比输出质量、调用耗时和费用后再决定。

模型价格可以结合以下页面查看：

• 价格说明

---

使用 OpenAI SDK 调用 Gemini 的常见报错

401：API Key 或鉴权配置有问题

出现 401 Unauthorized 时，先检查：

1. API Key 是否完整，是否包含多余空格。
2. Key 是否有效。
3. Key 是否属于当前请求的中转平台。
4. 程序是否读取到了正确的环境变量。

模型权限和账户状态也可以结合平台返回的错误内容进一步检查，不要只根据状态码猜测原因。

404：接口路径或模型名称不匹配

出现 404 时，可以依次检查：

• Base URL 是否按 SDK 文档填写
• 是否重复添加了接口路径
• 平台是否支持 Chat Completions 接口
• 模型 ID 是否存在

部分平台会对不存在的模型返回 400，因此应同时查看错误正文。

400：请求参数不受支持

常见原因包括：

• 消息格式有误
• 使用了当前模型不支持的参数
• 输入长度超过限制
• 图片或工具调用格式不符合要求

排查时可以先只保留：

model=...
messages=...

最小请求成功后，再逐个添加 temperature、输出长度限制、工具调用等参数。

不同模型和兼容平台的参数支持范围可能不同，不建议直接照搬其他模型的全部配置。

429：限流或配额不足

429 可能表示请求过于频繁，也可能与账户配额有关。

应先查看错误详情：

• 如果是频率或并发限制，可以降低并发、排队并进行退避重试。
• 如果是余额或配额不足，需要处理账户额度，反复重试通常无法解决。

本文示例设置了有限次数的 SDK 重试。正式项目中，如果业务层也增加重试，需要控制总尝试次数，避免重复请求过多。

请求超时或连接失败

可以检查：

• Base URL 是否正确
• 服务器是否能访问目标地址
• 请求内容是否过长
• 目标模型是否正在处理复杂任务
• 平台服务状态是否正常

适当增加超时可以帮助长任务完成，但对于持续发生的连接问题，还需要检查网络和服务状态。

---

Gemini API 调用成本怎么控制

成本优化应同时考虑模型价格和实际 token 用量。

减少不必要的历史消息

每次请求都传完整历史，可能使输入成本不断增长。

可以只保留相关内容，避免重复发送已经不影响当前任务的信息。

根据任务控制输出长度

短摘要、分类和数据提取，通常不需要长篇回答。

可以在提示词中明确字数或格式要求，并按平台文档配置当前模型支持的输出长度参数。

为重复请求增加缓存

对于固定 FAQ、相同文档摘要等任务，可以在业务层缓存结果。

缓存键需要包含模型、输入和相关配置，避免不同任务误用同一份结果。

记录实际使用量

如果兼容接口返回 usage，可以读取：

if response.usage is not None:
    print(response.usage.model_dump())

不同平台提供的统计字段可能不同，最终费用应以平台账单和计费规则为准。

---

常见问题

使用 OpenAI SDK 调用 Gemini，需要 OpenAI 官方 Key 吗？

如果你调用的是中转平台，就应使用该平台提供的 Key，并配置该平台的 Base URL。

Key 与请求地址需要匹配。

Gemini API Key 可以直接放到网页前端吗？

不建议。

浏览器中的代码和请求容易被查看，Key 可能被他人复制使用。常见做法是由你的服务端调用中转 API，前端向自己的服务端提交请求。

调用 Gemini 一定需要更换 SDK 吗？

如果平台支持你需要的 OpenAI 兼容功能，可以继续使用 OpenAI SDK。

如果要使用 Gemini 特有功能，则需要确认中转接口是否支持，或者采用对应服务提供的接入方式。

可以在同一个项目里切换 Gemini、GPT 和 Claude 吗？

如果中转平台支持这些模型的兼容调用，可以将模型名称做成配置，复用基础请求流程。

高级参数、工具调用和多模态输入仍需要分别验证。

Gemini 流式输出为什么没有内容？

可以检查平台是否支持流式接口、是否正确读取 delta.content，以及程序是否持续消费响应流。

如果经过自己的后端转发，还需要检查后端和代理层是否对响应进行了缓冲。

---

开始接入 Gemini 中转 API

使用 OpenAI SDK 调用 Gemini，可以先按以下顺序完成：

1. 在平台获取 API Key。
2. 从文档确认 SDK 使用的 Base URL。
3. 从模型列表复制可用的 Gemini 模型 ID。
4. 配置环境变量并运行最小请求。
5. 根据业务增加流式输出、多轮对话和错误处理。
6. 使用真实任务比较模型效果与调用成本。

对于已经有 OpenAI SDK 代码的项目，Gemini 中转 API 的价值在于复用基础调用流程，减少多模型接入时的重复工作。

你可以从以下入口查看服务与接入信息：

大模型 API 中转站：https://quanzil.com

大模型 API 中转站：https://quanzil.net

接入前，建议结合文档确认模型支持范围、价格、限流和所需功能：