Base URL and SDK Migration2026年7月24日Flatkey Team

Flatkey API 快速入门：通过 router.flatkey.ai 进行首次调用

创建 Flatkey API 密钥，切换到兼容 OpenAI 的 base URL，发起首次请求，读取响应，查看 Usage 与 Logs，并添加安全的故障切换路由。

Flatkey API 快速入门：通过 `router.flatkey.ai` 进行首次调用

如果你已经在使用 OpenAI SDK，那么进行第一次 Flatkey API 调用的最短路径很简单：创建一个 Flatkey 密钥，将客户端指向 https://router.flatkey.ai/v1，发送一次 chat-completions 请求，并在控制台中确认这次调用。

本快速入门将带你完成整个流程。它还会展示在第一个模型可用后，如何添加一个基础的回退序列，同时不隐藏错误，也不创建无限重试链。

你将完成什么

在本指南结束时，你将拥有：

一个 Flatkey 账户和 API 密钥。
一个使用 Flatkey 路由器的 OpenAI 兼容客户端。
一次成功的请求和一条可读的响应。
一个用于查看用量、成本和请求排查的控制台检查点。
一个你可以在生产前测试的小型回退模式。

对于这个冒烟测试，你不需要围绕一个新的 SDK 重写应用程序。Flatkey 的公开文档在 https://router.flatkey.ai/v1 提供了一个 OpenAI 兼容端点，因此常见的 chat、tool、streaming 和 structured-output 工作流可以继续使用熟悉的客户端形式。

开始之前

你需要：

一个 Flatkey 账户。
一个以 sk-fk- 开头的 Flatkey API 密钥。
如果你想使用 SDK 示例，则需要 Python 3.9+ 或 Node.js 18+。
一个当前可用于你账户的模型名称。

模型目录和可用性可能会变化。请使用当前的模型目录或控制台，而不是把旧的模型名称直接复制到生产环境中。

步骤 1：创建你的 Flatkey 账户

打开 Flatkey 注册流程并创建账户。登录后，使用控制台创建你的应用程序将在每次请求中发送的凭据。

控制台参考

进入 Console → API Keys。

为本快速入门创建一个密钥，并立即复制它。请像对待密码一样对待这个密钥：不要把它粘贴到客户端代码中，不要提交到 Git，不要包含在截图里，也不要在支持消息中发送它。

对于团队环境，请为不同的开发者或服务创建不同的密钥。Flatkey 的文档还说明了按密钥控制的选项，例如月度上限和可选的模型允许列表。这些控制有助于隔离测试、轮换某个凭据，或停止某个工作负载，而不会影响每个应用程序。

在你的 shell 中设置该密钥：

export FLATKEY_API_KEY="sk-fk-your-key-here"

如果你使用 .env 文件，请将其保存在版本控制之外：

FLATKEY_API_KEY=sk-fk-your-key-here

步骤 2：更改 base URL

OpenAI 兼容的 Flatkey base URL 是：

https://router.flatkey.ai/v1

这是本快速入门中最重要的配置变更。你的 API 密钥负责对请求进行身份验证，而 base URL 则会将请求通过 Flatkey 路由器发送，而不是直接发往其他提供商端点。

将这两个值都保留在环境配置中，这样你就可以在不修改应用逻辑的情况下更改它们：

export OPENAI_API_KEY="$FLATKEY_API_KEY"
export OPENAI_BASE_URL="https://router.flatkey.ai/v1"

使用你的框架所期望的变量名。有些库读取 OPENAI_BASE_URL；另一些则要求在创建客户端时使用 base_url 或 baseURL 选项。

步骤 3：发送你的第一请求

先从一个简短、确定性的提示开始。目标是在加入流式传输、工具、结构化输出或回退行为之前，先验证身份验证、连接性、模型访问和响应解析。

选项 A：cURL

将 YOUR_CURRENT_MODEL 替换为当前 Flatkey 目录中可用的模型：

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_CURRENT_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "准确回复：flatkey quickstart connected"
      }
    ],
    "temperature": 0
  }'

选项 B：Python

安装 OpenAI 客户端：

pip install openai

创建 quickstart.py：

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="YOUR_CURRENT_MODEL",
    messages=[
        {
            "role": "user",
            "content": "准确回复：flatkey quickstart connected",
        }
    ],
    temperature=0,
)

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

运行它：

python quickstart.py

选项 C：JavaScript

安装客户端：

npm install openai

创建 quickstart.mjs：

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "YOUR_CURRENT_MODEL",
  messages: [
    {
      role: "user",
      content: "准确回复：flatkey quickstart connected",
    },
  ],
  temperature: 0,
});

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

运行它：

node quickstart.mjs

步骤 4：读取响应

对于标准的 chat-completions 请求，先关注四个字段：

字段	它告诉你什么	首次调用检查
`id`	响应标识符	临时保存以便排查问题
`model`	与响应相关联的模型	确认它与你打算测试的路由一致
`choices[0].message.content`	助手输出	确认你的应用能够提取文本
`usage`	随调用返回的 token 计量	记录它用于成本和回归检查

一个简化的响应如下：

{
  "id": "chatcmpl-example",
  "model": "YOUR_CURRENT_MODEL",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "flatkey quickstart connected"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17
  }
}

确切的标识符和 token 数量会有所不同。你的首次调用成功条件并不是字节级匹配；它应当是一个有效的 HTTP 响应、一个可解析的 assistant 消息，以及你的应用程序可以记录的用量信息。

步骤 5：调用后检查用量

不要只停留在 200 OK。一个有用的快速入门还应证明，请求对将要运行集成的人可见。

控制台参考

在请求之后打开 Console → Usage & Logs。

查找新的调用，并确认你的账户可见的详细信息，例如：

请求时间。
模型或路由。
状态。
Token 用量。
成本或余额影响。
请求失败时的错误详情。

如果应用程序收到了响应，但缺少预期的日志条目，首先检查你查看的是不是与请求使用的同一账户、工作区和 API key。还要在重试前记录响应 ID 和请求时间；这两个细节会让排障容易得多。

在从烟雾测试过渡到持续工作负载之前，请查看当前的 Flatkey 价格页面。对比你预计要使用的模型、请求量、token 组合和回退行为——不仅仅是一次成功调用的成本。

步骤 6：添加安全的回退序列

在第一个模型可用之后，再进行回退路由。否则，备用路由可能会掩盖真正的问题：无效的密钥、错误的基础 URL、不可用的模型、格式错误的请求或账户限制。

从一组针对同一任务、已测试过的简短有序模型列表开始：

import os
from openai import OpenAI

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

models = [
    "PRIMARY_CURRENT_MODEL",
    "FALLBACK_CURRENT_MODEL",
]

last_error = None

for model in models:
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[
                {
                    "role": "user",
                    "content": "Return JSON with one key named status and value ok",
                }
            ],
            temperature=0,
        )
        print(model, response.choices[0].message.content)
        break
    except Exception as error:
        last_error = error
        print(f"Route failed: {model}")
else:
    raise RuntimeError("All approved model routes failed") from last_error

这个示例故意保持很小。在生产环境中使用之前，添加：

一份范围较窄的可重试错误列表。
每次尝试的超时和整个请求的截止时间。
针对暂时性故障的退避重试。
包含所尝试模型和响应 ID 的结构化日志。
针对 JSON、工具调用或其他所需 schema 的输出校验。
成本上限，避免回退静默选择不合适的路由。

不要对多个模型的身份验证错误进行重试。不要在请求未修复之前重试格式错误的请求。不要因为每个模型都接受 chat-completions 载荷，就把它们都视为可互换。

一个实用的回退策略

可将以下决策表作为起点：

故障	重试同一模型？	尝试已批准的回退？	操作
网络超时	一次，在截止时间内	是	保留原始请求 ID，并记录两次尝试
速率限制	退避后	是	遵循重试建议并限制总延迟
临时服务器错误	一次	是	在已批准的路由列表用尽后停止
无效的 API 密钥	否	否	轮换或更正凭证
未知/不可用的模型	否	是	刷新模型选择；不要对同一个名称循环重试
无效的请求 schema	否	否	修复并验证载荷
输出未通过验证	可能	是	仅当工作流定义了验证规则时才重试