Base URL and SDK Migration2026年6月22日Big Y

OpenAI 兼容 API 迁移：将 Base URL 改为 Flatkey

将 OpenAI 兼容应用迁移到 Flatkey：更改 base URL、映射 model IDs、运行 smoke tests，并验证日志、配额、计费和回滚。

如果你的应用已经使用了OpenAI 兼容 API，迁移到 Flatkey 不应从重写开始。更可控的路径更小：获取一个 Flatkey key，将你的 OpenAI 兼容 SDK 指向 https://router.flatkey.ai/v1，从 Flatkey 目录中选择一个模型 ID，并在发送真实流量之前，在日志、配额和计费中验证第一请求。

OpenAI 兼容 API 的实际价值就在于此。它让团队在保留常见请求相同心智模型的同时，将提供方访问放在一个统一网关之后。Flatkey 的公开产品文案正是围绕这一点构建的：一个 API key、一个基础 URL、清晰定价、统一计费，以及一个用于密钥、用量和路由的仪表板。

本指南展示迁移运行手册。它涵盖基础 URL 更改、SDK 示例、模型 ID 映射、冒烟测试、端点检查、用量日志审查、配额设置、计费验证和回滚。当你将现有的 Chat Completions 风格工作流迁移到 Flatkey，或通过一个 OpenAI compatible API 端点标准化多模型栈时，请使用它。

快速回答：迁移到 OpenAI 兼容 API 会有哪些变化？

对于大多数现有的 OpenAI 兼容聊天客户端来说，第一次迁移是一次配置变更，而不是应用重写。

设置	迁移前	使用 Flatkey 后
API key	特定提供商的 OpenAI、Gemini、DeepSeek 或代理 key	Flatkey API key
Base URL	提供商默认值或其他 OpenAI 兼容 base URL	`https://router.flatkey.ai/v1`
Chat endpoint	`/v1/chat/completions`	通过 Flatkey 的 `/v1/chat/completions`
Model	现有提供商的 model ID	从定价/控制台中选择的 Flatkey model ID
Validation	仅成功响应	响应 + 使用日志 + 成本 + 配额 + 回滚

关键字是“兼容”。OpenAI compatible API 并不保证每个提供商、模型、端点和参数的行为都与 OpenAI 完全一致。它的意思是，该 API 遵循了足够多的 OpenAI 请求和响应模式，使常见的客户端调用在 base URL、key 和 model 正确时能够正常工作。你的迁移清单应当验证应用实际使用到的具体功能。

为什么 OpenAI 兼容端点正在成为迁移层

OpenAI compatible API 的搜索结果大多是官方参考文档、提供商文档、插件、本地服务器文档以及社区问题。这很合理。开发者问的不只是“什么是兼容的？”他们真正想做的是在不改动每个调用点的情况下，在不同模型提供商之间迁移代码。

Google 的 Gemini 文档展示了 OpenAI 库示例：设置 Gemini 的 OpenAI 兼容 base URL，然后调用 chat completions。DeepSeek 的官方 API 文档也展示了 OpenAI SDK 示例，使用 DeepSeek 的 base URL 和诸如 deepseek-chat、deepseek-reasoner 之类的模型 ID。这个模式很清楚：许多提供商都在开发者原本使用的 SDK 之处与他们对接。

Flatkey 也使用同样的迁移思路，但目标不同。它不是把某个提供商的 OpenAI compatible API 指向某个单一提供商账号，而是为团队提供一个统一的 OpenAI 兼容 base URL，用于多模型访问、统一计费以及仪表盘可见性。

第 1 步：盘点你已经在使用的客户端

在更改基础 URL 之前，先记录你当前应用实际使用的内容。一个干净的 OpenAI 兼容 API 迁移应从真实调用形态开始，而不是从一个新的示例应用开始。

检查项	需要记录的内容
SDK	Python、Node、直接 HTTP、LangChain、LiteLLM、Vercel AI SDK，或其他封装。
Endpoint	Chat Completions、Responses、embeddings、images、video，或提供商原生 endpoint。
Model ID	生产环境中使用的精确字符串以及任何回退模型。
Message shape	System prompts、developer messages、tool messages、多模态内容，或仅纯文本。
Parameters	Streaming、temperature、max tokens、tool calls、JSON 输出、response format、seed、timeout、retries。
Observability	你目前在哪里查看延迟、token 使用量、请求 ID、错误和成本。
Rollback	你能多快恢复旧的 API key/base URL/model。

这份盘点让迁移过程保持真实。如果你的应用只发送简单的聊天消息，那么第一次 Flatkey 测试可以保持很小。如果你的应用依赖 streaming、tool calls、JSON 模式、images、video 或 Responses API，则应将每个功能都视为单独的冒烟测试。

第 2 步：将基础 URL 放在一个配置层后面

不要把新的 OpenAI 兼容基础 URL 散落到整个代码库中。把它放进一个环境变量或一个 SDK 工厂里。

推荐的环境变量：

FLATKEY_API_KEY="sk-fk-your-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="replace-with-publish-day-model-id"
ROLLBACK_OPENAI_BASE_URL="https://api.openai.com/v1"
ROLLBACK_MODEL="your-previous-model-id"

使用 OPENAI_BASE_URL 往往很方便，因为许多 SDK 包装器已经支持这种约定。使用 FLATKEY_API_KEY 和 FLATKEY_MODEL 可以让新的凭证和模型选择保持显式。

这正是 Flatkey 契合 openai compatible base url 搜索意图的地方。迁移应该可以在一个 diff 中被审查：基础 URL、密钥、模型以及验证步骤。

步骤 3：运行 Curl 烟雾测试

在更改应用程序之前，先从直接的 HTTP 请求开始。这可以隔离密钥、基础 URL、端点和模型 ID 相关的问题。

仅作模板：审阅者应使用有效的 Flatkey 密钥以及已确认的发布日模型 ID 运行。

curl -sS "https://router.flatkey.ai/v1/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {
        "role": "user",
        "content": "Reply with one sentence confirming this Flatkey smoke test worked."
      }
    ]
  }'

一个有用的烟雾测试证明的不仅仅是 200 OK。对于 OpenAI 兼容 API 迁移，请检查：

响应包含可用的 assistant 消息。
模型名称是你原本打算测试的那个。
用量会显示在 Flatkey 仪表板或用量日志中。
Token 数和成本足以用于账单审核。
如果模型 ID 或密钥错误，错误信息是可以理解的。
旧的基础 URL 和模型仍然可以快速恢复。

步骤 4：更改 Python OpenAI SDK 配置

如果你的 Python 应用已经使用 OpenAI SDK，请保持客户端构建集中化。

仅模板：审核者应在发布前执行。

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_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "确认此 OpenAI 兼容 API 请求已通过 Flatkey 路由。",
        }
    ],
)

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

Python 中需要关注的细节是 base_url。在一次干净的OpenAI 兼容 API迁移中，应用代码不应知道基础 URL 是直接指向 OpenAI、某个兼容提供商端点，还是 Flatkey。它应该调用共享客户端，并让配置来决定路由。

步骤 5：更改 Node OpenAI SDK 配置

对于 Node 应用，等效配置使用 baseURL。

仅模板：审阅者应在发布前执行。

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_MODEL,
  messages: [
    {
      role: "user",
      content: "确认此 OpenAI 兼容的 API 请求是否通过 Flatkey 路由。",
    },
  ],
});

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

这与各个提供商文档中看到的迁移模式相同：保留 SDK，设置不同的基础 URL，提供兼容的 API 密钥，并选择目标平台上存在的模型 ID。

步骤 6：刻意映射模型 ID

模型字符串是许多OpenAI 兼容 API迁移失败的地方。基础 URL 可能兼容，但模型 ID 仍然是供应商特定的。

不要假设：

你旧的模型名称在 Flatkey 中存在。
某个供应商的模型别名在网关后面指向相同版本。
每个兼容模型都支持相同的端点家族。
一个可用于聊天的模型也同样可用于视觉、工具、图片、视频或 Responses。

相反，在第一次应用层测试之前，请使用此映射表：

当前应用用途	Flatkey 检查项
文本聊天	选择一个支持 OpenAI 聊天端点的 Flatkey 模型。
流式聊天	使用相同的提示和超时预算单独测试流式传输。
工具/函数调用	验证所选模型和端点支持你的应用发送的工具调用形状。
JSON 输出	测试你精确的 `response_format` 或结构化输出模式。
视觉/图像输入	确认所选模型接受你的 SDK 发送的图像输入格式。
Responses API	确认 Flatkey 端点/模型支持适用于你用例的 `/v1/responses`。
图像或视频生成	将其视为单独的端点迁移，而不是聊天补全迁移。

Flatkey 在 2026 年 6 月 11 日的价格快照显示了 OpenAI 聊天补全、OpenAI Responses、Anthropic messages、Gemini、图像生成和 OpenAI 视频的端点家族。这对于审阅者来说是有用的证据，但文章仍应推动读者在发布当天确认他们计划使用的确切模型和功能。

步骤 7：验证日志、配额和计费

一个成功的 OpenAI compatible API 响应只是第一个检查点。通过 Flatkey 迁移的原因不只是请求形态；更重要的是围绕模型访问的运行层。

在完成冒烟测试后，请验证：

领域	要检查什么
使用日志	请求是否带有时间戳、模型、token 使用量、状态，以及如有的话错误详情。
计费	成本是否可见，并与预期的模型/定价单位相符。
配额	在更大范围推广之前，能否为新密钥或测试路由设置较小的配额。
路由	请求是否通过预期的 Flatkey 路径路由，而不是过期的直连提供方配置。
错误行为	错误的密钥、错误的模型以及不支持的参数错误是否足够清晰，便于支持排查。
回滚	恢复之前的 base URL/模型是否无需代码更改即可工作。

这正是 OpenAI compatible API 网关比原始提供方端点更有用的地方。base URL 的更改应当带来更好的可见性，而不仅仅是切换到另一个上游。

步骤 8：分阶段推进

不要一次性迁移所有工作流。请采用分阶段发布：

先运行一次直接的 curl 冒烟测试。
再在本地或预发布环境运行一次 SDK 冒烟测试。
回放一小组已知提示词，并比较输出形态。
仅在基础调用通过后，再启用流式传输或高级参数。
为测试密钥设置较低的配额。
先发送一小部分非关键流量。
比较错误、延迟、令牌使用量和成本。
只有在日志和计费结果符合预期后，才增加流量。

这一流程将 OpenAI 兼容 API 的承诺与生产实际表现绑定在一起。兼容性不是一句口号；它是对你的应用实际发送请求的测试结果。

迁移检查清单

将此作为发布页面资源使用。

步骤	完成？	备注
已记录当前 SDK 和端点		Python、Node、HTTP、wrapper、chat、responses、image、video 等。
已创建 Flatkey key		尽可能使用单独的测试 key。
Base URL 已集中管理		`https://router.flatkey.ai/v1` 应放在配置中，而不是散落在代码里。
已从 Flatkey 选择 model ID		请从定价或仪表板确认发布当天的 model ID。
Curl 冒烟测试通过		模板在发布前必须经过审阅者测试。
Python 或 Node SDK 冒烟测试通过		使用你的应用实际运行的 SDK。
已测试流式传输/工具/JSON/视觉功能		只测试你使用的功能。
使用日志可见		在仪表板中确认 model、状态、token 和错误。
已检查计费和定价单位		不要假设不同提供商的定价单位是相同的。
已设置配额限制		保持迁移流量在可控范围内。
回滚环境变量已准备就绪		无需更改代码即可恢复旧的 base URL 和 model。