Skip to main content

​
API 密钥概述

在调用 PPIO 派欧云平台 的 API 产品时，需要在请求头中使用 Bearer 认证方式进行 API 访问认证。例如：“Authorization: Bearer {API 密钥}”。 每个 API 密钥都以 sk_ 开头，是一串随机字符串。密钥的有效期在创建时设置，详见密钥有效期。 您可以前往API 密钥管理页面查看和管理您的 API 密钥。每个账户最多可以生成 10 个密钥。
密钥的创建与删除仅在控制台提供，OpenAPI 不包含创建或删除密钥的接口，也不支持通过 OpenAPI 配置或修改密钥的过期时间。OpenAPI 提供密钥列表查询，以及单个密钥模型访问策略、网络访问策略的读写，详见查询 API Key 列表。
api-key-1

​
创建 API 密钥

  1. 进入API 密钥管理页面，单击「+创建」。
  2. 输入密钥名称，选择密钥有效期，然后单击「确认」。
  3. 保存密钥。
    API 密钥创建后无法再次查看，请妥善保存您的密钥。如果遗失，您需要生成新的密钥。

​
管理 API 密钥

对于已有的 API 密钥，支持以下操作：
  • 修改：单击对应的edit，输入新的密钥名称，单击「确认」即可完成修改。
  • 删除：单击对应的delete，确认后即可删除。
密钥一经删除即刻失效且不可恢复，使用该密钥的所有调用都会返回鉴权失败（HTTP 401）。删除前请确认没有线上业务仍在使用它。

​
密钥有效期

创建 API 密钥时可以设置过期时间，四档可选：永久、90 天、30 天、24 小时。
过期时间在创建时设定，创建后不可修改，也不支持续期或立即过期。选择「永久」时，密钥长期有效，泄露后风险更高，请谨慎使用。过期时间不支持通过 OpenAPI 配置或修改，只能在控制台创建密钥时设置。
密钥的过期状态在密钥列表和设置页统一展示为三种： 已过期的密钥调用会被拒绝，但配置仍可查看，删除入口保留。过期不等于禁用；需要恢复调用只能创建新密钥。如需在到期前停用某个密钥，可在控制台直接删除它，删除后立即失效。

​
访问控制

您可以分别限制单个 API 密钥可调用的模型和允许的来源 IP：

模型访问

限定密钥可调用的模型，并了解模型下线与调用被拒时的处理方式。

网络访问

限定允许的 IPv4 地址或 CIDR 网段，降低密钥泄露后的滥用风险。

​
用量与预算

您可以为单个 API 密钥单独设置消费上限，用于控制该密钥的模型 API 调用成本。密钥预算与成员预算两层限额同时生效，任一层达到上限都会暂停对应服务。 配置方式、预算类型（无上限 / 固定总预算 / 月度预算）和用尽后的提示，详见团队预算管理。
API Key 预算目前仅限制模型 API 的调用消费，GPU 实例、沙箱等产品的消费不受 Key 预算约束，但仍计入成员预算总额。

​
环境变量配置

建议把 API 密钥配置到环境变量，避免在代码里硬编码密钥，降低泄漏风险。代码从环境变量读取密钥，例如 os.environ["PPIO_API_KEY"]。

​
临时变量与永久变量

  • 临时变量：只在当前终端会话生效，关闭终端后失效，适合临时测试。
  • 永久变量：写入 shell 配置文件或系统环境变量，新开的终端和重启后仍然生效，适合长期使用。
下面按操作系统给出设置方法（以变量名 PPIO_API_KEY 为例）。
临时变量（仅当前终端会话有效）：
永久变量（写入 ~/.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）和不同用途分配独立密钥，便于按需停用和排查，互不影响。
  • 用模型访问、网络访问和预算收敛权限：结合模型访问限定单个密钥可调用的模型，结合网络访问限定允许的来源 IP，结合预算限定其消费上限，缩小单个密钥的影响面。
  • 定期轮换：定期更换密钥。轮换时先创建新密钥、切换业务使用新密钥、在生产验证无误后再删除旧密钥，实现零停机切换。

​
密钥泄露后的处理

如果怀疑某个密钥已泄露（例如误提交到公开仓库、出现在日志或截图中）：
  1. 立即进入 API 密钥管理页面删除该密钥，使其失效。
  2. 创建一个新密钥，更新到所有使用该密钥的业务中。为新密钥配置网络访问，只允许你的业务出口 IP，降低再次泄露后的风险。
  3. 通过操作审计检查是否存在异常操作，通过预算管理确认消费是否异常。
  4. 如需收紧团队成员对密钥的管理权限，参见团队管理。
最后修改于 2026年9月1日