用 OpenAI SDK 调用 Gemini：只改 base_url、API Key 和模型名的接入教程

Google 把事说得很直：Gemini models 可以通过 OpenAI 的 Python 和 TypeScript/JavaScript SDK 访问，核心就是改三行代码。官方兼容文档给出的端点是 https://generativelanguage.googleapis.com/v1beta/openai/，示例模型是 gemini-3.5-flash（Google OpenAI compatibility）。这对已有 OpenAI SDK 项目很友好：不用先拆 provider 抽象，不用换整套调用栈，先跑通再说。

先确认你要调的模型

截至 2026-06-14，Google 模型页列出 Gemini 3.5 Flash 为 Stable，并说明模型代码是 gemini-3.5-flash；该模型输入上限 1,048,576 tokens，输出上限 65,536 tokens，支持文本、图片、视频、音频和 PDF 输入，输出为文本（Gemini 3.5 Flash）。模型页最后更新于 2026-05-19 UTC。

价格也要看当天文档。Google 价格页最后更新于 2026-06-09 UTC，gemini-3.5-flash Standard paid tier 标价为输入 $1.50 / 1M tokens、输出 $9.00 / 1M tokens，输出价包含 thinking tokens；Batch 是输入 $0.75、输出 $4.50（Gemini API pricing）。

模型	状态	输入上限	Standard 输入	Standard 输出
gemini-3.5-flash	Stable	1,048,576	$1.50 / 1M tokens	$9.00 / 1M tokens
gemini-3-flash-preview	Preview	见模型页	$0.50 / 1M tokens	$3.00 / 1M tokens
gemini-3.1-flash-lite	Stable	见模型页	$0.25 / 1M tokens	$1.50 / 1M tokens

gemini-3-flash-preview 和 gemini-3.1-flash-lite 来自 Google 的当前模型与价格页（Models、Pricing）。Preview 模型别直接当生产默认值，版本和限额可能变。

Python：把 OpenAI client 指到 Gemini

先装 SDK：

pip install openai
export GEMINI_API_KEY="你的 Gemini API Key"

然后保留 OpenAI SDK 的调用方式：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "你是一个简洁的工程助手。"},
        {"role": "user", "content": "用三句话解释什么是 API 兼容层。"},
    ],
)

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

真正改动只有三处：api_key 换成 Gemini key，base_url 换成 Google 的 OpenAI-compatible endpoint，model 换成 Gemini 模型名。注意官方示例里的 URL 末尾有 /，别手欠删掉后再去排查 404。

TypeScript：同样是 baseURL

Node 项目里也一样：

npm install openai
export GEMINI_API_KEY="你的 Gemini API Key"

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "user", content: "给我一个 JSON Schema 校验的最小例子。" },
  ],
});

console.log(response.choices[0].message.content);

如果你的项目已经把 provider 封装成环境变量，改动会更小：

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="$GEMINI_API_KEY"
OPENAI_MODEL="gemini-3.5-flash"

很多老项目的坑在这里：变量名还叫 OPENAI_API_KEY 没关系，值可以是 Gemini key；真正决定请求去哪的是 base_url/baseURL。

流式、工具调用和 thinking 怎么办

Google 兼容文档给了 streaming、function calling、structured outputs、image understanding 等示例（OpenAI compatibility）。已有 OpenAI SDK 项目通常先验证三件事：普通 chat、stream=True、tools/function calling。都过了，再处理模型特有能力。

thinking 参数要谨慎。兼容文档写到 OpenAI 的 reasoning_effort 会映射到 Gemini 的 thinking 配置；但 Gemini 3 和部分 2.5 模型不能完全关闭 thinking。我的建议很简单：第一版别调 thinking，先用默认值建立质量和成本基线，再在长任务、代码代理、复杂推理链路里单独压测。

如果你想少管几套 Key

官方直连适合严肃生产：账单、限额、数据策略都清楚。问题是团队常常不只用 Gemini，还要 Claude、GPT，甚至要给不同工具配不同 key。省事路径是用 onehop：把 OpenAI SDK 的 base URL 改成 https://api.onehop.ai/v1，同一套 OpenAI/Anthropic 兼容入口调用 Claude/GPT/Gemini；新账号送 $10，无需绑卡，适合先跑 demo 和内部工具。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[{"role": "user", "content": "把这段日志总结成 5 条排障线索。"}],
)

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

这里我故意把 model 放到环境变量：网关的模型名以控制台为准，别在代码里写死。想少折腾多厂商账单和兼容层，可以直接试：在 onehop 上调用 Claude 等模型，或者先领额度：注册即送 $10 体验额度。

接入前的最后检查

上线前别只看能不能返回文本。至少做四个检查：第一，确认模型在 Google 当前模型页仍可用；第二，用价格页核对输入、输出、Batch、Search grounding 费用；第三，把 401、429、5xx 的错误日志打完整；第四，给 base_url、api_key、model 做运行时配置，不要发版才能切模型。

这次接入的重点不是“换一家模型厂商”，而是把 SDK 层和模型供应商解耦。先用 Google 官方 OpenAI compatibility 跑通 gemini-3.5-flash，再决定直连、网关、还是两者并存。这样改动小，回滚也快。