云器科技-文档

一、API Key 是什么

API Key 是业务系统调用 AI Gateway 时使用的访问凭证。

可以把它理解为一把“业务调用钥匙”：

API Key 决定请求是否有权限进入平台；
API Key 绑定一个服务档位；
API Key 的用量可以单独统计；
API Key 可以被启用或停用；
不同业务可以使用不同 API Key。

API Key：谁可以调用服务档位：以什么服务方式调用模型：调用什么 AI 能力折扣：该客户在该模型上的实际价格规则

二、为什么建议按业务创建 API Key

不建议所有业务共用一个 API Key。

建议按照产品、项目或环境分别创建，例如：

业务	API Key 名称	建议档位
数据分析产品	`data-analytics-agent` data-analytics-agent	高质量型
工程开发产品	`engineering-agent` engineering-agent	高质量型
命令行工具	`cz-cli` cz-cli	高质量型
数据函数	`lakehouse-ai-function` lakehouse-ai-function	高质量型
临时测试	`model-test` model-test	经济型或标准型

独立创建可以带来以下好处：

用量统计更清晰；
费用归属更清楚；
故障排查更容易；
停用某个业务时不会影响其他业务；
后续可以为不同业务选择不同服务档位。

三、创建 API Key

进入 API Key 管理，点击“新建”。

1. 填写名称

名称建议包含业务或项目名称，不建议只填写无意义的编号。

推荐命名方式：

业务名称-环境-档位

例如：

```
engineering-agent-prod-高质量型
```
engineering-agent-prod-高质量型
；
```
data-analysis-test-标准型
```
data-analysis-test-标准型
；
```
model-test-经济型
```
model-test-经济型
。

2. 选择服务档位

创建 API Key 时需要选择服务档位：

经济型；
标准型；
高质量型。

一个 API Key 对应一个服务档位。

创建 API Key 时选择服务档位即可。不同模型的具体折扣和价格请在模型广场中查看。

服务档位的选择入口不受折扣配置限制，但实际可调用范围受当前档位折扣约束：账号已有任意生效折扣时，该 API Key 只能调用在当前档位配置了生效折扣的模型。

配图 1：新建 API Key 页面

3. 设置调用限制

如需限制 Token 或金额，可根据业务规模设置。

建议：

测试 Key 设置较小的额度；
正式业务 Key 根据预计用量设置；
对自动化产品设置合理的月度或周期限制；
定期通过用量统计检查限额是否合理。

4. 保存 API Key

保存后，请妥善保管完整 API Key。

不要将 API Key：

提交到公开代码仓库；
写入前端页面；
直接发送到不受控的群聊；
与无关人员共享。

四、一个业务使用多个档位时怎么配置

如果一个客户同时使用多个服务档位，应创建多个 API Key。

例如：

API Key A：工程测试-经济型 API Key B：工程日常-标准型 API Key C：工程生产-高质量型

正式生产产品建议直接使用高质量型 API Key，不要依赖运行时切换档位。

五、编辑 API Key

可以编辑：

API Key 名称；
Token 限制；
金额限制；
限制周期；
其他可配置的业务属性。

服务档位属于 API Key 的核心属性。需要更换服务档位时，建议创建新的 API Key，并在业务系统中完成替换。

六、启用和停用 API Key

API Key 可以被启用或停用。

启用

启用后，使用该 Key 的请求可以继续调用符合条件的模型。

停用

停用后，使用该 Key 的请求将无法正常调用。

适合停用的场景：

项目已经结束；
Key 疑似泄露；
临时冻结某个业务；
更换为新的档位或业务 Key；
测试 Key 不再使用。

建议优先停用不再使用的 Key，而不是长期保留大量无效凭证。

配图 2：API Key 列表页面

七、模型详情页如何使用已有 API Key

在模型详情页复制调用示例时，可以选择已经创建的 API Key。

使用路径如下：

API Key 管理 ↓ 创建并保存 API Key ↓ 模型广场 ↓ 打开模型详情 ↓ 复制 cURL 或 Python 示例 ↓ 选择已有 API Key

选择后，示例会自动填入对应凭证，用户可以直接用于测试。

配图 3：模型详情页选择 API Key

八、API Key 与价格的关系

API Key 绑定服务档位，具体模型价格在模型广场中查看。

如果账号没有任何生效的专属折扣：

所有模型都可以使用；
模型广场显示统一刊例价；
页面标记为“全价”；
不展示不存在的折后价。

如果账号已经配置过任意模型折扣：

模型在当前 API Key 档位有折扣时，按该档位折后价使用；
模型在当前 API Key 档位没有折扣时，标记为“不可用”，不能调用；
其他档位已经配置的折扣不能复用到当前档位。

如果账号没有任何生效的专属折扣，默认使用高质量型，并按照刊例价计费。

九、API Key 与路由行为

API Key 选择服务档位后，系统按照该档位对应的模型和服务规则处理请求。

系统不会因为当前档位不可用而自动跨到其他档位。

例如：

标准型 API Key ↓ 标准型当前没有可用服务 ↓ 不自动切换到经济型或高质量型 ↓ 请求失败

如果业务对稳定性要求更高，应为业务创建高质量型 API Key。

十、安全建议

按环境区分

建议区分测试、预发布和生产环境：

```
project-test-经济型
```
project-test-经济型
；
```
project-staging-标准型
```
project-staging-标准型
；
```
project-prod-高质量型
```
project-prod-高质量型
。

按产品区分

不同产品尽量不要共用同一把 Key。

出现疑似泄露时立即停用

先停用原 Key，再创建新 Key，最后完成业务系统替换。

定期查看用量

如果某个 Key 的请求量突然增加，应及时确认是否存在误用、泄露或业务异常。