API KEY 管理

API KEY 管理

API KEY 管理

用于创建、维护和控制 AI Gateway 的调用凭证。业务系统调用 AI Gateway 时，需要使用这里生成的 API Key 作为鉴权凭证。通过 API Key 可以按业务、环境、团队或应用拆分调用入口，并分别配置

Token 限额

Token 限额

、

金额限额

金额限额

和

路由策略

路由策略

。

该页面适合用于以下场景：

为不同业务系统创建独立调用凭证。
为生产、测试、开发环境设置不同限额。
控制单个 API Key 的 Token 或金额消耗上限。
配置某个 API Key 的供应商路由方式。
快速查看、复制、禁用、删除或下钻分析 API Key 用量。

页面入口

进入 AI Gateway 控制台后，点击左侧导航栏的 API KEY 管理，或直接访问：

<https://aitoken.clickzetta.com/apikey>

页面结构

页面主要由

顶部操作区

顶部操作区

、

筛选区

筛选区

和

API Key 列表

API Key 列表

组成。

区域	说明
`标题区` 标题区	展示当前页面名称和能力说明，例如支持 Token 限额、金额限额和 API Key 粒度路由策略。
`新建` 新建	创建新的 API Key，并设置名称、限额周期、Token 限额和金额限额。
`搜索` 搜索	按 API Key 名称或脱敏后的 API Key 关键字搜索。
`状态筛选` 状态筛选	按启用、禁用等状态过滤 API Key。
`刷新` 刷新	重新加载当前列表数据。
`列表` 列表	展示 API Key 的名称、密钥、状态、限额、路由策略和行内操作。

列表字段说明

API Key 列表用于集中查看每个调用凭证的当前状态和控制策略。

字段	说明
`名称` 名称	API Key 的业务名称，建议包含业务、环境或团队标识，例如 `prod-payment` prod-payment 、 `dev-agent` dev-agent 。
`API KEY` API KEY	API Key 的脱敏展示，用于识别凭证。页面中通常只展示部分字符，不建议在截图或文档中暴露完整 Key。
`状态` 状态	API Key 当前是否可用。启用状态下可正常调用；禁用后调用会失败。
`Token 限额` Token 限额	展示当前已使用 Token 和 Token 上限，可通过进度条快速判断是否接近上限。
`金额限额` 金额限额	展示当前 API Key 的金额上限。为空或显示不限额时，表示不按金额限制。
`路由策略` 路由策略	展示当前 API Key 的模型供应商路由方式，例如默认、指定策略、仅 BYOK。
`操作` 操作	支持路由策略、编辑、复制、禁用、删除、查看用量等操作。

Token 限额

Token 限额

Token 限额

用于控制该 API Key 在指定周期内可消耗的 Token 数量。

常见展示方式：

示例	说明
`0 / 10,000 Tokens` 0 / 10,000 Tokens	当前已消耗 0 Token，上限为 10,000 Token。
`675,857 / 1,000,000 Tokens` 675,857 / 1,000,000 Tokens	当前已使用约 67.6%，应关注是否即将触达上限。
`0 / - Tokens` 0 / - Tokens	未设置 Token 上限。

当 API Key 达到 Token 限额后，后续调用可能会被限制或失败。建议为生产业务设置合理上限，并结合用量统计定期评估。

金额限额

金额限额

金额限额

用于控制该 API Key 在指定周期内可消耗的金额上限。

展示	说明
`¥500` ¥500	该 API Key 的金额上限为 500 元。
`¥3,000` ¥3,000	该 API Key 的金额上限为 3,000 元。
`不限额` 不限额	未设置金额上限，不按金额进行限制。

金额限额适合用于控制异常调用造成的成本风险。例如，测试环境、外部演示环境或临时项目可以设置较小金额上限；生产环境可根据业务峰值设置更高上限。

注意：页面金额用于产品侧用量观察和限额控制。实际账单、折扣、BYOK 云厂商费用等可能受计费周期和供应商结算影响，最终以出账结果为准。

新建 API Key

点击页面右上角

新建

新建

，可以创建新的 API Key。

创建时需要填写以下字段：

字段	是否必填	说明
`名称` 名称	是	API Key 的显示名称，用于区分业务、环境或团队。
`限额周期` 限额周期	是	限额生效周期，可按产品页面提供的周期选择，例如天、月或其他周期。
`Token 限额` Token 限额	否	当前周期内可消耗的 Token 上限。不填表示不限制 Token。
`金额限额（元）` 金额限额（元）	否	当前周期内可消耗的金额上限。不填表示不限制金额。

操作步骤：

进入 API KEY 管理。
点击右上角
```
新建
```
新建
。
输入 API Key 名称。
选择限额周期。
按需填写 Token 限额。
按需填写金额限额。
点击
```
确定
```
确定
创建。

命名建议：

生产环境：
```
prod-业务名
```
prod-业务名
，例如
```
prod-agent-service
```
prod-agent-service
。
测试环境：
```
test-业务名
```
test-业务名
，例如
```
test-chatbot
```
test-chatbot
。
个人或临时调试：
```
dev-姓名或项目名
```
dev-姓名或项目名
。
对外演示：
```
demo-客户或场景名
```
demo-客户或场景名
，并设置较小限额。

限额建议：

场景	建议
生产业务	根据历史峰值设置 Token 和金额限额，并预留合理缓冲。
测试环境	设置较小 Token 限额和金额限额，避免压测或循环调用导致费用异常。
临时验证	设置短周期、低额度，用完后及时禁用或删除。
多团队共用	不建议共用同一个 Key，应拆分为多个 Key 便于成本归因。

编辑 API Key

在列表中点击

编辑

编辑

，可修改 API Key 的基础配置，例如：

名称。
限额周期。
Token 限额。
金额限额。

编辑不会改变 API Key 的身份本身，但会影响后续调用的限额控制。调整生产环境 API Key 前，建议先进入

查看用量

查看用量

，确认该 Key 最近的峰值、日均消耗和业务归属。

复制 API Key

点击

复制

复制

可以复制当前 API Key。复制适合用于快速创建配置相似的新 Key，例如：

为相同业务创建测试环境 Key。
为新团队创建同样路由策略的 Key。
为临时活动复制一份限额更小的 Key。

复制后建议立即检查：

名称是否已改为新业务用途。
Token 限额和金额限额是否符合新场景。
路由策略是否仍然适用。
是否需要在业务系统中替换为新 Key。

禁用与删除

操作	说明	建议
`禁用` 禁用	停用当前 API Key。禁用后，使用该 Key 的调用会失败。	适合密钥疑似泄露、业务暂停、临时阻断异常调用。
`删除` 删除	删除当前 API Key。删除后通常无法继续使用。	删除前应确认没有生产业务依赖该 Key。

禁用或删除前，建议先点击

查看用量

查看用量

，确认该 Key 最近是否仍有调用。如果最近仍有请求，应先通知业务方完成替换。

查看用量

点击列表行内的

查看用量

查看用量

，可以跳转到 用量统计 / 模型用量 页面，并按当前 API Key 查看对应消耗。

常见用途：

查看某个 API Key 的 Token 消耗趋势。
排查某个业务的请求量突增。
核对某个 Key 对应的系统成本或 BYOK 成本。
在禁用、删除前确认是否仍有调用。
定位金额限额触发前后的调用来源。

路由策略

点击 API Key 行内的

路由策略

路由策略

，可以配置该 API Key 调用模型时的供应商路由方式。

当前支持三种策略模式：

策略模式	说明	推荐场景
`默认` 默认	系统在平台内置供应商和用户 BYOK 中按所选策略自动排序。	大多数业务，既希望自动择优，又不想手动维护供应商顺序。
`指定策略` 指定策略	手动选择平台内置端点或 BYOK，并通过拖拽决定调用优先级。	对供应商、区域、稳定性、合规或成本有明确要求的业务。
`仅 BYOK` 仅 BYOK	只调用用户已配置的 BYOK，并按拖拽顺序故障转移。	必须使用企业自有云厂商账号或必须自行承担供应商账单的业务。

默认模式

默认

默认

模式由系统自动选择可用端点。该模式下可以选择端点排序策略：

排序策略	说明
`价格优先` 价格优先	优先调用成本更低的端点。适合对成本敏感的业务。
`吞吐优先` 吞吐优先	优先调用吞吐能力更高的端点。适合高并发或批量任务。
`延迟优先` 延迟优先	优先调用响应延迟更低的端点。适合交互式应用、实时问答等场景。

默认模式的路由逻辑可以理解为：

系统先汇总该模型可用的候选端点，包括平台内置端点和用户已配置的 BYOK。
如果用户配置了与目标模型匹配的 BYOK，系统会优先尝试用户 BYOK。
如果 BYOK 不可用，再回退到平台内置供应商。
在多个平台内置供应商都可用时，系统按所选策略排序。
以
```
价格优先
```
价格优先
为例，系统会从价格最低的内置供应商开始尝试；如果最低价供应商不可用，再回退到价格更高的供应商。
如果同一价格下有多个内置供应商，系统可能随机选择其中一个进行路由。

适用建议：

不确定如何配置时，优先使用默认模式。
成本敏感场景选择
```
价格优先
```
价格优先
。
高并发任务选择
```
吞吐优先
```
吞吐优先
。
对首字响应或总耗时敏感的场景选择
```
延迟优先
```
延迟优先
。

指定策略

指定策略

指定策略

用于手动控制路由对象和优先级。可混合选择平台内置端点和已配置的 BYOK。

配置方式：

在策略模式中选择
```
指定策略
```
指定策略
。
搜索并选择平台端点或 BYOK 名称。
在优先级区域中拖拽排序。
序号越小，优先级越高。
点击
```
保存
```
保存
生效。

指定策略的路由逻辑：

只在用户选择的路由对象范围内调用。
列表顺序就是调用优先级。
高优先级对象不可用时，按顺序故障转移到下一个对象。
指定策略不再叠加
```
价格优先
```
价格优先
、
```
吞吐优先
```
吞吐优先
或
```
延迟优先
```
延迟优先
的自动排序。

适合场景：

某业务必须优先使用指定区域或指定供应商。
希望先走企业自有 BYOK，再使用平台兜底。
希望为关键业务配置明确的故障转移顺序。
某些模型供应商在业务侧已有合规或合同要求。

仅 BYOK

仅 BYOK

仅 BYOK

模式只使用用户已配置的 BYOK，不会回退到平台内置供应商。

配置方式：

在策略模式中选择
```
仅 BYOK
```
仅 BYOK
。
从已配置的 BYOK 名称中选择一个或多个 Key。
通过拖拽调整优先级。
点击
```
保存
```
保存
生效。

仅 BYOK 的路由逻辑：

只调用选中的 BYOK。
按拖拽顺序依次尝试。
高优先级 BYOK 不可用时，故障转移到下一个 BYOK。
不会回退到平台内置供应商。

适合场景：

企业要求所有调用必须走自有云厂商账号。
费用必须由企业在云厂商侧自行结算。
对数据边界、供应商合规或内部审计有明确要求。
不希望平台内置供应商参与兜底。

使用前请确认：

BYOK 已在 BYOK 页面配置完成。
云厂商侧 API Key 有效且额度充足。
云厂商侧已开通目标模型。
目标模型、区域和接口类型与当前调用匹配。

路由策略配置建议

业务目标	推荐配置
快速接入，尽量少维护	使用 `默认` 默认 + `价格优先` 价格优先。
控制调用成本	使用 `默认` 默认 + `价格优先` 价格优先，并设置金额限额。
提升高峰期稳定性	使用 `默认` 默认 + `吞吐优先` 吞吐优先，或配置 `指定策略` 指定策略多端点故障转移。
降低交互延迟	使用 `默认` 默认 + `延迟优先` 延迟优先。
优先使用企业自有 Key	使用 `指定策略` 指定策略，将 BYOK 放在优先级前面。
禁止平台内置兜底	使用 `仅 BYOK` 仅 BYOK 。

常见排查场景

调用提示 API Key 不可用

可以按以下顺序检查：

API Key 是否已被禁用或删除。
业务系统中配置的 Key 是否为最新 Key。
Token 限额是否已达到上限。
金额限额是否已达到上限。
路由策略是否选择了不可用的供应商或 BYOK。

调用突然失败

重点检查：

是否刚刚修改过路由策略。
是否切换到了
```
仅 BYOK
```
仅 BYOK
，但 BYOK 不可用。
是否设置了过低的 Token 或金额限额。
是否禁用了业务仍在使用的 Key。

成本或用量异常

建议操作：

点击该 API Key 的
```
查看用量
```
查看用量
。
在用量统计中查看该 Key 的 Token、请求数和成本趋势。
对比是否存在突增时间段。
检查业务侧是否有循环调用、批量任务或压测。
必要时先降低限额或禁用 Key，再排查业务代码。

安全建议

不要在代码仓库、日志、截图、工单或公开文档中暴露完整 API Key。
生产、测试、开发环境分别使用不同 API Key。
不同业务系统分别创建 API Key，避免共用导致成本无法归因。
对外部系统、临时测试和演示环境设置较小 Token 限额和金额限额。
定期检查长期未使用的 API Key，并及时禁用或删除。
发生泄露风险时，应立即禁用旧 Key，创建新 Key 并更新业务系统配置。

联系我们