签发 API 密钥并设置限流

完成后,用户可以在脚本中用带 scope 的密钥调用 AI 和上传接口,你可以控制每个密钥的调用频率。

API 密钥让用户无需浏览器会话即可调用部分 /api/* 接口。任何已登录用户都可以为自己的账号创建密钥,限流由运营人员设置。密钥不需要服务商,也不需要环境变量。

准备工作

  • 一个用于创建密钥的已登录用户账号。
  • 查看限流需要 config.read,修改需要 config.write,查看所有用户的密钥需要 api_keys.read。内置的 Platform Operator 角色可以查看,Settings Manager 角色提供 config.write。
  • 调用 AI 时需要一个已设置路由的场景,见 设置场景路由和定价。

创建密钥

打开表单

登录后在应用侧边栏打开 API Keys(/app/api-keys),点击 创建 API Key。

填写字段

字段填写内容
Key 名称便于日后辨认的名称,至少两个字符。
环境Production、Staging 或 Development。只是标签,不影响密钥的权限。
速率限制 (req/sec)没有 API 规则的接口上每个窗口允许的请求数,默认 100。
过期日期可选。到该日期(UTC)起密钥失效。
允许的 Origins/IPs可选,每行一个。见下方警告。
Scopes运行 AI 任务、查询 AI 任务状态、上传文件。默认勾选前两项。

复制密钥

点击 创建 key,然后点击 复制 保存 Secret key。它只显示这一次,之后无法找回,丢失了只能重新创建。

创建后不能修改 Scopes。

允许来源会拦截服务端之间的调用

填写 允许的 Origins/IPs 后,只有请求的 Origin 头与某一行完全一致(包括协议和端口)才会被接受。不会按 IP 匹配。没有 Origin 头的请求(例如 curl 或服务端代码)会被拒绝。服务端之间调用的密钥请留空。

用密钥调用接口

通过 Authorization: Bearer <key> 或 x-api-key: <key> 发送密钥。

curl -X POST "https://your-domain.example/api/$SCENE/generate" \
  -H "Authorization: Bearer $KERNLIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise this changelog"}'

curl "https://your-domain.example/api/status?taskId='taskId'" \
  -H "x-api-key: $KERNLIFT_API_KEY"

$SCENE 是 场景路由 中的场景编码。第一个请求需要 运行 AI 任务,第二个需要 查询 AI 任务状态,POST /api/assets/upload 需要 上传文件。调用以密钥所有者的身份执行,消耗的是所有者的积分。GET /api/openapi.json 提供这些接口的 OpenAPI 3.1 文档。

为所有密钥设置限流

打开限流配置

在后台进入 平台 → 限流配置(/admin/rate-limits)。

选择后端

限流后端:内存 在每个服务进程内单独计数。多个实例同时提供 API 时选择 Redis,并填写 Redis URL(例如 redis://default:password@host:6379)。Redis 连不上时,该请求改用内存计数。切回 内存 会清空已保存的 URL。

设置默认值

默认次数 (req/sec) 和 默认窗口 (秒) 作用于没有单独规则的接口。次数范围 1–10,000,窗口范围 1–3,600 秒。

设置 API 规则

API 规则 中 AI generate(/api/{scene}/generate)、AI status(/api/status)和 Asset upload(/api/assets/upload)各占一行,分别设置 次数 (req) 和 窗口 (秒),然后点击 保存配置。

这三个接口上的 API 规则对所有密钥生效,并且优先于用户创建密钥时填写的速率限制。用户填写的限制只作用于其他支持密钥认证的接口。

为单个密钥设置不同的限流

找到密钥

进入 平台 → API Keys(/admin/api-keys)。Key 库存 列出所有用户的密钥(已脱敏),以及所属用户、状态、过期时间、最后使用 和使用事件数。用 搜索 和 状态 筛选后点击 应用。

编辑规则

点击该行的 API 规则。API key 默认规则 设置这个密钥自己的次数和窗口。每个接口行会显示当前继承的值,可以为这个密钥单独填写 限流 和 窗口。

保存

点击 保存。对话框里每一行都会存为该密钥的设置,之后在 限流配置 页的修改不再影响这个密钥。

撤销密钥

在 /app/api-keys 该密钥所在行点击 撤销,输入 key 名称后点击 确认撤销。使用该密钥的请求会立即失败。运营人员不能创建或撤销用户的密钥,但用户被封禁期间,其所有密钥都无法使用。

验证

不带 taskId 调用状态接口:

curl -i "https://your-domain.example/api/status" \
  -H "Authorization: Bearer $KERNLIFT_API_KEY"
  • 400 且返回 taskId is required.:密钥可用。
  • 401 invalid_api_key:密钥错误、已撤销或已过期,或被允许来源拒绝。
  • 403 insufficient_scope:密钥没有 查询 AI 任务状态。
  • 429 rate_limited:触发了限流,等当前窗口过去再试。

每次调用都会以通过或拒绝的形式出现在 使用统计(/app/api-keys/usage)中。pnpm validate:api-keys 会检查密钥库存、scope 和校验限流。

常见问题

请求返回 insufficient_scope

密钥缺少该接口要求的 scope。例如只有默认 scope 的密钥无法调用 POST /api/assets/upload。密钥创建后不能修改,请用所需的 scope 新建一个。

限额被重置或不同服务器表现不一致

内存 后端在每个服务进程内单独计数。在 限流配置 页把 限流后端 设为 Redis 并填写 Redis URL,让所有实例共享计数。

接口忽略密钥、要求会话

部分接口只接受会话:/api/chat、/api/chat/conversations 和 /api/billing/checkout。

同一 IP 频繁收到 rate_limited

除上面的限流外,每个密钥前缀加客户端 IP 在 60 秒内最多校验 120 次,用来拖慢猜测密钥的尝试。请分散调用,或停止发送无效密钥。

参考

下一步