API 密钥与额度查询接口

概述

数眼智能 AI 云平台提供统一的 AI API 网关服务，聚合 DeepSeek、豆包、通义千问、GLM、MiniMax 等大模型，支持 OpenAI 兼容协议接入。本文说明 API Key 的额度查询、用量统计及账户管理相关接口。

创建、修改、删除 API Key 请参阅 API 密钥管理接口文档。

服务地址

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

重要：/v1/ 开头的 OpenAI 兼容接口使用平台地址，/api/ 开头的管理接口使用管理地址（必须带 www）。混用会返回 404。

鉴权方式

方式一：API Key 鉴权

适用于模型调用及 Key 自身的额度查询。通过标准 HTTP Header 传递 API Key：

Authorization: Bearer sk-xxx

API Key 可在控制台「模型 API Key」页面（www.shuyanai.com/admin/tokens）创建和管理。

方式二：系统访问令牌鉴权

适用于管理类操作（用户信息查询、Key 列表等）。需同时携带系统访问令牌和用户数字 ID：

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

系统访问令牌在控制台「个人设置 → 账户管理 → 安全设置」中生成和复制，重新生成后旧令牌失效。用户数字 ID 请联系商务获取。

一、OpenAI 兼容接口

兼容 OpenAI 格式的额度与用量查询接口，可直接用于支持该格式的第三方客户端。

基础地址：https://platform.shuyanai.com

1.1 查询 Key 总额度

获取当前 API Key 的总额度（已用 + 剩余）。

接口地址

GET /v1/dashboard/billing/subscription

请求头

名称	必填	说明
`Authorization`	是	`Bearer <API-Key>`

请求示例

响应示例（无限额度的 Key）

{
  "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`	Number	Key 的总额度（已用 + 剩余），单位：人民币元
`hard_limit_usd`	Number	同 `soft_limit_usd`
`system_hard_limit_usd`	Number	同 `soft_limit_usd`
`access_until`	Integer	Key 过期时间（Unix 时间戳），`0` 表示永不过期

无限额度：Key 设置为无限额度时，三个额度字段均返回 100000000。
币种说明：返回值单位为人民币，字段名中的 usd 后缀为 OpenAI 兼容格式保留的命名，不代表实际币种。

1.2 查询累计用量

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

接口地址

GET /v1/dashboard/billing/usage

请求头

名称	必填	说明
`Authorization`	是	`Bearer <API-Key>`

请求示例

start_date 和 end_date 查询参数为兼容保留字段，传入后仍返回全量累计用量，不按日期过滤。

响应示例

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

响应字段

字段	类型	说明
`object`	String	固定值 `"list"`
`total_usage`	Number	该 Key 的累计用量，单位：人民币分（元 × 100）。例如 `1557.03` 表示已消费约 ¥15.57

1.3 查询可用模型列表

获取当前 API Key 可调用的全部模型。

接口地址

GET /v1/models

请求头

名称	必填	说明
`Authorization`	是	`Bearer <API-Key>`

请求示例

响应示例（节选）

{
  "data": [
    {
      "id": "deepseek-v4.1-flash",
      "object": "model",
      "created": 1626777600,
      "owned_by": "custom",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "glm-5.1",
      "object": "model",
      "created": 1626777600,
      "owned_by": "custom",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "doubao-seedream-5-0-260128",
      "object": "model",
      "created": 1626777600,
      "owned_by": "custom",
      "supported_endpoint_types": ["image-generation", "openai"]
    }
  ],
  "object": "list",
  "success": true
}

响应字段

字段	类型	说明
`data`	Array	模型列表
`data[].id`	String	模型名，调用时使用此值
`data[].object`	String	固定值 `"model"`
`data[].created`	Integer	时间戳（固定值，无实际含义）
`data[].owned_by`	String	固定值 `"custom"`
`data[].supported_endpoint_types`	Array	支持的调用格式，如 `openai`、`anthropic`、`image-generation`、`image-edit` 等
`object`	String	固定值 `"list"`
`success`	Boolean	请求是否成功

二、平台专属接口

查询单个 API Key 的额度、用量及模型权限详情，任何有效的 API Key 均可调用。

基础地址：https://www.shuyanai.com/apex

2.1 API Key 实时状态查询

接口地址

GET /api/usage/token/

请求头

名称	必填	说明
`Authorization`	是	`Bearer <API-Key>`

请求示例

响应示例（有限额度）

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

响应示例（无限额度）

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "初始令牌",
    "total_granted": 0,
    "total_used": 1112192,
    "total_available": -1112192,
    "unlimited_quota": true,
    "model_limits": {},
    "model_limits_enabled": false,
    "expires_at": 0
  }
}

响应字段

字段	类型	说明
`code`	Boolean	请求是否成功，`true` 表示成功
`message`	String	状态描述，成功时为 `"ok"`
`data.object`	String	固定值 `"token_usage"`
`data.name`	String	API Key 名称
`data.total_granted`	Integer	总额度（`total_used + total_available`，内部单位）
`data.total_used`	Integer	已消耗额度（内部单位）
`data.total_available`	Integer	剩余可用额度（内部单位）
`data.unlimited_quota`	Boolean	是否为无限额度，为 `true` 时不受额度限制
`data.model_limits`	Object	模型访问限制规则，空对象 `{}` 表示无限制
`data.model_limits_enabled`	Boolean	是否启用模型白名单
`data.expires_at`	Integer	Key 过期时间（Unix 时间戳），`0` 表示永不过期

额度换算公式

人民币金额 = 内部额度值 ÷ 500,000 × 7

内部额度值	对应人民币	计算过程
`5,000,000`	¥70.00	5000000 ÷ 500000 × 7 = 70
`1,112,192`	¥15.57	1112192 ÷ 500000 × 7 ≈ 15.57
`500,000`	¥7.00	500000 ÷ 500000 × 7 = 7

无限额度说明：unlimited_quota 为 true 时，total_available 可能为负值，仅表示累计消耗，不影响使用。

三、控制台管理接口

以下接口用于程序化查询账户、API Key 及订阅信息。

基础地址：https://www.shuyanai.com/apex

鉴权方式：系统访问令牌 + 用户数字 ID（参见上文「方式二」）

3.1 获取用户信息

接口地址

GET /api/user/self

请求头

名称	必填	说明
`Authorization`	是	`Bearer <系统访问令牌>`
`apex-api-user`	是	用户数字 ID

请求示例

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "id": 1576,
    "username": "example_user",
    "display_name": "example_user",
    "email": "user@example.com",
    "role": 1,
    "status": 1,
    "group": "default",
    "quota": 5593307,
    "used_quota": 4956693,
    "request_count": 463,
    "aff_code": "xxxx",
    "aff_count": 0,
    "aff_quota": 0,
    "aff_history_quota": 0,
    "inviter_id": 0
  }
}

响应字段（data 对象）

字段	类型	说明
`id`	Integer	用户数字 ID
`username`	String	登录用户名
`display_name`	String	显示名称
`email`	String	注册邮箱
`role`	Integer	用户角色。`1` = 普通用户，`10` = 管理员，`100` = 超级管理员
`status`	Integer	账户状态。`1` = 正常，`2` = 已禁用
`group`	String	用户所属分组
`quota`	Integer	账户剩余额度（内部单位，÷ 500000 × 7 = 人民币）
`used_quota`	Integer	账户已消耗额度（内部单位，÷ 500000 × 7 = 人民币）
`request_count`	Integer	API 累计请求次数
`aff_code`	String	推荐码
`aff_count`	Integer	已推荐用户数
`aff_quota`	Integer	待发放推荐奖励额度
`aff_history_quota`	Integer	历史累计推荐奖励总额
`inviter_id`	Integer	邀请人用户 ID，`0` 表示无邀请人

3.2 获取 API Key 列表

获取用户的全部 API Key，支持分页。

接口地址

GET /api/token/

请求头

名称	必填	说明
`Authorization`	是	`Bearer <系统访问令牌>`
`apex-api-user`	是	用户数字 ID

查询参数

参数	类型	默认值	说明
`p`	Integer	`1`	页码
`size`	Integer	`10`	每页数量

请求示例

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 14,
    "items": [
      {
        "id": 7641,
        "user_id": 1576,
        "key": "P2VRfvqZ5Wh4jw...",
        "status": 1,
        "name": "prod-key-01",
        "created_time": 1778044000,
        "accessed_time": 1778044000,
        "expired_time": -1,
        "remain_quota": 0,
        "unlimited_quota": true,
        "model_limits_enabled": false,
        "model_limits": "",
        "allow_ips": "",
        "used_quota": 0,
        "group": "default",
        "cross_group_retry": false
      }
    ]
  }
}

响应字段（data.items[]）

字段	类型	说明
`id`	Integer	API Key 数字 ID
`user_id`	Integer	所属用户 ID
`key`	String	Key 值（脱敏，不含 `sk-` 前缀）
`status`	Integer	Key 状态。`1` = 启用，`2` = 已禁用，`3` = 已过期
`name`	String	Key 名称
`created_time`	Integer	创建时间（Unix 时间戳）
`accessed_time`	Integer	最后访问时间（Unix 时间戳）
`expired_time`	Integer	过期时间（Unix 时间戳），`-1` = 永不过期
`remain_quota`	Integer	剩余额度（内部单位）
`unlimited_quota`	Boolean	是否无限额度
`model_limits_enabled`	Boolean	是否启用模型白名单
`model_limits`	String	模型白名单（逗号分隔，空 = 不限制）
`allow_ips`	String	IP 白名单（空 = 不限制）
`used_quota`	Integer	已消耗额度（内部单位）
`group`	String	Key 所属分组
`cross_group_retry`	Boolean	是否启用跨分组重试

分页字段

字段	类型	说明
`data.page`	Integer	当前页码
`data.page_size`	Integer	每页数量
`data.total`	Integer	总数

3.3 获取指定 API Key 详情

通过 Key 的数字 ID 获取详情。

接口地址

GET /api/token/{id}

路径参数

参数	类型	说明
`id`	Integer	API Key 的数字 ID

请求头

名称	必填	说明
`Authorization`	是	`Bearer <系统访问令牌>`
`apex-api-user`	是	用户数字 ID

请求示例

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "id": 3504,
    "user_id": 1576,
    "key": "ytgbjD0ItSv8Xd...",
    "status": 1,
    "name": "def",
    "created_time": 1775706400,
    "accessed_time": 1778658114,
    "expired_time": -1,
    "remain_quota": -2407369,
    "unlimited_quota": true,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": "",
    "used_quota": 2407369,
    "group": "default",
    "cross_group_retry": false
  }
}

响应字段与 3.2 节 items[] 一致。

3.4 搜索 API Key

按名称搜索 API Key。

接口地址

GET /api/token/search

请求头

名称	必填	说明
`Authorization`	是	`Bearer <系统访问令牌>`
`apex-api-user`	是	用户数字 ID

查询参数

参数	类型	必填	说明
`keyword`	String	是	Key 名称，需与名称完全一致

请求示例

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 1,
    "items": [
      {
        "id": 3504,
        "user_id": 1576,
        "key": "ytgbjD0ItSv8Xd...",
        "status": 1,
        "name": "def",
        "unlimited_quota": true,
        "used_quota": 2407369,
        "group": "default"
      }
    ]
  }
}

注意：此接口按名称精确匹配，不支持模糊搜索。keyword 必须与 Key 的完整名称一致。

3.5 获取订阅信息

接口地址

GET /api/subscription/self

请求头

名称	必填	说明
`Authorization`	是	`Bearer <系统访问令牌>`
`apex-api-user`	是	用户数字 ID

请求示例

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "subscriptions": [],
    "all_subscriptions": [],
    "billing_preference": "subscription_first"
  }
}

响应字段

字段	类型	说明
`data.subscriptions`	Array	当前生效的订阅计划
`data.all_subscriptions`	Array	全部订阅计划（含已过期）
`data.billing_preference`	String	计费优先级，`"subscription_first"` = 优先使用订阅额度

四、接口选型指南

接口	鉴权方式	适用场景	数据粒度
`/v1/dashboard/billing/subscription`	API Key	第三方客户端查看额度	Key 级
`/v1/dashboard/billing/usage`	API Key	第三方客户端查看累计消费	Key 级
`/v1/models`	API Key	查询 Key 可调用的模型	Key 级
`/api/usage/token/`	API Key	校验单个 Key 的额度与模型权限	Key 级
`/api/user/self`	系统令牌	查询账户信息与余额	用户级
`/api/token/`	系统令牌	Key 列表	Key 级
`/api/token/{id}`	系统令牌	单个 Key 详情	Key 级
`/api/token/search`	系统令牌	按名称查找 Key	Key 级
`/api/subscription/self`	系统令牌	订阅信息	用户级

推荐方案：

第三方客户端查询：使用 /v1/dashboard/billing/subscription + /v1/dashboard/billing/usage

生产环境额度监控：使用 /api/usage/token/，返回内部额度值，可精确换算

后台管理系统集成：使用系统令牌鉴权的管理接口

五、错误码参考

场景	响应内容	原因	处理方式
API Key 无效（`/v1/` 接口）	HTTP 401 `{"error":{"message":"无效的令牌 ...","type":"server_error"}}`	Key 错误、已删除或被禁用	在控制台确认 Key 状态或重新创建
API Key 无效（`/api/usage/token/`）	HTTP 401 `{"message":"无效的令牌","success":false}`	同上	同上
系统令牌无效	`{"code":401,"msg":"未登录或登录已失效"}`	系统访问令牌错误或已失效	在「个人设置 → 账户管理 → 安全设置」中重新获取
用户 ID 错误	`{"code":401,"msg":"未登录或登录已失效"}`	`apex-api-user` 与令牌不属于同一账号	使用正确的用户数字 ID
路径错误	HTTP 404 `404 page not found`	混用了平台地址与管理地址	`/v1/` 接口用 `platform.shuyanai.com`，`/api/` 接口用 `www.shuyanai.com/apex`
搜索失败	`{"success":false,"message":"搜索令牌失败"}`	`keyword` 包含特殊字符或编码异常	确保 `keyword` 与 Key 名称完全一致

六、SDK 集成示例

Python（openai SDK）

JavaScript / TypeScript（openai SDK）

cURL 快速验证

七、最佳实践

结果缓存：额度查询结果可缓存 30～60 秒，减少请求次数

轮询频率：生产环境监控建议不超过每分钟 1 次

错误重试：对临时性失败做指数退避重试

密钥隔离：不同业务使用不同 Key，便于独立监控消耗

额度告警：total_available 低于阈值时触发告警

按名称查找：/api/token/search 只支持完整名称，如需模糊查找请分页遍历列表接口

API 密钥与额度查询接口

概述#

服务地址#

鉴权方式#

方式一：API Key 鉴权#

方式二：系统访问令牌鉴权#

一、OpenAI 兼容接口#

1.1 查询 Key 总额度#

1.2 查询累计用量#

1.3 查询可用模型列表#

二、平台专属接口#

2.1 API Key 实时状态查询#

三、控制台管理接口#

3.1 获取用户信息#

3.2 获取 API Key 列表#

3.3 获取指定 API Key 详情#

3.4 搜索 API Key#

3.5 获取订阅信息#

四、接口选型指南#

五、错误码参考#

六、SDK 集成示例#

Python（openai SDK）#

JavaScript / TypeScript（openai SDK）#

cURL 快速验证#

七、最佳实践#

概述

服务地址

鉴权方式

方式一：API Key 鉴权

方式二：系统访问令牌鉴权

一、OpenAI 兼容接口

1.1 查询 Key 总额度

1.2 查询累计用量

1.3 查询可用模型列表

二、平台专属接口

2.1 API Key 实时状态查询

三、控制台管理接口

3.1 获取用户信息

3.2 获取 API Key 列表

3.3 获取指定 API Key 详情

3.4 搜索 API Key

3.5 获取订阅信息

四、接口选型指南

五、错误码参考

六、SDK 集成示例

Python（openai SDK）

JavaScript / TypeScript（openai SDK）

cURL 快速验证

七、最佳实践