数眼智能 API 密钥与额度查询接口文档

文档版本：v1.0
最后更新：2026-04-28
服务基址：https://platform.shuyanai.com

数眼智能平台提供三类计费查询接口，满足从第三方客户端快速集成到企业级精细化管控的全场景需求。

计费单位说明：本平台所有金额均以 人民币（CNY） 计价。接口响应中的 *_usd 字段名称沿用 OpenAI 兼容格式，实际返回值的单位为人民币（元），而非美元。

一、OpenAI 兼容接口

完全兼容 OpenAI 计费查询规范，可直接对接 Cherry Studio、NextChat、LobeChat 等主流大模型客户端，无需额外适配。

前置条件：此类接口位于 /v1/ 路径下，请求须通过平台的用户分组权限校验。若返回 "无权访问 xxx 分组" 错误，请联系管理员确认 API Key 的分组配置，或改用第二节的平台专属接口。

1.1 查询额度信息

获取当前 API Key 的额度上限及有效期信息。

请求

GET /v1/dashboard/billing/subscription
Authorization: Bearer <API Key>

响应示例（有限额度）

{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 7,
  "hard_limit_usd": 7,
  "system_hard_limit_usd": 7,
  "access_until": 0
}

响应示例（无限额度）

{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 100000000,
  "hard_limit_usd": 100000000,
  "system_hard_limit_usd": 100000000,
  "access_until": 0
}

响应参数

字段	类型	说明
`object`	String	固定值 `"billing_subscription"`
`has_payment_method`	Boolean	是否已绑定支付方式，固定为 `true`
`soft_limit_usd`	Float	额度上限，单位：人民币（元）。字段名沿用 OpenAI 格式，实际为人民币
`hard_limit_usd`	Float	硬性额度上限，单位：人民币（元）。与 `soft_limit_usd` 值相同
`system_hard_limit_usd`	Float	系统级硬性限额，单位：人民币（元）。与 `hard_limit_usd` 值相同
`access_until`	Integer	订阅有效截止时间（Unix 时间戳），`0` 表示永久有效

无限额度 Key：若 API Key 被设置为无限额度，上述三个限额字段将返回 100000000（1 亿），表示不受额度限制。

1.2 查询累计使用量

获取当前 API Key 的累计消费金额。

请求

GET /v1/dashboard/billing/usage
Authorization: Bearer <API Key>

start_date 和 end_date 查询参数为 OpenAI 兼容保留字段，当前版本返回的是该 Key 的全量累计使用量，不按日期范围过滤。

响应示例

{
  "object": "list",
  "total_usage": 0.0014
}

响应参数

字段	类型	说明
`object`	String	固定值 `"list"`
`total_usage`	Float	累计使用量，单位：人民币（分）。例如 `0.0014` 表示已消费 0.000014 元人民币

换算公式

实际消费（元） = total_usage ÷ 100

二、平台专属接口

数眼智能平台提供的高精度查询接口，可精确获取单个 API Key 的额度、用量及权限详情，适用于微服务架构下的实时额度校验与自动化运维。

该接口不受分组权限限制，任何有效的 API Key 均可调用。

2.1 API Key 实时状态查询

请求

GET /api/usage/token/
Authorization: Bearer <API Key>

响应示例（有限额度）

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "测试2",
    "total_granted": 500000,
    "total_used": 1,
    "total_available": 499999,
    "unlimited_quota": false,
    "model_limits": {},
    "model_limits_enabled": false,
    "expires_at": 0
  }
}

响应示例（无限额度）

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "cherry",
    "total_granted": 0,
    "total_used": 0,
    "total_available": 0,
    "unlimited_quota": true,
    "model_limits": {},
    "model_limits_enabled": false,
    "expires_at": 0
  }
}

响应参数（data 对象）

字段	类型	说明
`object`	String	固定值 `"token_usage"`
`name`	String	API Key 的备注名称
`total_granted`	Integer	该 Key 的总分配额度，单位：内部额度单位
`total_used`	Integer	该 Key 已消耗的累计额度，单位同上
`total_available`	Integer	当前剩余可用额度（`total_granted − total_used`），单位同上
`unlimited_quota`	Boolean	是否为无限额度。为 `true` 时该 Key 不受额度限制
`model_limits`	Object	模型访问限制规则。空对象 `{}` 表示无限制
`model_limits_enabled`	Boolean	是否启用模型级访问控制。为 `true` 时该 Key 仅可调用 `model_limits` 中列出的模型
`expires_at`	Integer	Key 过期时间（Unix 时间戳），`0` 表示永久有效

内部额度单位换算公式

人民币（元） = 内部额度值 ÷ 500000 × 7

其中 500000 为平台内部额度基准单位，7 为平台配置的美元兑人民币汇率。

换算示例

内部额度值	对应人民币	计算过程
`500000`	¥7.00	`500000 ÷ 500000 × 7 = 7`
`100000`	¥1.40	`100000 ÷ 500000 × 7 = 1.4`
`1000`	¥0.014	`1000 ÷ 500000 × 7 = 0.014`

无限额度 Key：当 unlimited_quota 为 true 时，total_granted、total_used、total_available 均为 0，这不代表无额度，而是表示该 Key 不受额度限制。应通过 unlimited_quota 字段判断额度状态，而非数值。

三、控制台管理接口

以下接口服务于数眼智能管理后台，需携带有效的用户级会话凭证（Session Cookie 或 JWT），不支持通过 API Key 调用。

接口路由	方法	说明
`/api/token/`	GET	获取当前账户的全部 API Key 列表及状态（支持分页）
`/api/token/:id`	GET	获取指定 API Key 的完整配置与消耗详情
`/api/token/search`	GET	按备注名或 Key 片段进行检索
`/api/subscription/self`	GET	获取当前用户的账户订阅信息

四、接口选型指南

接口	鉴权方式	适用场景	数据维度
`/v1/.../subscription`	API Key	第三方客户端集成，查看 Key 总额度	Key 级
`/v1/.../usage`	API Key	第三方客户端集成，查看累计消费	Key 级
`/api/usage/token/`	API Key	生产环境实时校验单 Key 额度与模型权限	Key 级
`/api/token/*`	用户登录态	内部运维管理看板	Key 级

建议：生产环境中推荐使用 /api/usage/token/ 接口进行额度监控。该接口不受分组权限限制、返回精度最高，且能准确区分有限额度与无限额度。

五、常见错误

HTTP 状态码	错误信息	原因	处理方式
200	`无权访问 xxx 分组`	API Key 所在分组未授权访问 `/v1/` 路径	联系管理员调整分组配置，或改用 `/api/usage/token/`
401	`Unauthorized`	API Key 无效或已过期	检查 Key 是否正确或联系管理员重新签发

API 密钥与额度查询接口

数眼智能 API 密钥与额度查询接口文档#

一、OpenAI 兼容接口#

1.1 查询额度信息#

1.2 查询累计使用量#

二、平台专属接口#

2.1 API Key 实时状态查询#

三、控制台管理接口#

四、接口选型指南#

五、常见错误#