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

文档版本：v1.0
最后更新：2026-07-22
文档状态：生产环境已验证

概述

数眼智能提供统一的 AI API 网关服务。除控制台页面操作外，平台开放了 API 密钥（令牌）的全生命周期管理接口，支持通过程序化方式创建密钥、查询密钥、调整密钥额度、启用/禁用及删除密钥，适用于企业客户的自动化发号、额度分配与密钥轮换场景。

本文档为管理类接口，均为写操作或含敏感信息的读操作，请妥善保管系统访问令牌。仅需查询余额与用量，请参阅 API 密钥与额度查询接口。

服务地址

用途	地址
AI 模型调用 & OpenAI 兼容接口	`https://platform.shuyanai.com`
平台管理接口（本文档）	`https://www.shuyanai.com/apex`

重要：本文档所有接口均以 https://www.shuyanai.com/apex 为基础地址。platform.shuyanai.com 仅提供 /v1/ 模型接口，不提供管理接口。

鉴权方式

所有接口均使用系统访问令牌鉴权，需同时携带以下两个请求头：

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

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

系统访问令牌与用户数字 ID 必须属于同一账户，不匹配将返回 401。
系统访问令牌具备密钥管理权限，请按最高敏感级别保管，泄露后请立即在控制台重置。
所有接口仅能操作本账户名下的密钥。

额度单位说明

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

500,000 额度单位 = 1 美元（$1）

remain_quota 取值	美元	人民币（控制台显示，$1 = ¥7）
50000	$0.1	¥0.7
500000	$1	¥7
5000000	$10	¥70
50000000	$100	¥700

控制台「令牌管理」页面会同时显示美元与人民币金额，均由 remain_quota 换算而来。

设置 unlimited_quota: true 时密钥不受额度限制，remain_quota 值被忽略。

分组（group）说明

密钥的 group 字段决定该密钥路由到哪一类渠道资源池，并对应不同的计费倍率。这是发号时最容易踩坑的一步，请务必阅读。

默认分组可能无可用渠道

group 传空字符串时，密钥使用账户默认分组。部分账户的默认分组并未绑定可用渠道，此时用该密钥调用模型会返回：

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

建议创建密钥时显式指定一个有效分组，不要依赖默认分组。

查询本账户可用分组

GET /api/user/self/groups

响应按厂商归类，每个分组含描述与计费倍率 ratio：

{
  "data": {
    "deepseek": {
      "de-of-svip": {"desc": "...", "desc_en": "...", "ratio": 0.32},
      "ds-hs-svip": {"desc": "...", "desc_en": "...", "ratio": 0.72}
    },
    "qwen": { "qw-of-svip": {"desc": "...", "ratio": 0.55} }
  },
  "message": "",
  "success": true
}

将其中的分组名（如 de-of-svip）填入密钥的 group 字段即可。

⚠️ 修改分组后有生效延迟

通过 PUT /api/token/ 修改密钥分组，或新建密钥后，网关侧存在令牌缓存，分组变更需数秒（实测最多约 15 秒）才在模型调用侧生效。在此期间：

模型调用仍按旧分组路由；

可能短暂出现「分组 X 下模型无可用渠道」（X 为旧分组）。

这是正常的缓存刷新过程，并非配置错误。修改分组后请等待约 15 秒再验证，或对首次调用做重试。

model_not_found 排查

现象	原因	处理
`分组 X 下模型 Y 无可用渠道`	分组 X 未绑定模型 Y 的渠道	换用承载该模型的分组；用 `GET /api/user/self/groups` 确认
刚改完分组仍报旧分组无渠道	令牌缓存未刷新	等待约 15 秒后重试
特价分组间歇性无渠道	特价资源池并发/稳定性有限	改用稳定分组，或稍后重试

编码要求

请求体必须为 UTF-8 编码的 JSON。密钥名称含中文时请确保客户端以 UTF-8 发送：

Windows 命令行中在 curl 命令内直接内联中文会因本地编码（GBK）导致名称乱码入库；

请改用 curl --data @文件（文件保存为 UTF-8）或程序语言的 HTTP 客户端（如 Python requests/urllib）发送；

自动化脚本场景建议使用英文密钥名称，规避编码问题并便于按名称搜索。

一、创建密钥

创建一个新的 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}

创建接口不直接返回密钥内容，请随后调用「查询密钥列表」或「搜索密钥」获取新密钥的 id 与 key。

二、查询密钥列表

接口地址

GET /api/token/?p=1&size=20

参数	说明
`p`	页码，从 1 开始
`size`	每页条数

请求示例

响应示例（节选）

{
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 3,
    "items": [
      {
        "id": 21089,
        "user_id": 10001,
        "key": "PqXk****************************",
        "status": 1,
        "name": "prod-key-01",
        "created_time": 1784712786,
        "accessed_time": 1784712786,
        "expired_time": -1,
        "remain_quota": 5000000,
        "unlimited_quota": false,
        "used_quota": 0,
        "group": ""
      }
    ]
  },
  "message": "",
  "success": true
}

关键响应字段

字段	类型	说明
`id`	Integer	密钥 ID，修改/删除操作以此为准
`key`	String	密钥内容（调用模型接口时使用 `sk-` + 该值）
`status`	Integer	状态：`1` 启用，`2` 禁用，`3` 已过期，`4` 已耗尽
`remain_quota`	Integer	剩余额度（内部额度单位）
`used_quota`	Integer	累计已用额度
`unlimited_quota`	Boolean	是否无限额度
`expired_time`	Integer	过期时间戳，`-1` 永不过期

三、查询单个密钥 / 按名称搜索

GET /api/token/{id}
GET /api/token/search?keyword=<名称关键词>

请求示例

响应字段与「查询密钥列表」一致。

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

接口地址

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	是	回填原值

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

响应示例

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

调整成功后，控制台「令牌管理」页面的剩余额度（美元/人民币）实时同步更新。

校验规则

非无限额度时，remain_quota 不能为负数，且不能超过系统上限

remain_quota 为目标值语义：额度充值请自行计算 当前值 + 增量 后传入

已过期或已耗尽的密钥不能直接置回启用状态，需先修正 expired_time / remain_quota

五、仅启用 / 禁用密钥

只切换状态、不影响其他字段时，使用 status_only 参数，无需回填全量字段：

status：1 启用，2 禁用。

六、删除密钥

接口地址

DELETE /api/token/{id}

请求示例

响应示例

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

删除后密钥立即失效且不可恢复，请谨慎操作。

错误码

场景	响应	处理建议
令牌缺失/无效/与用户 ID 不匹配	`{"code":401,"msg":"未登录或登录已失效"}`	检查系统访问令牌与 `apex-api-user` 是否属于同一账户
密钥不存在或不属于本账户	`{"success":false,"message":"record not found"}`	检查密钥 `id`
额度为负数 / 超出上限	`{"success":false,"message":"..."}`	修正 `remain_quota`
名称超长	`{"success":false,"message":"..."}`	名称 ≤ 50 字符

FAQ

Q：调整密钥额度会影响账户余额吗？
A：不会。密钥额度与账户余额是两层独立配额，密钥消费时同时扣减两者。密钥额度总和可以超过账户余额，实际可用量以两者中先耗尽者为准。

Q：能通过本接口操作其他账户的密钥吗？
A：不能。所有接口仅作用于 apex-api-user 对应账户本人名下的密钥。

Q：额度可以调小吗？
A：可以。remain_quota 是目标值，调大调小均立即生效。

Q：通过接口的变更在控制台可见吗？
A：可见且实时。接口创建的密钥、调整后的额度会立即反映在控制台「令牌管理」页面（金额按美元与人民币双币种显示）。

Q：新建/改分组后调用报「无可用渠道」怎么办？
A：网关侧令牌缓存有数秒（最多约 15 秒）刷新延迟，期间仍按旧分组路由属正常现象，等待后重试即可。若持续报错，说明目标分组未绑定该模型渠道，请用 GET /api/user/self/groups 确认并改用有效分组。详见「分组（group）说明」。

变更记录

版本	日期	说明
v1.0	2026-07-22	首次发布：创建、查询、额度调整、启停、删除全流程，生产环境已验证

API 密钥管理接口文档

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

概述#

服务地址#

鉴权方式#

额度单位说明#

分组（group）说明#

默认分组可能无可用渠道#

查询本账户可用分组#

⚠️ 修改分组后有生效延迟#

model_not_found 排查#

编码要求#

一、创建密钥#

二、查询密钥列表#

三、查询单个密钥 / 按名称搜索#

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

⚠️ 重要：本接口为全量覆盖更新#

五、仅启用 / 禁用密钥#

六、删除密钥#

错误码#

FAQ#

变更记录#

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

概述

服务地址

鉴权方式

额度单位说明

分组（group）说明

默认分组可能无可用渠道

查询本账户可用分组

⚠️ 修改分组后有生效延迟

model_not_found 排查

编码要求

一、创建密钥

二、查询密钥列表

三、查询单个密钥 / 按名称搜索

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

⚠️ 重要：本接口为全量覆盖更新

五、仅启用 / 禁用密钥

六、删除密钥

错误码

FAQ

变更记录