# 密钥管理

https://omnimodel.me/docs/api-keys?lang=zh

API 密钥决定谁可以调用、能调用哪些模型、最多花多少钱。每个账号可以创建多把密钥，建议按应用或环境分开使用，出问题时只停用其中一把。

## 查看完整密钥

- 完整密钥以 `key_` 开头，创建或重置后立即显示。
- 之后在密钥页点「查看」，输入登录密码即可再次查看，每次查看都要重新输入。5 分钟内输错 5 次会锁定 15 分钟。
- 已撤销的密钥不能查看。管理员也看不到你的完整密钥。

## 暂停、重置与撤销

| 操作 | 效果 |
| --- | --- |
| 暂停 / 恢复 | 暂停后该密钥的新请求全部被拒绝，恢复后立即可用 |
| 重置 | 生成新的完整密钥，前缀不变，旧密钥立即失效；需要输入登录密码 |
| 撤销 | 永久停用，不能恢复 |

暂停、过期、撤销和写错的密钥都返回同一个错误 `auth.invalid_key`（HTTP 401）。密钥只在请求开始时校验，已经在进行中的调用会正常完成并计费。

## 给密钥加限制

创建或编辑密钥时，可以为每把密钥单独设置：

- **可用模型**：只允许调用列出的模型，留空表示全部模型。调用列表外的模型返回 `auth.forbidden`（HTTP 403）。
- **每日 / 每月消费上限**：按实例币种设置。平台在调用前按预估费用判断，单次调用可能让实际花费略超上限，之后的调用会被拒绝，返回 `key.spend_limit`（OpenAI 格式里显示为 `billing.key_limit_exceeded`）。日与月按实例时区切换。
- **IP 白名单**：填写单个 IP 或 CIDR 网段，名单外的来源返回 `key.ip_denied`（HTTP 403）。
- **过期时间**：到期后自动失效。

## 安全建议

- 密钥只放在服务端环境变量或密钥管理系统里，不要写进前端代码、移动端安装包或公开仓库。
- 请求时只放在请求头（`Authorization: Bearer` 或 Anthropic 的 `x-api-key`），URL 参数里的密钥一律拒绝。
- 怀疑泄露时先重置或撤销，再检查[用量](/docs/usage)里对应密钥的调用记录。

## 常见问题

### 密钥忘记保存了怎么办？

在密钥页点「查看」，输入登录密码即可再次查看完整密钥。已撤销的密钥无法查看。

### 重置和撤销有什么区别？

重置会生成新的密钥，旧密钥立即失效，但密钥本身和它的限制设置保留；撤销是永久停用，不能恢复。

### 暂停密钥会中断正在进行的请求吗？

不会。密钥只在请求开始时校验，进行中的请求会正常完成并计费，暂停后新的请求才会被拒绝。

### 消费上限为什么被略微超出？

上限按调用前的预估费用判断，单次调用的实际费用可能让总额略超上限，之后的调用会被拒绝。