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

文档版本：v2.0
最后更新：2026-06-01
文档状态：生产环境已验证
服务区域：国际站

概述

ve2s.ai Cloud 提供统一的 AI API 网关服务，聚合全球 100+ 顶尖大模型（OpenAI GPT、Anthropic Claude、Google Gemini、DeepSeek、豆包等），支持 OpenAI 兼容协议接入。本文档详细说明密钥状态查询、额度管理、用量统计及账户管理相关的全部 API 接口。

服务地址

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

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

鉴权方式

方式一：API Key 鉴权

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

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

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

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

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

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

系统访问令牌在控制台「个人设置 → 账户管理 → 安全设置」中查看和复制。用户数字 ID 需要联系后台管理员查看。

一、OpenAI 兼容接口

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

基础地址：https://cloud.ve2s.ai

1.1 查询账户额度

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

接口地址

GET /v1/dashboard/billing/subscription

请求头

名称	必填	说明
`Authorization`	是	`Bearer <API-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	软性额度上限（美元），达到后触发预警通知
`hard_limit_usd`	Number	硬性额度上限（美元），达到后暂停服务
`system_hard_limit_usd`	Number	系统级硬限额，与 `hard_limit_usd` 一致
`access_until`	Integer	订阅到期时间（Unix 时间戳），`0` 表示永不过期

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

1.2 查询累计用量

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

接口地址

GET /v1/dashboard/billing/usage

请求头

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

请求示例

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

响应示例

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

响应字段

字段	类型	说明
`object`	String	固定值 `"list"`
`total_usage`	Number	累计使用量，单位：美分（美元 × 100）。例如 `601.41` 表示已消费 $6.01

1.3 查询可用模型列表

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

接口地址

GET /v1/models

请求头

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

请求示例

响应示例

{
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai"]
    },
    {
      "id": "claude-opus-4-6",
      "object": "model",
      "created": 1626777600,
      "owned_by": "vertex-ai",
      "supported_endpoint_types": ["openai", "anthropic"]
    },
    {
      "id": "gemini-2.5-pro-thinking",
      "object": "model",
      "created": 1626777600,
      "owned_by": "custom",
      "supported_endpoint_types": ["openai", "gemini"]
    }
  ],
  "object": "list",
  "success": true
}

响应字段

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

二、平台专属接口

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

基础地址：https://www.ve2s.ai/apex

2.1 API Key 实时状态查询

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

接口地址

GET /api/usage/token/

请求头

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

请求示例

响应示例（有限额度）

{
  "code": true,
  "message": "ok",
  "data": {
    "object": "token_usage",
    "name": "my-production-key",
    "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": "default-key",
    "total_granted": 500000,
    "total_used": 3007043,
    "total_available": -2507043,
    "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

内部额度值	对应美元	计算过程
`5,000,000`	$10.00	5000000 ÷ 500000 = 10
`3,007,043`	$6.01	3007043 ÷ 500000 ≈ 6.01
`500,000`	$1.00	500000 ÷ 500000 = 1

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

三、控制台管理接口

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

基础地址：https://www.ve2s.ai/apex

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

3.1 获取用户信息

获取指定用户的账户详情。

接口地址

GET /api/user/self

请求头

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

请求示例

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "id": 669,
    "username": "example_user",
    "display_name": "example_user",
    "email": "user@example.com",
    "role": 1,
    "status": 1,
    "group": "pro",
    "quota": 4084864,
    "used_quota": 269527941,
    "request_count": 9412,
    "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	账户级已消耗总额度
`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": 56,
    "items": [
      {
        "id": 11848,
        "user_id": 669,
        "key": "0jCu7MEFsd6jzr...",
        "status": 1,
        "name": "openai-vip-pro",
        "created_time": 1778838568,
        "accessed_time": 1779028792,
        "expired_time": -1,
        "remain_quota": -1279,
        "unlimited_quota": true,
        "model_limits_enabled": false,
        "model_limits": "",
        "allow_ips": "",
        "used_quota": 1279,
        "group": "gpt-vip-pro",
        "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 <系统访问令牌>`
`apex-api-user`	是	目标用户的数字 ID

请求示例

响应示例

{
  "success": true,
  "message": "",
  "data": {
    "id": 11527,
    "user_id": 669,
    "key": "2UWqFGoE2AM2FY...",
    "status": 1,
    "name": "cl-of",
    "created_time": 1778739907,
    "accessed_time": 1779454195,
    "expired_time": -1,
    "remain_quota": -36107,
    "unlimited_quota": true,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": "",
    "used_quota": 36107,
    "group": "cl-of-pro",
    "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": 11848,
        "user_id": 669,
        "key": "0jCu7MEFsd6jzr...",
        "status": 1,
        "name": "openai-vip-pro",
        "unlimited_quota": true,
        "used_quota": 1279,
        "group": "gpt-vip-pro"
      }
    ]
  }
}

重要提示：此接口执行精确全名匹配，不支持模糊搜索。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	第三方客户端集成 — 查看账户总额度	账户级
`/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 状态或重新创建
系统令牌无效	`{"code":401,"msg":"未登录或登录已失效"}`	系统访问令牌错误或已过期	在「个人设置 → 账户管理 → 安全设置」中重新获取
用户 ID 错误	`{"code":401,"msg":"未登录或登录已失效"}`	`apex-api-user` 值不匹配有效用户	使用正确的用户数字 ID
路径错误	HTTP 404 `page not found`	混用了平台地址与管理代理地址	v1 接口用 `cloud.ve2s.ai`，api 接口用 `www.ve2s.ai/apex`
分组无权限	`无权访问 xxx 分组`	API Key 所在分组未授权访问	联系管理员调整分组配置，或改用 `/api/usage/token/`
搜索失败	`{"success":false,"message":"搜索令牌失败"}`	`keyword` 参数包含特殊字符或编码异常	使用 ASCII 字符搜索，确保完整匹配 Key 名称

六、SDK 集成示例

Python（OpenAI SDK）

JavaScript / TypeScript（OpenAI SDK）

cURL 快速验证

七、最佳实践

结果缓存：额度查询结果可缓存 30–60 秒以减少 API 负载

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

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

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

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

搜索注意：/api/token/search 仅支持精确全名匹配，如需模糊搜索请使用列表接口分页遍历

API 密钥与额度查询接口

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

七、最佳实践#

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

七、最佳实践