> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 管理 API 密钥
## API 密钥概述
在调用PPIO 派欧云平台的 API 产品时，通过使用请求头中的**Bearer 认证方式**进行 API 访问认证，例如，"Authorization: Bearer \{API 密钥}"。
每个 API 密钥都以 `sk_` 开头，是一串随机字符串。密钥创建后长期有效，除非您在控制台手动删除它。
您可以前往API 密钥管理页面查看和管理您的 API 密钥。每个账户最多可以生成**10**个密钥。
密钥的创建与删除仅在控制台提供，OpenAPI 不包含创建或删除密钥的接口。OpenAPI 仅提供密钥列表查询，以及单个密钥模型访问策略的读写，详见查询 API Key 列表。
## 创建 API 密钥
1. 进入API 密钥管理页面，单击「+创建」。
2. 输入密钥名称，单击「确认」。
3. 保存密钥。
API 密钥创建后无法再次查看，请妥善保存您的密钥。如果遗失，您需要生成新的密钥。
## 管理 API 密钥
对于已有的 API 密钥，支持以下操作：
* 修改：单击对应的
，输入新的密钥名称，单击「确认」即可完成修改。
* 删除：单击对应的
，确认后即可删除。
密钥一经删除即刻失效且不可恢复，使用该密钥的所有调用都会返回鉴权失败（HTTP 401）。删除前请确认没有线上业务仍在使用它。
## 密钥有效期
当前，API 密钥创建后长期有效，不会自动过期，除非您在控制台手动删除它。删除后密钥立即失效。
如需停用某个密钥，请在控制台删除对应密钥；平台不会主动使密钥过期。
## 模型访问
「模型访问」用于控制单个 API 密钥可以调用哪些模型。它不改变团队已开通的模型范围，只在团队已开通范围内进一步收敛某个密钥能访问的模型。未包含在访问范围内的模型，调用时会被直接拒绝。
本能力覆盖大语言模型（LLM）产品线下的模型。图片、视频等独立多模态能力暂不纳入模型访问配置范围。
常见的使用场景：
* **隔离不同用途的密钥**：让生产密钥只访问稳定模型，实验密钥只访问低成本模型。
* **应急收敛风险**：某个密钥出现非预期的高成本模型调用时，先把它限制到几个安全模型。
* **外部合作控制**：临时提供给外包或合作方的密钥，只开放约定的模型。
### 访问模式
每个 API 密钥有一种访问模式，二选一：
| 访问模式 | 含义 |
| :------ | :------------------------------------------------------- |
| 全部已开通模型 | 默认模式。可访问团队当前及未来开通的可用模型，可以再手动排除部分模型。未来新开通的模型会自动可访问，除非被排除。 |
| 仅限指定模型 | 只能访问手动选定的模型。团队后续新开通的模型不会自动加入，需要手动添加。 |
两种模式下，实际可访问的模型都遵循同一条边界：不能超出团队已开通的模型范围，也不包含已下线的模型。
* 全部已开通模型：可访问模型 = 团队已开通模型（含未来新开通模型）− 已排除的模型。
* 仅限指定模型：可访问模型 = 已选定的模型（与团队已开通模型取交集）。
### 配置模型访问
只有团队的管理员可以配置 API 密钥的模型访问。开发者和基础用户可以查看与自己相关密钥的只读摘要，但不能编辑；财务管理员看不到模型访问入口。
前往 API 密钥管理页面，找到要配置的 API 密钥。
在创建或编辑该 API 密钥时，进入「模型访问」区域。
选择「全部已开通模型」或「仅限指定模型」：
* 选择「全部已开通模型」时，可在「已排除的模型」中添加需要禁止访问的模型。
* 选择「仅限指定模型」时，在「可访问的模型」中至少添加一个模型。
保存后，新的模型访问设置可能需要一段时间才会生效。
在创建新密钥或编辑现有密钥时，可以通过「复制配置」「粘贴配置」复用同一 Team 内其他密钥的模型访问设置，粘贴后可直接保存，也可以调整后再保存。
### 模型下线的影响
如果某个模型被平台下线，该模型不再属于可用模型集合：
* 对该模型的所有调用会立即返回「模型不可用」。
* 历史配置中如果仍包含已下线模型，页面会保留展示并置灰提示；保存前必须先移除，否则不允许保存。
### 调用被拒的表现
当 API 密钥调用了不在其访问范围内的模型时，调用会返回 HTTP 403 和错误码 `model_access_denied`，并提示该密钥不能访问此模型。此时请联系团队管理员调整该密钥的模型访问设置。常见错误码的排查参见常见错误码说明。
如果需要通过 API 自动化管理密钥的模型访问，参见 查询 API Key 模型访问策略。
## 用量与预算
您可以为单个 API 密钥单独设置消费上限，用于控制该密钥的模型 API 调用成本。密钥预算与成员预算两层限额同时生效，任一层达到上限都会暂停对应服务。
配置方式、预算类型（无上限 / 固定总预算 / 月度预算）和用尽后的提示，详见团队预算管理。
API Key 预算目前仅限制模型 API 的调用消费，GPU 实例、沙箱等产品的消费不受 Key 预算约束，但仍计入成员预算总额。
## 环境变量配置
建议把 API 密钥配置到环境变量，避免在代码里硬编码密钥，降低泄漏风险。代码从环境变量读取密钥，例如 `os.environ["PPIO_API_KEY"]`。
### 临时变量与永久变量
* **临时变量**：只在当前终端会话生效，关闭终端后失效，适合临时测试。
* **永久变量**：写入 shell 配置文件或系统环境变量，新开的终端和重启后仍然生效，适合长期使用。
下面按操作系统给出设置方法（以变量名 `PPIO_API_KEY` 为例）。
临时变量（仅当前终端会话有效）：
```bash theme={null}
export PPIO_API_KEY="sk_你的密钥"
```
永久变量（写入 `~/.bashrc`，对 bash 生效；zsh 请写入 `~/.zshrc`）：
```bash theme={null}
echo 'export PPIO_API_KEY="sk_你的密钥"' >> ~/.bashrc
source ~/.bashrc
```
验证是否设置成功：
```bash theme={null}
echo $PPIO_API_KEY
```
临时变量（仅当前终端会话有效）：
```bash theme={null}
export PPIO_API_KEY="sk_你的密钥"
```
永久变量（macOS 默认 shell 为 zsh，写入 `~/.zshrc`）：
```bash theme={null}
echo 'export PPIO_API_KEY="sk_你的密钥"' >> ~/.zshrc
source ~/.zshrc
```
验证是否设置成功：
```bash theme={null}
echo $PPIO_API_KEY
```
临时变量（仅当前 PowerShell 会话有效）：
```powershell theme={null}
$env:PPIO_API_KEY = "sk_你的密钥"
```
永久变量（写入用户级环境变量，需新开终端才生效）：
```powershell theme={null}
setx PPIO_API_KEY "sk_你的密钥"
```
验证是否设置成功（新开一个终端后执行）：
```powershell theme={null}
echo $env:PPIO_API_KEY
```
### 设置了变量但代码仍找不到
如果设置后代码依然读取不到密钥，按以下几种情况排查：
* **只设了临时变量**：`export` 或 `$env:` 只对当前终端会话有效，换个终端或重启后就没了。需要长期生效请改用永久变量（`~/.bashrc` / `~/.zshrc` / `setx`）。
* **改了配置但没重新加载**：写入 `~/.bashrc` / `~/.zshrc` 后，需要 `source` 对应文件或重开终端；IDE 内置终端通常要重启 IDE 才会加载新变量。
* **进程管理器不继承用户变量**：用 systemd、supervisor、PM2 等托管服务时，不会自动继承你登录 shell 的环境变量，需要在各自的服务配置里单独声明。
* **sudo 不继承当前环境**：`sudo` 默认使用干净的环境，读不到当前用户的变量。需要传递时使用 `sudo -E`，或在 root 环境下单独配置。
## 安全最佳实践与泄露应急
API 密钥等同于账户凭证，任何持有它的人都能以您的身份调用 API 并产生费用。请遵循以下实践：
* **用环境变量存储**：把密钥放进环境变量或密钥管理服务，不要硬编码进源代码。
* **不要提交到代码仓库**：避免把密钥写进代码、配置文件后提交到 Git；对外分享代码或截图前先移除密钥。
* **不要放进前端**：不要在浏览器端、移动 App 等客户端代码中直接使用密钥，这些环境的密钥可被他人提取。请通过您自己的后端中转调用。
* **一环境一密钥**：为不同环境（生产、测试、CI）和不同用途分配独立密钥，便于按需停用和排查，互不影响。
* **用模型访问和预算收敛权限**：结合[模型访问](#模型访问)限定单个密钥可调用的模型，结合[预算](/docs/support/budgets)限定其消费上限，缩小单个密钥的影响面。
* **定期轮换**：定期更换密钥。轮换时先创建新密钥、切换业务使用新密钥、在生产验证无误后再删除旧密钥，实现零停机切换。
### 密钥泄露后的处理
如果怀疑某个密钥已泄露（例如误提交到公开仓库、出现在日志或截图中）：
1. 立即进入 API 密钥管理页面删除该密钥，使其失效。
2. 创建一个新密钥，更新到所有使用该密钥的业务中。
3. 通过操作审计检查是否存在异常操作，通过预算管理确认消费是否异常。
4. 如需收紧团队成员对密钥的管理权限，参见团队管理。