API 密钥与额度查询接口

汇飞 AI — API 密钥与额度查询接口文档

文档版本：v2.1 最后更新：2026-10-09 文档状态：生产环境已验证

概述

汇飞智能 AI 云平台提供统一的 AI API 网关服务，聚合主流大模型（DeepSeek、豆包、通义千问、GLM、MiniMax 等），支持 OpenAI 兼容协议接入。本文档详细说明密钥状态查询、额度管理、用量统计及账户管理相关的全部 API 接口。

服务地址

用途	地址
AI 模型调用 & OpenAI 兼容接口	`https://api.sapis.cn`
平台管理接口	`https://sapis.cn`

重要：/v1/ 开头的 OpenAI 兼容接口使用平台地址，/api/ 开头的管理接口使用管理代理地址。请勿混用。

鉴权方式

方式一：API Key 鉴权

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

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

API Key 可在平台控制台「API 密钥」中创建和管理。

方式二：访问令牌鉴权

适用于管理类操作（账户信息查询、密钥管理等）。请求头只需携带访问令牌：

Authorization: Bearer <访问令牌>

访问令牌有两种来源：在控制台「安全与访问」中创建的访问令牌，或登录接口 POST /api/user/login 返回的 data.access_token。令牌即代表操作者身份，平台不需要、也不支持通过额外的用户 ID 参数指定其他账号；所有管理接口仅能操作当前令牌所属账号名下的资源。

一、OpenAI 兼容接口

完全兼容 OpenAI 计费查询规范，支持任何 OpenAI SDK 或兼容客户端无缝接入。

基础地址：https://api.sapis.cn

1.1 查询账户额度

获取当前 API Key 所属账户的额度上限信息。

接口地址

GET /v1/dashboard/billing/subscription

请求头

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

请求示例

curl --location 'https://api.sapis.cn/v1/dashboard/billing/subscription' \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

响应示例

{
  "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	软性额度上限（人民币），达到后触发预警通知。字段名保留 `usd` 为 OpenAI 兼容格式
`hard_limit_usd`	Number	硬性额度上限（人民币），达到后暂停服务
`system_hard_limit_usd`	Number	系统级硬限额，与 `hard_limit_usd` 一致
`access_until`	Integer	订阅到期时间（Unix 时间戳），`0` 表示永不过期

无限额度：当 API Key 设置为无限额度时，三个限额字段均返回 100000000，表示不受额度限制。

币种说明：接口返回的额度数值单位为人民币（CNY），即 内部额度 ÷ 500,000。字段名中的 usd 后缀为 OpenAI 兼容协议保留命名，不代表实际币种。

1.2 查询累计用量

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

接口地址

GET /v1/dashboard/billing/usage

请求头

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

请求示例

curl --location 'https://api.sapis.cn/v1/dashboard/billing/usage' \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

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

响应示例

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

响应字段

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

1.3 查询可用模型列表

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

接口地址

GET /v1/models

请求头

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

请求示例

curl --location 'https://api.sapis.cn/v1/models' \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

响应示例

{
  "data": [
    {
      "id": "deepseek-v4-pro",
      "object": "model",
      "created": 1626777600,
      "owned_by": "custom",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "mimo-v2.5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "custom",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "Qwen3.8-Omni-Flash",
      "object": "model",
      "created": 1626777600,
      "owned_by": "custom",
      "supported_endpoint_types": ["openai"]
    }
  ],
  "object": "list",
  "success": true
}

响应字段

字段	类型	说明
`data`	Array	模型列表
`data[].id`	String	模型标识符，调用时使用此值
`data[].object`	String	固定值 `"model"`
`data[].created`	Integer	模型创建时间（Unix 时间戳）
`data[].owned_by`	String	模型提供商
`data[].supported_endpoint_types`	Array	支持的调用格式：`openai`、`anthropic`、`gemini`、`image-generation`、`embeddings`、`rerank` 等
`object`	String	固定值 `"list"`
`success`	Boolean	请求是否成功

二、平台专属接口

汇飞 AI 平台提供的高精度查询接口，可精确获取单个 API Key 的额度、用量及权限详情。该接口不受分组权限限制，任何有效的 API Key 均可调用。

基础地址：https://sapis.cn

2.1 API Key 实时状态查询

精确获取当前 API Key 的额度分配、消耗、剩余及模型权限信息。

接口地址

GET /api/usage/token/

请求头

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

请求示例

curl --location 'https://sapis.cn/api/usage/token/' \
  --header 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx'

响应示例（有限额度）

{
  "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": 500000,
    "total_used": 1114861,
    "total_available": -614861,
    "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	总分配额度（内部单位）。换算：`÷ 500,000 = 人民币`
`data.total_used`	Integer	已消耗累计额度（内部单位）
`data.total_available`	Integer	剩余可用额度（`total_granted − total_used`）
`data.unlimited_quota`	Boolean	是否为无限额度。为 `true` 时不受额度限制
`data.model_limits`	Object	模型访问限制规则。空对象 `{}` 表示无限制
`data.model_limits_enabled`	Boolean	是否启用模型级访问控制
`data.expires_at`	Integer	Key 过期时间（Unix 时间戳），`0` 表示永不过期

额度换算公式

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

其中 500,000 为系统额度基准单位（即 500,000 额度单位 = ¥1）。

内部额度值	对应人民币	计算过程
`5,000,000`	¥10.00	5000000 ÷ 500000 = 10
`1,114,861`	¥2.23	1114861 ÷ 500000 ≈ 2.23
`500,000`	¥1.00	500000 ÷ 500000 = 1

无限额度说明：当 unlimited_quota = true 时，total_available 可能为负值，仅反映累计消耗超出初始分配量，不影响服务可用性。

三、控制台管理接口

以下接口服务于平台管理场景，支持程序化管理账户内的 API Key 生命周期及订阅信息。

基础地址：https://sapis.cn

鉴权方式：访问令牌（参见上文「方式二」）

3.1 获取当前账号信息

获取当前访问令牌所属账号的账户详情。

接口地址

GET /api/user/self

请求头

名称	必填	说明
`Authorization`	是	`Bearer <访问令牌>`

请求示例

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

响应示例

{
  "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 = 人民币）
`used_quota`	Integer	账户级已消耗总额度（内部单位，÷500000 = 人民币）
`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 <访问令牌>`

查询参数

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

请求示例

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

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 14,
    "items": [
      {
        "id": 7641,
        "user_id": 1576,
        "key": "P2VRfvqZ5Wh4jw...",
        "status": 1,
        "name": "国模特惠",
        "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": "国模特惠",
        "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	模型限制规则（JSON 字符串，空 = 不限制）
`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 <访问令牌>`

请求示例

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

响应示例

{
  "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 <访问令牌>`

查询参数

参数	类型	必填	说明
`keyword`	String	否	搜索关键词（按备注名称）。不含 `%` 为精确匹配；含 `%` 为模糊匹配（最多 2 个 `%`，去掉 `%` 后至少 2 个字符）
`token`	String	否	按密钥值搜索（不含 `sk-` 前缀），规则同上
`p`	Integer	否	页码，默认 1
`size`	Integer	否	每页条数

请求示例

curl --location 'https://sapis.cn/api/token/search?keyword=def' \
  --header 'Authorization: Bearer <访问令牌>'

响应示例

{
  "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 不含 % 时为精确匹配，含 % 时为模糊匹配（最多 2 个 %）。若账号令牌数量超过平台上限，则仅允许精确匹配。

3.5 获取订阅信息

获取当前账号的订阅信息。

接口地址

GET /api/subscription/self

请求头

名称	必填	说明
`Authorization`	是	`Bearer <访问令牌>`

请求示例

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

响应示例

{
  "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	第三方客户端集成 — 查看账户总额度	账户级
`/v1/dashboard/billing/usage`	API Key	第三方客户端集成 — 查看累计消费	账户级
`/v1/models`	API 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，OpenAI 兼容，零适配成本
生产环境额度监控：使用 /api/usage/token/，精度最高，不受分组权限限制
程序化运维：使用访问令牌鉴权的管理接口，实现账户内资源的程序化管理

五、错误码参考

场景	响应内容	原因	处理方式
API Key 无效	HTTP 401 `Unauthorized`	Key 无效、已过期或被禁用	在控制台确认 Key 状态或重新创建
访问令牌无效	`{"success":false,"code":"AUTH_UNAUTHORIZED","message":"..."}`	访问令牌错误或已过期	在控制台「安全与访问」中重建，或重新登录获取 `data.access_token`
访问令牌权限不足	`{"success":false,"code":"ACCESS_TOKEN_SCOPE_DENIED","message":"..."}`	令牌缺少该接口所需权限	为令牌授予对应权限（如 `api_key:read`、`api_key:write`、`wallet:read`）
路径错误	HTTP 404 `page not found`	混用了平台地址与管理代理地址	v1 接口用 `api.sapis.cn`，api 接口用 `sapis.cn`
分组无权限	`无权访问 xxx 分组`	API Key 所在分组未授权访问	联系管理员调整分组配置，或改用 `/api/usage/token/`
搜索失败	`{"success":false,"message":"搜索令牌失败"}`	`keyword` 参数包含特殊字符或编码异常	使用合法关键词；含 `%` 时为模糊匹配（最多 2 个 `%`）

六、SDK 集成示例

Python（OpenAI SDK）

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxx",
    base_url="https://api.sapis.cn/v1"
)

# 查询可用模型
models = client.models.list()
for model in models.data:
    print(f"{model.id} ({model.owned_by})")

# 对话补全
response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "你好！"}]
)
print(response.choices[0].message.content)

JavaScript / TypeScript（OpenAI SDK）

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-xxxxxxxxxxxxxxxx',
  baseURL: 'https://api.sapis.cn/v1',
});

// 查询模型列表
const models = await client.models.list();
console.log(models.data.map(m => m.id));

// 对话补全
const response = await client.chat.completions.create({
  model: 'mimo-v2.5',
  messages: [{ role: 'user', content: '你好！' }],
});
console.log(response.choices[0].message.content);

cURL 快速验证

# 验证 API Key 有效性
curl -s 'https://api.sapis.cn/v1/models' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' | jq '.data | length'

# 查询额度详情
curl -s 'https://sapis.cn/api/usage/token/' \
  -H 'Authorization: Bearer sk-xxxxxxxxxxxxxxxx' | jq '.data'

# 查询当前账户信息
curl -s 'https://sapis.cn/api/user/self' \
  -H 'Authorization: Bearer <访问令牌>' | jq '.data'

七、最佳实践

结果缓存：额度查询结果可缓存 30–60 秒以减少 API 负载
轮询频率：生产环境监控建议不超过每分钟 1 次查询
错误重试：对临时性失败实现指数退避重试
密钥隔离：为不同业务使用不同 Key，便于独立监控消耗
额度告警：当 total_available 低于阈值时触发告警通知
搜索注意：/api/token/search 仅支持精确全名匹配，如需模糊搜索请使用列表接口分页遍历

汇飞智能 AI 云平台 — 让 AI 触手可及

#API 密钥与额度查询接口

#汇飞 AI — API 密钥与额度查询接口文档

#概述

#服务地址

#鉴权方式

#方式一：API Key 鉴权

#方式二：访问令牌鉴权

#一、OpenAI 兼容接口

#1.1 查询账户额度

#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 密钥与额度查询接口

汇飞 AI — API 密钥与额度查询接口文档

概述

服务地址

鉴权方式

方式一：API Key 鉴权

方式二：访问令牌鉴权

一、OpenAI 兼容接口

1.1 查询账户额度

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 快速验证

七、最佳实践