主题
API Key 管理与安全
API Key 是调用 Zivv API 的凭证。合理拆分和限制 Key，可以降低泄露、误扣费和排障困难的风险。
创建 API Key
- 登录 令牌管理
- 点击 添加令牌
- 填写名称，选择模型分组
- 按需设置模型白名单、额度、RPM / RPH 和过期时间
- 创建后立即复制并保存在密码管理器或密钥管理服务中
不要把 Key 放进仓库
不要把 sk-... 写进源码、提交到 Git、截图发群或放在公开文档中。前端网页也不应直接持有长期有效的服务端 Key。
推荐的 Key 拆分方式
| 使用场景 | 推荐命名 | 推荐限制 |
|---|---|---|
| 个人电脑上的 Codex | codex-desktop-main | 仅开放常用编程模型，设置月度额度 |
| 本地第三方客户端 | client-laptop | 先确认支持自定义 Base URL，再限定模型并设置 RPM / RPH |
| 后端服务 | api-production | 最小模型白名单，单独额度和告警 |
| 测试环境 | api-staging | 较低额度，设置过期时间 |
| 临时脚本 | script-2026-07 | 较低额度，任务结束后删除 |
建议遵循：
- 一个应用、一个环境、一个 Key
- 生产与测试环境分开
- 团队成员不要共享个人 Key
- 对不需要的模型使用白名单收紧权限
限制项说明
模型分组
分组决定可用渠道、价格倍率和可能的客户端限制。创建 Key 前先确认目标客户端适合哪个分组。
模型白名单
只允许 Key 调用选中的模型。请求其他模型时会返回 model is not allowed for this API key。
额度限制
额度是这个 Key 可累计消费的上限。达到上限后会返回 key quota limit exceeded。额度限制不会替代账户余额检查。
RPM / RPH
- RPM：每分钟请求数
- RPH：每小时请求数
触发限制后通常返回 429 rate limit exceeded。并发程序应读取 Retry-After 并使用指数退避重试。
过期时间
临时项目、演示或外部协作应设置过期时间。过期 Key 无需人工回收，也不能继续调用。
Key 轮换
当 Key 可能泄露、成员离开或应用迁移时：
- 创建新 Key，并复制到安全位置
- 更新应用环境变量或密钥管理服务
- 发起一次最小请求验证新 Key
- 停用或删除旧 Key
- 在 用量日志 检查是否仍有旧 Key 请求
不要先删除旧 Key 再改应用，否则会造成不必要的服务中断。
环境变量示例
bash
export ZIVV_API_KEY="sk-你的Key"powershell
$env:ZIVV_API_KEY = "sk-你的Key"bash
ZIVV_API_KEY=sk-你的Key