• 简体中文
  • API Key 管理

    API Key(令牌)是调用本站 API 的唯一凭据,以 sk- 开头。所有请求通过 HTTP 头 Authorization: Bearer sk-xxxx 携带令牌完成鉴权。

    管理入口:控制台 →「常规」→「API 密钥」,或直接访问 https://api-model.shuntianchuang.cn/keys。

    什么是 API Key(令牌)

    • 一个账号可以创建多个 API Key,各自独立设置额度、有效期和可用模型
    • 每个 Key 单独计量,方便区分项目、环境(开发 / 生产)或团队成员
    • Key 可以随时禁用、启用或删除,不影响账号本身

    创建步骤

    1. 进入「API 密钥」页面,点击右上角「创建 API 密钥」按钮。

      API 密钥列表页

    2. 在弹窗的「基本信息」中填写:

      创建 API 密钥弹窗

      • 名称:必填,便于识别用途,如 my-project-dev
      • 分组:选择令牌所属分组(不同分组的模型倍率可能不同,一般选 default)
      • 过期时间:默认「永不过期」,也可以点选快捷项(1 小时 / 1 天 / 1 个月)或自定义时间
      • 数量:一次性批量创建多个密钥(名称自动添加随机后缀),默认为 1
    3. 在「额度设置」中决定令牌可用额度:

      • 「无限配额」开关默认开启,表示令牌可使用的额度上限等于账户余额
      • 关闭后可填写固定额度,适合限制单个项目或成员的用量
    4. (可选)展开「高级设置」配置访问限制(详见下方参数说明)。

    5. 点击「保存更改」,列表中出现新建的密钥。

      复制 API 密钥

    TIP

    出于安全考虑,列表中的密钥默认以 sk-Ab3d**********Xy9z 形式中间打码显示。点击密钥即可复制完整值,请创建后及时保存到安全位置。

    参数说明

    参数说明建议
    名称令牌的显示名称按用途命名,如 cherry-studio、server-prod
    分组令牌所属的用户分组,影响可用模型与倍率不确定时选 default
    过期时间令牌失效时间,默认永不临时用途建议设短有效期
    额度令牌可消耗的配额上限,默认无限给团队成员分发时建议设上限
    模型限制限定此 Key 只能调用选中的模型,留空允许全部生产环境建议只放开所需模型
    IP 白名单每行一个 IP(支持 CIDR 表达式),留空不限制服务器固定 IP 场景可配置
    WARNING

    站点对「IP 白名单」的提示:请勿过度信任此功能,IP 可能被伪造,请配合 nginx 和 CDN 等网关使用。

    管理已有 Key

    密钥列表支持以下操作:

    操作入口说明
    复制密钥点击列表中的密钥值复制完整密钥到剪贴板
    禁用 / 启用行内「禁用」按钮暂停某个 Key 的调用,不删除
    编辑行内「编辑」按钮修改名称、额度、过期时间、模型限制、IP 白名单
    删除行内「打开菜单」→ 删除彻底删除,不可恢复
    筛选顶部「按名称筛选」「按 API 密钥筛选」「状态」快速定位大量密钥

    列表字段含义:状态(已启用 / 已禁用)、额度(剩余额度与已使用金额)、分组、模型(限制范围)、IP 限制、创建时间、最后使用时间、过期时间。

    令牌安全

    WARNING

    API Key 等同于你的账户密码:

    1. 不要把令牌写死在代码里、提交到 Git 仓库或发布到前端页面
    2. 不要在公开场合(群聊、截图、博客)暴露完整令牌
    3. 建议通过环境变量注入,如 export SHUNTIANCHUANG_API_KEY=sk-你的令牌
    4. 一旦怀疑泄露,立即在 API 密钥页 删除或禁用对应令牌

    令牌创建后遇到调用报错?先看 错误码对照与排查,或参考 快速开始 末尾的常见失败原因。