模型与多模态实用指南2026年9月22日Flatkey Team

Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置

设置 Gemini 的 OpenAI 兼容基础 URL，对比直接访问 Google 与 Flatkey 路由，并验证模型 ID、SDK 配置和使用日志。

如果您已经在使用 OpenAI SDK，测试 Gemini 的最快方法就是更改 API 密钥、基础 URL 和模型 ID。官方的 Gemini API OpenAI 兼容基础 URL 是：

https://generativelanguage.googleapis.com/v1beta/openai/

对于 Flatkey，OpenAI 兼容路由器的基础 URL 是：

https://router.flatkey.ai/v1

这就是 Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置的核心：直接使用 Gemini 时采用 Google API 密钥和 Google 的 OpenAI 兼容端点；使用 Flatkey 时则采用 Flatkey 密钥、Flatkey 路由器，以及您在 Flatkey 账户中可用的 Gemini 模型 ID。

当您只需要 Gemini，并且希望采用最接近提供商原生设置的方式时，请使用直接 Google 路由。当您已经在对比 Gemini 与 GPT、Claude、DeepSeek、Qwen 或其他模型，并希望使用一个 OpenAI 兼容基础 URL、一个模型列表和一份使用日志时，请使用 Flatkey 路由。

Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置一览

设置选项	基础 URL	API 密钥	模型 ID 来源	最适合
直接 Gemini	`https://generativelanguage.googleapis.com/v1beta/openai/`	Gemini API 密钥	Google Gemini API 模型文档或 `client.models.list()`	您只需要 Gemini，并且希望直接访问 Google。
Flatkey 路由器	`https://router.flatkey.ai/v1`	Flatkey API 密钥	Flatkey `/v1/models` 或模型目录	您希望在一个密钥下同时使用 Gemini 和其他模型提供商。

不要混用这两者。Gemini API 密钥无法对 Flatkey 进行身份验证，Flatkey 密钥也无法对 Google 的直接 Gemini 端点进行身份验证。

使用 OpenAI SDK 的直接 Gemini 设置

Google 的 OpenAI 兼容层让您在常见的聊天补全工作流中保留 OpenAI SDK 的形态。关键区别在于客户端配置。

Python

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[
        {"role": "user", "content": "写一句关于模型路由的话。"}
    ],
)

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

JavaScript

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "gemini-3.8-flash",
  messages: [
    { role: "user", content: "写一句关于模型路由的话。" },
  ],
});

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

REST

curl https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [
      {"role": "user", "content": "写一句关于模型路由的句子。"}
    ]
  }'

在发布之前，针对相同的 base URL 运行 client.models.list() 或 GET /openai/models。这可以捕捉最常见的错误：从博客文章中复制旧的模型 ID，并假设它仍然适用于你的账户。

Gemini 的 Flatkey 路由设置

Flatkey 保留了 OpenAI SDK 的结构，但 base URL 和 key 又会发生变化。你需要使用 Flatkey router，然后从 Flatkey 的 /v1/models 响应或实时 Model Directory 中选择一个 Gemini 模型 ID。

Python

import os
from openai import OpenAI

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

models = client.models.list()
gemini_models = [model.id for model in models.data if "gemini" in model.id]
print(gemini_models)

response = client.chat.completions.create(
    model=os.environ.get("FLATKEY_GEMINI_MODEL", "gemini-2.5-flash"),
    messages=[
        {"role": "user", "content": "写一句关于模型路由的句子。"}
    ],
)

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

JavaScript

import OpenAI from "openai";

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

const models = await client.models.list();
console.log(models.data.map((model) => model.id).filter((id) => id.includes("gemini")));

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_GEMINI_MODEL || "gemini-2.5-flash",
  messages: [
    { role: "user", content: "写一句关于模型路由的句子。" },
  ],
});

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

在生产环境中，不要假设 Google 的直接模型 ID 和 Flatkey 的路由模型 ID 会始终完全相同。应将模型列表视为你所调用账户的事实来源。

保持切换可逆的环境变量

一个干净的 Gemini API OpenAI 兼容基础 URL 和 Flatkey 路由设置，应该让直连和路由测试可以轻松对比，而无需编辑应用代码。

# 直接 Gemini
GEMINI_API_KEY="..."
GEMINI_OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
GEMINI_MODEL="gemini-3.8-flash"

# Flatkey router
FLATKEY_API_KEY="..."
FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_GEMINI_MODEL="gemini-2.5-flash"

然后从配置中选择路由：

import os
from openai import OpenAI

route = os.environ.get("AI_ROUTE", "flatkey")

if route == "direct_gemini":
    client = OpenAI(
        api_key=os.environ["GEMINI_API_KEY"],
        base_url=os.environ["GEMINI_OPENAI_BASE_URL"],
    )
    model = os.environ["GEMINI_MODEL"]
else:
    client = OpenAI(
        api_key=os.environ["FLATKEY_API_KEY"],
        base_url=os.environ["FLATKEY_BASE_URL"],
    )
    model = os.environ["FLATKEY_GEMINI_MODEL"]

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "精确返回：route ok"}],
)

这种模式让独立开发者可以先直接测试 Gemini，之后再接入 Flatkey，并且无需重写请求路径即可回滚。

在迁移流量之前的烟雾测试清单

检查项	直接 Gemini	Flatkey 路由器
身份验证	确认 Gemini 密钥仅在 Google 的端点上可用。	确认 Flatkey 密钥仅在 `router.flatkey.ai` 上可用。
模型列表	针对 Gemini base URL 运行 `client.models.list()`。	针对 Flatkey 运行 `client.models.list()`，并筛选 Gemini ID。
基础聊天	发送一个简短的非流式聊天补全请求。	通过 Flatkey Gemini 模型发送相同提示。
流式传输	仅当你的应用使用流式传输时才测试流式。	在向用户启用之前，先在确切的路由模型上测试流式。
工具调用	如果你的应用使用工具，测试一个小型函数 schema。	确认路由后的模型支持你的应用所期望的工具行为。
结构化输出	验证真实的 JSON 输出，而不只是状态 `200`。	验证相同的 schema 和重试行为。
使用情况复核	在你的提供商账户中检查 Google 的使用情况和错误。	在 Flatkey Usage Logs 中检查模型、token 数、延迟和成本。

OpenAI 兼容并不意味着每个提供商特有功能的行为都完全一致。它意味着你的客户端形态可以足够接近，以支持常见的 SDK 工作流。烟雾测试应覆盖你的应用实际依赖的功能。

常见的 base URL 错误

在直接 Gemini 路由中遗漏 `/openai/`

对于直接的 OpenAI 兼容 Gemini 调用，请使用：

https://generativelanguage.googleapis.com/v1beta/openai/

不要把原生 Gemini 的 generateContent 端点与 OpenAI SDK 的聊天补全代码混用。原生 Gemini API 示例和 OpenAI 兼容示例的请求形态是不同的。

在 Node 中使用 `base_url` 或在 Python 中使用 `baseURL`

Python OpenAI SDK 配置使用 base_url。JavaScript SDK 使用 baseURL。

OpenAI(base_url="https://router.flatkey.ai/v1")

new OpenAI({ baseURL: "https://router.flatkey.ai/v1" })

将模型 ID 视为永久不变

模型名称变化得比 SDK 初始化代码还快。对于直连方式，请查看 Google 的模型文档，或通过 Gemini OpenAI 兼容端点列出模型。对于 Flatkey，请查看 /v1/models 和 Model Directory。

跳过日志

第一次成功响应并不意味着设置已经完成。在第一次 Flatkey 请求之后，打开 Usage Logs，确认模型、token 数量、延迟和成本。这会让 Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置在运营上可追踪，而不仅仅是语法正确。

Flatkey 何时更有价值

当 Gemini 只是更大模型栈中的一条路径时，Flatkey 就很有用。例如：

你希望通过一个 OpenAI 兼容的基础 URL 统一接入 Gemini、Claude、GPT、DeepSeek 和 Qwen。
你正在测试模型回退行为，不想让各个应用和 agent 中散落着不同的提供商密钥。
你需要一个共享的使用账本，用于记录模型 ID、token 数量、延迟和每次请求成本。
你希望开发者只修改 model 参数，而不更改 SDK 客户端。

如果你的应用以后只会调用 Gemini，那么直接的 Google 设置可能就足够了。如果你的产品已经在比较多个提供商，Flatkey 路由会给你更清晰的迁移路径。

值得保留打开的内部链接

常见问题

官方的 Gemini OpenAI 兼容基础 URL 是什么？

官方的 Gemini OpenAI 兼容基础 URL 是 https://generativelanguage.googleapis.com/v1beta/openai/。请使用 Gemini API key，而不是 Flatkey key。

通过 Flatkey 使用 Gemini 时应使用什么基础 URL？

请使用 https://router.flatkey.ai/v1 并配合 Flatkey API key。然后从 Flatkey 的 /v1/models 响应或实时 Model Directory 中选择一个 Gemini 模型 ID。

我可以在两个地方使用相同的 Gemini 模型 ID 吗？

有时可以，但不要默认如此。安全的做法是列出你正在使用的精确路由和账户对应的模型，然后把该 ID 固定到配置中。

OpenAI 兼容是否意味着功能完全一致？

不意味着。把 OpenAI 兼容视为 SDK 和请求形状上的便利。在正式上线前，针对确切的模型和路由测试流式输出、工具、结构化输出、文件和多模态输入。

独立开发者应该直接开始还是先用 Flatkey？

如果你只是想验证 Gemini 是否可用，就直接开始。如果真正要决定的是哪个模型应该为产品提供能力，而不是 Gemini 单独是否能回答提示，就先用 Flatkey。

要点总结

当你把两条路由分开看时，Gemini API OpenAI Compatibility Base URL 与 Flatkey Router Setup 就很简单：

直接 Gemini：https://generativelanguage.googleapis.com/v1beta/openai/
Flatkey 路由器：https://router.flatkey.ai/v1

保持密钥分离，在调用 chat completions 之前列出模型，测试应用所使用的功能，并在首次请求后验证用量。当你准备好通过一个 OpenAI 兼容层将 Gemini 与其他提供商进行比较时，创建一个 Flatkey 密钥，并一次迁移一个工作负载。

模型与多模态实用指南

Qwen API 价格（2026）：所有模型、地域与折扣详解

2026年9月16日Flatkey Team

模型与多模态实用指南

使用一个兼容 OpenAI 的路由器访问 MiniMax API

2026年9月16日Flatkey Team

模型与多模态实用指南

Claude OpenAI SDK 兼容性：哪些可用，哪些不可用

2026年6月22日Big Y

返回博客

Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置

Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置一览

使用 OpenAI SDK 的直接 Gemini 设置

Python

JavaScript

REST

Gemini 的 Flatkey 路由设置

Python

JavaScript

保持切换可逆的环境变量

在迁移流量之前的烟雾测试清单

常见的 base URL 错误

在直接 Gemini 路由中遗漏 `/openai/`

在 Node 中使用 `base_url` 或在 Python 中使用 `baseURL`

将模型 ID 视为永久不变

跳过日志

Flatkey 何时更有价值

值得保留打开的内部链接

常见问题

官方的 Gemini OpenAI 兼容基础 URL 是什么？

通过 Flatkey 使用 Gemini 时应使用什么基础 URL？

我可以在两个地方使用相同的 Gemini 模型 ID 吗？

OpenAI 兼容是否意味着功能完全一致？

独立开发者应该直接开始还是先用 Flatkey？

要点总结

相关文章

Qwen API 价格（2026）：所有模型、地域与折扣详解

使用一个兼容 OpenAI 的路由器访问 MiniMax API

Claude OpenAI SDK 兼容性：哪些可用，哪些不可用

热门模型

资源

算力

产品

开发者

公司

产品

资源

开发者

算力

Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置

Gemini API OpenAI 兼容基础 URL 与 Flatkey 路由设置一览

使用 OpenAI SDK 的直接 Gemini 设置

Python

JavaScript

REST

Gemini 的 Flatkey 路由设置

Python

JavaScript

保持切换可逆的环境变量

在迁移流量之前的烟雾测试清单

常见的 base URL 错误

在直接 Gemini 路由中遗漏 /openai/

在 Node 中使用 base_url 或在 Python 中使用 baseURL

将模型 ID 视为永久不变

跳过日志

Flatkey 何时更有价值

值得保留打开的内部链接

常见问题

官方的 Gemini OpenAI 兼容基础 URL 是什么？

通过 Flatkey 使用 Gemini 时应使用什么基础 URL？

我可以在两个地方使用相同的 Gemini 模型 ID 吗？

OpenAI 兼容是否意味着功能完全一致？

独立开发者应该直接开始还是先用 Flatkey？

要点总结

相关文章

Qwen API 价格（2026）：所有模型、地域与折扣详解

使用一个兼容 OpenAI 的路由器访问 MiniMax API

Claude OpenAI SDK 兼容性：哪些可用，哪些不可用

在直接 Gemini 路由中遗漏 `/openai/`

在 Node 中使用 `base_url` 或在 Python 中使用 `baseURL`