数眼智能 — API 密钥管理接口文档

文档版本：v1.2
最后更新：2026-11-02

概述

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

服务地址

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

鉴权方式

创建、修改、启停、删除及分组查询接口使用系统访问令牌，需携带以下请求头：

Authorization: Bearer <系统访问令牌>
apex-api-user: <用户数字ID>

请求头	必填	说明
`Authorization`	是	`Bearer <系统访问令牌>`。在控制台「个人设置 → 账户管理 → 安全设置」中生成和复制
`apex-api-user`	是	用户数字 ID，请联系商务获取

系统访问令牌与用户数字 ID 必须属于同一账号。系统访问令牌泄露后，请在控制台重置。

第二章的完整密钥查询使用账号密码登录后返回的登录令牌，无需填写 apex-api-user。所有接口仅支持操作当前账号的密钥。

额度单位说明

密钥额度字段（remain_quota）使用平台内部额度单位，换算为人民币：

人民币金额 = remain_quota ÷ 500,000 × 7

remain_quota 取值	控制台显示
50000	¥0.7
500000	¥7
5000000	¥70
50000000	¥700

控制台「模型 API key」页面显示的额度由 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

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

{
  "data": {
    "deepseek": {
      "<分组名>": {"desc": "...", "desc_en": "...", "ratio": 1}
    }
  },
  "message": "",
  "success": true
}

将返回的分组名填入 group。更多分组信息请联系商务。

分组生效时间

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

model_not_found 排查

现象	原因	处理
`分组 X 下模型 Y 无可用渠道`	分组 X 未绑定模型 Y 的渠道	查询可用分组，选择支持该模型的分组
刚改完分组仍报旧分组无渠道	令牌缓存未刷新	等待约 15 秒后重试

编码要求

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

一、创建密钥

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

接口地址

POST /api/token/

请求体参数

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

请求示例

响应示例

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

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

二、查询完整密钥

准备账号、登录密码和密钥名称，依次调用以下接口：

步骤	请求	获取的字段
1. 登录	`POST /api/client/login`	`data.token`：登录令牌
2. 查询密钥 ID	`GET /api/apex/api/token/search`	`data.items[].id`：密钥 ID
3. 查询完整密钥	`POST /api/client/token/plain`	`data.key`：完整密钥

尚未设置登录密码的账号，请先登录控制台，在「模型 API key」页面点击密钥的「查看」，按弹窗提示设置密码。

第一步：登录

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

接口地址

POST https://www.shuyanai.com/api/client/login

请求头

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

请求体参数

参数	类型	必填	说明
`account`	String	是	账号绑定的手机号或邮箱；手机号需连续填写，不含空格
`password`	String	是	当前账号的登录密码

cURL 请求示例

成功响应示例（节选）

{
  "code": 0,
  "data": {
    "token": "<登录令牌>"
  },
  "msg": ""
}

响应字段说明

字段	类型	说明
`code`	Integer	响应状态码，`0` 表示登录成功
`data.token`	String	登录令牌，填入后续请求的 `Authorization: Bearer <登录令牌>`
`msg`	String	响应提示；登录成功时为空字符串

code 为 0 时，复制完整的 data.token，不包含两侧的双引号。其他账号信息无需复制。

第二步：查询密钥 ID

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

接口地址

GET https://www.shuyanai.com/api/apex/api/token/search

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <登录令牌>`，使用第一步返回的 `data.token`

查询参数

参数	类型	必填	说明
`keyword`	String	是	密钥名称，需与名称完全一致
`p`	Integer	否	页码，从 1 开始，默认值为 1
`size`	Integer	否	每页条数，本例传入 `20`

cURL 请求示例

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

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

成功响应示例（节选）

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

响应字段说明

字段	类型	说明
`success`	Boolean	`true` 表示搜索或列表查询成功
`data.page`	Integer	当前页码
`data.page_size`	Integer	每页条数
`data.total`	Integer	符合条件的密钥总数
`data.items[].id`	Integer	密钥 ID，第三步作为 `token_id` 提交
`data.items[].name`	String	密钥名称
`message`	String	响应提示；成功时为空字符串

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

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

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

第三步：查询完整密钥

使用第一步的登录令牌，提交第二步的密钥 ID 和登录密码。

接口地址

POST https://www.shuyanai.com/api/client/token/plain

请求头

请求头	必填	说明
`Authorization`	是	`Bearer <登录令牌>`，使用第一步返回的 `data.token`
`Content-Type`	是	`application/json`

请求体参数

参数	类型	必填	说明
`token_id`	Integer	是	第二步返回的密钥 `id`
`password`	String	是	当前账号的登录密码

cURL 请求示例

本请求使用 POST，地址为 /api/client/token/plain。将 21089 替换为第二步取得的 ID，Body 使用 JSON。

成功响应示例

{
  "code": 0,
  "data": {
    "key": "sk-<完整密钥内容>"
  },
  "msg": ""
}

响应字段说明

字段	类型	说明
`code`	Integer	响应状态码，`0` 表示查询成功
`data.key`	String	查询到的完整密钥，已包含 `sk-` 前缀，可直接用于模型调用
`msg`	String	响应提示；查询成功时为空字符串

模型调用的请求头填写如下：

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

每次查询完整密钥都需提交登录密码。请勿将密码、登录令牌或完整密钥写入日志或代码仓库。

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

接口地址

PUT /api/token/

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

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

请求体参数

参数	类型	必填	说明
`id`	Integer	是	密钥 ID
`name`	String	是	密钥名称（回填原值）
`remain_quota`	Integer	是	修改后的剩余额度，非增加的额度
`unlimited_quota`	Boolean	是	是否无限额度
`expired_time`	Integer	是	过期时间戳（回填原值）
`status`	Integer	是	状态（回填原值）
`group`	String	是	分组（回填原值）
`model_limits_enabled`	Boolean	是	是否启用模型白名单，未修改时保留原值
`model_limits`	String	是	模型白名单，未修改时保留原值
`allow_ips`	String	是	IP 白名单，未修改时保留原值

请求示例（将剩余额度调整为 ¥14）

响应示例

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

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

校验规则

未启用无限额度时，remain_quota 不能为负数或超过系统上限。

增加额度时，传入当前剩余额度与增加额度之和。

重新启用已过期或额度已耗尽的密钥前，需先调整 expired_time 或 remain_quota。

四、启用 / 禁用密钥

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

status：1 启用，2 禁用。

五、删除密钥

接口地址

DELETE /api/token/{id}

请求示例

响应示例

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

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

常见错误

HTTP 200 不代表业务成功。登录和完整密钥查询以 code: 0 为成功，搜索和列表查询以 success: true 为成功。

场景	响应	处理建议
管理接口鉴权失败	`{"code":401,"msg":"未登录或登录已失效"}`	检查系统访问令牌与 `apex-api-user` 是否有效且属于同一账号
账号或密码为空	`{"code":400,"msg":"参数错误"}`	填写 `account` 和 `password`
登录账号格式错误	`code: -1`、`msg: "请输入有效账户"`	检查手机号或邮箱格式，手机号不含空格
登录密码错误	`code: -1`、`msg: "密码错误"`	核对账号和登录密码后重新登录
查询时登录令牌无效	`{"code":401,"msg":"未登录或登录已失效"}`	重新登录，用新的 `data.token` 更新请求头
管理接口中密钥不存在或不属于当前账号	`{"success":false,"message":"record not found"}`	检查密钥 `id`
完整密钥查询失败	`code` 非 `0`，`msg` 返回失败原因	按提示检查登录令牌、密钥 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 key」页面。

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

变更记录

版本	日期	说明
v1.2	2026-11-02	额度单位改为人民币说明；分组示例改用占位名；密钥搜索改为按名称精确匹配；补充「参数错误」响应
v1.1	2026-09-28	更新完整密钥查询流程，补充账号密码登录、密钥 ID 获取及密码验证的参数和示例
v1.0	2026-07-22	首次发布：创建、查询、额度调整、启停、删除全流程，生产环境已验证

API 密钥管理接口文档

数眼智能 — API 密钥管理接口文档#

概述#

服务地址#

鉴权方式#

额度单位说明#

分组（group）说明#

默认分组#

查询可用分组#

分组生效时间#

model_not_found 排查#

编码要求#

一、创建密钥#

二、查询完整密钥#

第一步：登录#

第二步：查询密钥 ID#

第三步：查询完整密钥#

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

四、启用 / 禁用密钥#

五、删除密钥#

常见错误#

常见问题#

变更记录#

数眼智能 — API 密钥管理接口文档

概述

服务地址

鉴权方式

额度单位说明

分组（group）说明

默认分组

查询可用分组

分组生效时间

model_not_found 排查

编码要求

一、创建密钥

二、查询完整密钥

第一步：登录

第二步：查询密钥 ID

第三步：查询完整密钥

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

四、启用 / 禁用密钥

五、删除密钥

常见错误

常见问题

变更记录