API 密钥概述
在调用PPIO 派欧云平台的 API 产品时，通过使用请求头中的Bearer 认证方式进行 API 访问认证，例如，“Authorization: Bearer {API 密钥}”。 每个 API 密钥都以sk_ 开头，是一串随机字符串。密钥创建后长期有效，除非您在控制台手动删除它。
您可以前往API 密钥管理页面查看和管理您的 API 密钥。每个账户最多可以生成10个密钥。
密钥的创建与删除仅在控制台提供，OpenAPI 不包含创建或删除密钥的接口。OpenAPI 仅提供密钥列表查询，以及单个密钥模型访问策略的读写，详见查询 API Key 列表。
创建 API 密钥
- 进入API 密钥管理页面，单击「+创建」。
- 输入密钥名称，单击「确认」。
- 保存密钥。
管理 API 密钥
对于已有的 API 密钥，支持以下操作：- 修改：单击对应的
，输入新的密钥名称，单击「确认」即可完成修改。 - 删除：单击对应的
，确认后即可删除。
密钥有效期
当前，API 密钥创建后长期有效，不会自动过期，除非您在控制台手动删除它。删除后密钥立即失效。 如需停用某个密钥，请在控制台删除对应密钥；平台不会主动使密钥过期。模型访问
「模型访问」用于控制单个 API 密钥可以调用哪些模型。它不改变团队已开通的模型范围，只在团队已开通范围内进一步收敛某个密钥能访问的模型。未包含在访问范围内的模型，调用时会被直接拒绝。本能力覆盖大语言模型（LLM）产品线下的模型。图片、视频等独立多模态能力暂不纳入模型访问配置范围。
- 隔离不同用途的密钥：让生产密钥只访问稳定模型，实验密钥只访问低成本模型。
- 应急收敛风险：某个密钥出现非预期的高成本模型调用时，先把它限制到几个安全模型。
- 外部合作控制：临时提供给外包或合作方的密钥，只开放约定的模型。
访问模式
每个 API 密钥有一种访问模式，二选一：
两种模式下，实际可访问的模型都遵循同一条边界：不能超出团队已开通的模型范围，也不包含已下线的模型。
- 全部已开通模型：可访问模型 = 团队已开通模型（含未来新开通模型）− 已排除的模型。
- 仅限指定模型：可访问模型 = 已选定的模型（与团队已开通模型取交集）。
配置模型访问
只有团队的管理员可以配置 API 密钥的模型访问。开发者和基础用户可以查看与自己相关密钥的只读摘要，但不能编辑；财务管理员看不到模型访问入口。
1
进入 API 密钥管理页面
前往 API 密钥管理页面，找到要配置的 API 密钥。
2
打开模型访问设置
在创建或编辑该 API 密钥时，进入「模型访问」区域。
3
选择访问模式
选择「全部已开通模型」或「仅限指定模型」：
- 选择「全部已开通模型」时，可在「已排除的模型」中添加需要禁止访问的模型。
- 选择「仅限指定模型」时，在「可访问的模型」中至少添加一个模型。
4
保存
保存后，新的模型访问设置可能需要一段时间才会生效。
模型下线的影响
如果某个模型被平台下线，该模型不再属于可用模型集合：- 对该模型的所有调用会立即返回「模型不可用」。
- 历史配置中如果仍包含已下线模型，页面会保留展示并置灰提示；保存前必须先移除，否则不允许保存。
调用被拒的表现
当 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 为例）。
- Linux
- macOS
- Windows
临时变量（仅当前终端会话有效）：永久变量（写入 验证是否设置成功：
~/.bashrc，对 bash 生效；zsh 请写入 ~/.zshrc）：设置了变量但代码仍找不到
如果设置后代码依然读取不到密钥，按以下几种情况排查：- 只设了临时变量：
export或$env:只对当前终端会话有效，换个终端或重启后就没了。需要长期生效请改用永久变量（~/.bashrc/~/.zshrc/setx）。 - 改了配置但没重新加载：写入
~/.bashrc/~/.zshrc后，需要source对应文件或重开终端；IDE 内置终端通常要重启 IDE 才会加载新变量。 - 进程管理器不继承用户变量：用 systemd、supervisor、PM2 等托管服务时，不会自动继承你登录 shell 的环境变量，需要在各自的服务配置里单独声明。
- sudo 不继承当前环境：
sudo默认使用干净的环境，读不到当前用户的变量。需要传递时使用sudo -E，或在 root 环境下单独配置。
安全最佳实践与泄露应急
API 密钥等同于账户凭证，任何持有它的人都能以您的身份调用 API 并产生费用。请遵循以下实践：- 用环境变量存储：把密钥放进环境变量或密钥管理服务，不要硬编码进源代码。
- 不要提交到代码仓库：避免把密钥写进代码、配置文件后提交到 Git；对外分享代码或截图前先移除密钥。
- 不要放进前端：不要在浏览器端、移动 App 等客户端代码中直接使用密钥，这些环境的密钥可被他人提取。请通过您自己的后端中转调用。
- 一环境一密钥：为不同环境（生产、测试、CI）和不同用途分配独立密钥，便于按需停用和排查，互不影响。
- 用模型访问和预算收敛权限：结合模型访问限定单个密钥可调用的模型，结合预算限定其消费上限，缩小单个密钥的影响面。
- 定期轮换：定期更换密钥。轮换时先创建新密钥、切换业务使用新密钥、在生产验证无误后再删除旧密钥，实现零停机切换。
密钥泄露后的处理
如果怀疑某个密钥已泄露（例如误提交到公开仓库、出现在日志或截图中）：- 立即进入 API 密钥管理页面删除该密钥，使其失效。
- 创建一个新密钥，更新到所有使用该密钥的业务中。
- 通过操作审计检查是否存在异常操作，通过预算管理确认消费是否异常。
- 如需收紧团队成员对密钥的管理权限，参见团队管理。