Flatkey API 身份验证：密钥、请求头与错误

Flatkey 使用在 Authorization 请求头中以 Bearer Token 传递的 API 密钥验证每个 API 请求。你可以在 Flatkey 控制台中创建和管理密钥，无需 OAuth 流程或会话管理。

创建 API 密钥

打开 API 密钥页面

点击创建 API 密钥

为密钥设置一个便于识别的名称，例如 production-app、staging 或 personal-testing。名称仅供你自己识别。

立即复制密钥

完整密钥只会在创建时显示一次。请立即复制并保存到安全位置，例如密码管理器、密钥管理服务或环境变量。如果丢失，只能重新创建。

切勿将 API 密钥提交到源代码仓库，也不要把它放在浏览器端代码中。请使用环境变量，或 AWS Secrets Manager、HashiCorp Vault、Doppler 等密钥管理服务。

使用 API 密钥

在每个请求的 Authorization 请求头中传递密钥：

Authorization: Bearer YOUR_FLATKEY_API_KEY

使用 OpenAI SDK

OpenAI Python 和 Node.js SDK 可通过 api_key / apiKey 构造参数接收密钥：

import os
from openai import OpenAI

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

import OpenAI from "openai";

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

使用 Anthropic SDK

使用 Anthropic Python SDK 时，将 base_url 设置为 https://router.flatkey.ai/v1，并通过 auth_token 构造参数传入 Flatkey 密钥：

import os
import anthropic

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

import Anthropic from "@anthropic-ai/sdk";

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

使用 curl

curl https://router.flatkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

身份验证错误

HTTP 状态码	错误代码	原因	处理方法
`401`	`invalid_api_key`	密钥缺失、格式错误或已撤销	确认密钥存在且复制正确
`401`	`insufficient_balance`	余额为 $0.00	在控制台中充值余额
`403`	`model_not_allowed`	密钥无权访问请求的模型	检查密钥的模型访问设置

管理密钥

多个密钥：可以按需创建任意数量的密钥，例如每个环境（dev、staging、prod）一个，或每位团队成员一个。
撤销密钥：在 API 密钥 页面点击对应密钥旁的删除图标，撤销会立即生效。
密钥不会自动过期：请按照安全最佳实践定期轮换密钥。

每个部署环境使用一个独立 API 密钥。即使某个密钥泄露，也可以只撤销该密钥，不影响其他环境。

设置环境变量

推荐通过环境变量传递密钥：

export FLATKEY_API_KEY="sk-fk-..."

也可以放在 .env 文件中（请确保 .env 已加入 .gitignore）：

.env

FLATKEY_API_KEY=sk-fk-...

​创建 API 密钥

​使用 API 密钥

​使用 OpenAI SDK

​使用 Anthropic SDK

​使用 curl

​身份验证错误

​管理密钥

​设置环境变量

创建 API 密钥

使用 API 密钥

使用 OpenAI SDK

使用 Anthropic SDK

使用 curl

身份验证错误

管理密钥

设置环境变量