签发 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.:密钥可用。401invalid_api_key:密钥错误、已撤销或已过期,或被允许来源拒绝。403insufficient_scope:密钥没有 查询 AI 任务状态。429rate_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 次,用来拖慢猜测密钥的尝试。请分散调用,或停止发送无效密钥。