Model and Modality Playbooks2026年6月22日Big Y

通过路由器访问 Gemini API 的 OpenAI 兼容接口

通过 Flatkey 使用 Gemini API 的 OpenAI 兼容访问：设置 base URL、选择模型，并测试功能、日志、定价和回滚。

Gemini API OpenAI 兼容访问适用于两种不同的迁移路径。Google 文档说明了一个面向 Gemini 的直接 OpenAI 兼容端点，而 Flatkey 则为希望在与其他模型相同的单密钥网关中使用 Gemini 的团队提供了一条路由路径。

Google 的直接路径是将基础 URL 更换为 https://generativelanguage.googleapis.com/v1beta/openai/，并使用 Gemini API 密钥。Flatkey 路径则保留 OpenAI SDK 的调用形式，但将客户端指向 https://router.flatkey.ai/v1，使用 Flatkey 密钥，并在测试日志、成本和功能支持之前，从 Flatkey 目录中选择一个 Gemini 模型 ID。

本指南说明如何安全地使用 Gemini API OpenAI 兼容 路由。它涵盖了 Google 的兼容性文档实际支持什么、路由器会在何处改变运行模型，以及在将生产流量迁移之前需要验证哪些内容。

快速回答：Gemini API OpenAI 兼容路由

如果你的应用已经在使用 OpenAI Python 或 JavaScript SDK，那么 Gemini API OpenAI compatible 迁移应从配置开始，而不是重写。

决策	直接使用 Gemini API	通过 Flatkey 使用 Gemini
API key	来自 Google AI Studio 的 Gemini API key	Flatkey API key
Base URL	`https://generativelanguage.googleapis.com/v1beta/openai/`	`https://router.flatkey.ai/v1`
主要目标	使用 OpenAI SDK 语法调用 Gemini	通过一个 key 在 Gemini 和其他模型提供商之间路由
模型选择	来自 Google 文档的 Google Gemini 模型 ID	来自定价或控制台的 Flatkey Gemini 模型 ID
验证	响应、模型行为、Google 计费	响应、Flatkey 使用日志、计费单位、配额、回滚

当你只需要 Gemini，并且希望使用提供商原生的账号控制时，请使用 Google 直接端点。当 Gemini 需要与 GPT、Claude、DeepSeek、Qwen、图像、视频以及其他模型访问并列时，请使用 Flatkey 路由器，这样只需一个 key、一个控制台和一个计费界面。

Google 的 OpenAI 兼容文档确认了什么

Google 的 OpenAI 兼容性文档说明，Gemini 模型可通过更新 API 密钥、基础 URL 和模型，使用 OpenAI 的 Python 和 JavaScript 库以及 REST 访问。文档中给出的直接基础 URL 是 https://generativelanguage.googleapis.com/v1beta/openai/。

同一页面还展示了聊天补全、流式响应、函数调用、图像理解和嵌入的示例。它还指出，目前不支持与 OpenAI 兼容的文件上传和下载，因此文件工作流需要使用 Google GenAI 客户端处理，而不能假设与 OpenAI 的文件功能完全等价。

这就是任何 Gemini API OpenAI compatible 指南的核心结论：兼容性是按端点和功能分别定义的。聊天补全可以通过干净地迁移基础 URL 来实现，而文件上传、图像、批处理、工具或嵌入工作流仍然值得分别测试。

Flatkey 如何改变 Gemini 的设置

在第一次测试时，Flatkey 不会要求你用新的 provider SDK 替换一个兼容 OpenAI 的应用。Flatkey 的公开产品界面围绕一个 API key 构建，不需要单独的 provider 账户，定价清晰，统一计费，并且有一个用于 keys、usage 和 routing 的仪表盘。它还将兼容 OpenAI 的 router base URL 显示为 https://router.flatkey.ai/v1。

对于通过 Flatkey 进行 Gemini API OpenAI compatible 路由，关键变化不是 OpenAI SDK 的方法名。关键变化在于运营方式：

你从 Flatkey 选择 Gemini model ID，而不只是从 Google 的文档中选择。
你在请求完成后在 Flatkey 中验证 usage 和 cost，而不只是看应用返回结果。
你将 Gemini 保持在与其他 providers 相同的 routing 和 quota 工作流中。
你避免为每个团队或工具都创建单独的 provider-account 路径。
你通过配置来控制 base URL、key 和 model，从而保持回滚简单。

本文检查到的 Flatkey 实时定价快照包含以 Gemini 命名的 catalog 行，但可用性和具体 model 名称可能会变化。请将 catalog 视为发布当天的事实来源：先在 pricing 或 dashboard 中选择 model，然后在生产流量之前测试精确的 model ID。

Base URL 迁移模式

首先将迁移拆分为三个环境变量：

FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="replace-with-flatkey-gemini-model-id"

这为任何Gemini API OpenAI compatible客户端提供了一个干净的切换方式。应用代码保持 OpenAI 兼容的 SDK 路径不变。配置决定请求是直接发送到 Google、Flatkey，还是其他兼容端点。

Config Item	Why It Matters	What To Avoid
Base URL	将路由器选择保留在业务逻辑之外。	在多个文件中硬编码提供商 URL。
API key	将直接提供商凭据与路由器凭据分离。	为 Flatkey 路由重复使用旧的提供商密钥。
Model ID	让你可以有意地把 Google 模型映射到 Flatkey 目录中的模型。	假设路由器后面的每个提供商模型别名都存在。
Rollback values	让你能够快速恢复到之前的路由。	让回滚必须通过代码部署才能完成。

Flatkey Gemini 路由的 Python 模板

仅为模板：在生产环境中使用之前，请先使用有效的 Flatkey key 和已确认的 Flatkey Gemini model ID 运行此示例。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_GEMINI_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Reply with one sentence confirming the Gemini route is configured.",
        }
    ],
)

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

OpenAI SDK 方法很熟悉，但在 Flatkey 使用日志显示了请求、model、token usage、status 和 cost 之前，不要将其视为已完成的 Gemini API OpenAI compatible 迁移。

Flatkey Gemini 路由的 JavaScript 模板

仅为模板：请使用有效的 Flatkey 密钥以及当前 Flatkey 目录中已确认的模型 ID 运行。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL || "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_GEMINI_MODEL,
  messages: [
    {
      role: "user",
      content: "回复一句话，确认 Gemini 路由已配置。",
    },
  ],
});

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

对于已经在使用 OpenAI 兼容 SDK 的团队，这样可以将迁移工作保持在较小范围内。真正的生产工作在于功能验证、模型映射、配额以及计费检查。

生产前功能检查清单

在将 Gemini API OpenAI compatible 路由视为可用之前，请使用此检查清单。

功能	Google 文档信号	Flatkey 路由检查
基础聊天补全	已记录 OpenAI SDK 和 REST 示例。	确认响应和 Flatkey 使用日志。
流式传输	Google 文档中通过 OpenAI 风格调用进行流式传输。	测试流处理、超时和部分输出解析。
函数调用	Google 文档中通过兼容性示例进行工具/函数调用。	测试您精确的工具 schema 和工具选择行为。
图像理解	Google 文档中通过聊天补全进行图像输入。	确认 Flatkey 模型接受您的 SDK 发送的图像格式。
嵌入和批处理	Google 文档中的嵌入和与批处理相关的示例。	作为单独的端点路径进行测试，而不是当作聊天前提。
文件上传/下载	Google 表示当前不支持 OpenAI-compatible 上传/下载。	如果您的工作流依赖文件，请使用单独的提供商原生文件方案。
定价	Google 维护 Gemini Developer API 定价页面。	路由使用请使用 Flatkey 定价，然后核实实际成本日志。