汇飞智能

API 密钥管理接口文档

汇飞智能 — API 密钥管理接口文档

文档版本：v1.2
最后更新：2026-10-09

概述

本文介绍 API 密钥的创建、查询、额度调整、启用、禁用和删除接口。

查询余额与用量，请参阅API 密钥与额度查询接口。

服务地址

用途基础地址
模型调用（兼容 OpenAI 接口）https://api.sapis.cn
密钥创建、修改、启停、删除及分组查询https://sapis.cn
登录与完整密钥查询（第二章）https://sapis.cn

鉴权方式

本文所有管理接口均使用访问令牌鉴权，请求头只需携带：

Authorization: Bearer <访问令牌>
请求头必填说明
Authorization是Bearer <访问令牌>。令牌有两种来源：①在控制台登录后获得的登录访问令牌；②在控制台「安全与访问」中创建的访问令牌（系统访问令牌）

令牌本身即代表操作者身份：平台不需要、也不支持通过额外的用户 ID 参数指定其他账号。所有接口仅能操作当前令牌所属账号名下的密钥与资源，无法操作他人账号。

访问令牌泄露后，请在控制台「安全与访问」中撤销并重新创建。

额度单位说明

密钥额度字段（remain_quota）使用平台内部额度单位：

500,000 额度单位 = 1 元（¥1）
remain_quota 取值人民币
50000¥0.1
500000¥1
5000000¥10
50000000¥100
  • 控制台「API 密钥」页面显示的额度由 remain_quota 换算而来。
  • 设置 unlimited_quota: true 时密钥不受额度限制，remain_quota 值被忽略。

分组（group）说明

group 指定密钥使用的渠道分组。不同分组对应不同的可用模型和计费倍率。

默认分组

group 为空字符串时，密钥使用账号默认分组。若默认分组没有可用渠道，调用模型时会返回：

{"error":{"code":"model_not_found","message":"分组 xxx 下模型 yyy 无可用渠道（distributor）","type":"server_error"}}

建议创建密钥前查询可用分组，并将分组名填入 group。

查询可用分组

GET /api/user/self/groups
curl --location 'https://sapis.cn/api/user/self/groups' \
  --header 'Authorization: Bearer <访问令牌>'

响应列出当前账号可用的分组，包含分组描述和计费倍率 ratio：

{
  "success": true,
  "message": "",
  "data": {
    "default":  {"desc": "默认分组", "ratio": 1},
    "free":     {"desc": "免费模型", "ratio": 0},
    "国模":      {"desc": "国产模型", "ratio": 0.4},
    "国模特惠":   {"desc": "国产模型特惠渠道，稳定性逊于国模分组", "ratio": 0.3}
  }
}

将返回的分组名（如 国模特惠）填入 group。

分组生效时间

新建密钥或修改分组后，配置约需数秒生效。请等待约 15 秒后调用模型。在此期间，修改过分组的密钥可能仍使用原分组，并返回原分组无可用渠道的错误。

model_not_found 排查

现象原因处理
分组 X 下模型 Y 无可用渠道分组 X 未绑定模型 Y 的渠道查询可用分组，选择支持该模型的分组
刚改完分组仍报旧分组无渠道令牌缓存未刷新等待约 15 秒后重试
国模特惠分组间歇性无渠道国模特惠分组资源暂时不可用改用稳定分组，或稍后重试

编码要求

请求体使用 UTF-8 编码的 JSON。Windows 终端使用 GBK 编码时，直接输入中文可能导致乱码。可将请求体保存为 UTF-8 文件，通过 curl --data @文件 发送。

一、创建密钥

创建 API 密钥，并设置初始额度、有效期和分组。

接口地址

POST /api/token/

请求体参数

参数类型必填说明
nameString是密钥名称，最长 50 字符
remain_quotaInteger是初始额度（内部额度单位），≥ 0
unlimited_quotaBoolean是是否无限额度，true 时不受 remain_quota 限制
expired_timeInteger是过期时间（Unix 秒级时间戳），-1 表示永不过期
groupString否分组名，空字符串表示账号默认分组。可用分组见「分组（group）说明」
model_limits_enabledBoolean否是否启用模型白名单
model_limitsString否模型白名单，逗号分隔
allow_ipsString否IP 白名单，空表示不限制

请求示例

curl --location --request POST 'https://sapis.cn/api/token/' \
  --header 'Authorization: Bearer <访问令牌>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "prod-key-01",
    "remain_quota": 5000000,
    "unlimited_quota": false,
    "expired_time": -1,
    "group": "",
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": ""
  }'

响应示例

{"message": "", "success": true}

创建成功后，按「二、查询完整密钥」获取密钥内容。

二、查询完整密钥

密钥列表和详情接口返回的 key 都是脱敏值。要获取完整密钥，依次调用以下接口：

步骤请求获取的字段
1. 登录POST /api/user/logindata.access_token：登录访问令牌
2. 查询密钥 IDGET /api/token/searchdata.items[].id：密钥 ID
3. 查询完整密钥POST /api/token/{id}/keydata.key：完整密钥

第 3 步无需再次提交密码：登录访问令牌可直接换取完整密钥，且只能换取当前账号名下的密钥。

第一步：登录

使用账号和密码登录，取得登录访问令牌，供后续请求使用。

接口地址

POST https://sapis.cn/api/user/login

请求头

请求头必填说明
Content-Type是application/json

请求体参数

参数类型必填说明
usernameString是登录用户名
passwordString是当前账号的登录密码

cURL 请求示例

curl --location --request POST 'https://sapis.cn/api/user/login' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "<用户名>",
    "password": "<当前账号登录密码>"
  }'

成功响应示例（节选）

{
  "success": true,
  "message": "",
  "data": {
    "access_token": "<登录访问令牌>",
    "token_type": "Bearer",
    "access_expires_at": 1791515062,
    "session": { "sid": "881ce14a-...", "login_method": "password" },
    "user": { "id": 9, "display_name": "demo", "group": "default", "quota": 49916248 }
  }
}

响应字段说明

字段类型说明
successBooleantrue 表示登录成功
data.access_tokenString登录访问令牌，填入后续请求的 Authorization: Bearer <access_token>
data.access_expires_atInteger访问令牌过期时间（Unix 秒级时间戳）
data.user.idInteger用户数字 ID（只读，仅用于核对账号）
messageString响应提示；成功时为空字符串

登录成功后，复制完整的 data.access_token 用于第二、三步。第 2、3 步直接使用该令牌作为 Authorization 即可，无需任何额外的用户 ID 参数。

第二步：查询密钥 ID

按密钥名称搜索，获取对应的密钥 ID。

接口地址

GET https://sapis.cn/api/token/search

请求头

请求头必填说明
Authorization是Bearer <data.access_token>

查询参数

参数类型必填说明
keywordString否密钥名称。精确匹配；含 % 时为模糊匹配（最多 2 个 %）
tokenString否按密钥值筛选（不含 sk- 前缀）
pInteger否页码，从 1 开始，默认 1
sizeInteger否每页条数

cURL 请求示例

curl --location --get 'https://sapis.cn/api/token/search' \
  --data-urlencode 'keyword=<密钥名称>' \
  --data-urlencode 'p=1' \
  --data-urlencode 'size=20' \
  --header 'Authorization: Bearer <登录访问令牌>'

将 keyword=<密钥名称> 换成你实际的密钥名称，例如 default。

如果不知道密钥名称，可先查询当前账号的密钥列表：

curl --location 'https://sapis.cn/api/token/?p=1&size=20' \
  --header 'Authorization: Bearer <登录访问令牌>'

成功响应示例（节选）

{
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "items": [
      {
        "id": 21089,
        "name": "prod-key-01",
        "key": "prod**********y-01"
      }
    ]
  },
  "message": "",
  "success": true
}

响应字段说明

字段类型说明
successBooleantrue 表示搜索或列表查询成功
data.pageInteger当前页码
data.page_sizeInteger每页条数
data.totalInteger符合条件的密钥总数
data.items[].idInteger密钥 ID，第三步作为路径参数使用
data.items[].nameString密钥名称
messageString响应提示；成功时为空字符串

找到名称匹配的记录，将其 id 填入第三步的地址。例如，上面的 prod-key-01 对应 21089。

有同名密钥时，需结合创建时间等信息确认记录。结果超过一页时，增加 p 翻页；data.items 为空表示本页没有记录。

此接口返回的 key 为脱敏值。完整密钥通过第三步获取。

第三步：查询完整密钥

使用第一步的登录访问令牌，提交第二步取得的密钥 ID。

接口地址

POST https://sapis.cn/api/token/{id}/key

路径参数

参数类型说明
idInteger第二步返回的密钥 id

请求头

请求头必填说明
Authorization是Bearer <登录访问令牌>

cURL 请求示例

curl --location --request POST 'https://sapis.cn/api/token/21089/key' \
  --header 'Authorization: Bearer <登录访问令牌>'

本请求使用 POST，地址为 /api/token/{id}/key，无请求体。将 21089 替换为第二步取得的 ID。

成功响应示例

{
  "success": true,
  "message": "",
  "data": {
    "key": "pzGoBTwBxpMV2FvDSpaJOMVP2nSCPcqbxJU0TYXcqX5fg5ag"
  }
}

响应字段说明

字段类型说明
successBooleantrue 表示查询成功
data.keyString完整密钥内容。不含 sk- 前缀
messageString响应提示；查询成功时为空字符串

模型调用的请求头填写如下（加不加 sk- 前缀平台均可识别）：

Authorization: Bearer <data.key 的完整值>

批量获取完整密钥

需要一次取回多个密钥时，使用 POST /api/token/batch/keys，请求体 {"ids":[1,2,3]}（最多 100 个），响应 data.keys 为 {密钥ID: 完整密钥} 的映射。

请勿将登录密码、访问令牌或完整密钥写入日志或代码仓库。

三、调整密钥额度（修改密钥）

接口地址

PUT /api/token/

本接口为全量覆盖更新，必须提交全部可写字段。仅提交 id 和 remain_quota 会清空密钥名称，并将过期时间置为 0（立即过期）。

请先调用 GET /api/token/{id} 读取当前配置，修改所需字段后，提交下表中的全部字段。

请求体参数

参数类型必填说明
idInteger是密钥 ID
nameString是密钥名称（回填原值）
remain_quotaInteger是修改后的剩余额度，非增加的额度
unlimited_quotaBoolean是是否无限额度
expired_timeInteger是过期时间戳（回填原值）
statusInteger是状态（回填原值）
groupString是分组（回填原值）
model_limits_enabledBoolean是是否启用模型白名单，未修改时保留原值
model_limitsString是模型白名单，未修改时保留原值
allow_ipsString是IP 白名单，未修改时保留原值

请求示例（将额度调整为 ¥2）

curl --location --request PUT 'https://sapis.cn/api/token/' \
  --header 'Authorization: Bearer <访问令牌>' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 21089,
    "name": "prod-key-01",
    "remain_quota": 1000000,
    "unlimited_quota": false,
    "expired_time": -1,
    "status": 1,
    "group": "",
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": ""
  }'

响应示例

{
  "data": { "id": 21089, "remain_quota": 1000000, "...": "..." },
  "message": "",
  "success": true
}

调整成功后，控制台「API 密钥」页面会同步显示新的剩余额度。

校验规则

  • 未启用无限额度时，remain_quota 不能为负数或超过系统上限。
  • 增加额度时，传入当前剩余额度与增加额度之和。
  • 重新启用已过期或额度已耗尽的密钥前，需先调整 expired_time 或 remain_quota。

四、启用 / 禁用密钥

仅修改状态时，设置 status_only=true，请求体只需提交 id 和 status：

curl --location --request PUT 'https://sapis.cn/api/token/?status_only=true' \
  --header 'Authorization: Bearer <访问令牌>' \
  --header 'Content-Type: application/json' \
  --data '{"id": 21089, "status": 2}'

status：1 启用，2 禁用。

五、删除密钥

接口地址

DELETE /api/token/{id}

请求示例

curl --location --request DELETE 'https://sapis.cn/api/token/21089' \
  --header 'Authorization: Bearer <访问令牌>'

响应示例

{"message": "", "success": true}

删除后密钥立即失效，且无法恢复。

常见错误

HTTP 200 也可能表示业务失败。所有接口统一以响应体的 success 字段判断成败：true 为成功，false 为失败，失败原因见 message。

场景响应处理建议
管理接口鉴权失败{"success":false,"code":"AUTH_UNAUTHORIZED","message":"..."}检查 Authorization 令牌是否有效且未过期，必要时重新登录或重建访问令牌
登录账号或密码错误{"success":false,"message":"用户名或密码错误…"}核对用户名与登录密码后重新登录（message 文案随语言变化）
登录访问令牌过期{"success":false,"code":"AUTH_TOKEN_EXPIRED","message":"..."}重新调用 /api/user/login 获取新的 data.access_token
访问令牌权限不足{"success":false,"code":"ACCESS_TOKEN_SCOPE_DENIED","message":"..."}为该访问令牌授予所需权限：查询 api_key:read，修改 api_key:write，查看完整密钥 api_key:reveal
密钥不存在或不属于当前账号{"success":false,"message":"record not found"}检查密钥 id；接口只能访问当前账号的密钥
完整密钥查询失败{"success":false,"message":"..."}检查登录令牌与密钥 ID
请求方法或地址错误HTTP 404，404 page not found核对方法和完整地址：搜索使用 GET，登录和完整密钥查询使用 POST
额度为负数 / 超出上限{"success":false,"message":"..."}修正 remain_quota
名称超长{"success":false,"message":"..."}名称最多 50 个字符

常见问题

Q：调整密钥额度会影响账号余额吗？
A：不会。密钥额度与账号余额独立设置，调用模型时同时扣减两者。密钥额度总和可以超过账号余额，但任一额度耗尽后均无法继续调用。

Q：能通过本接口操作其他账号的密钥吗？
A：不能。所有接口仅允许操作当前访问令牌所属账号名下的密钥。

Q：额度可以调小吗？
A：可以。将 remain_quota 设置为调整后的剩余额度即可。

Q：通过接口的变更在控制台可见吗？
A：可以。创建的密钥和调整后的额度会同步显示在控制台「API 密钥」页面。

Q：新建密钥或修改分组后，调用提示「无可用渠道」怎么办？
A：等待约 15 秒后重试。若持续报错，检查分组是否有该模型的可用渠道，详见「分组（group）说明」。

变更记录

版本日期说明
v1.22026-10-09对齐平台实际源码：改用登录访问令牌鉴权（去除不存在的 New-Api-User 请求头）；第二章改为 POST /api/user/login + POST /api/token/{id}/key 的完整密钥查询流程；修正响应与错误格式
v1.12026-09-28更新完整密钥查询流程，补充账号密码登录、密钥 ID 获取及密码验证的参数和示例
v1.02026-07-22首次发布：创建、查询、额度调整、启停、删除全流程，生产环境已验证
不会配置？联系我们首次免费远程协助配置