Token 用量

Token 用量接口用于查询通过模型网关产生的请求数、输入 Token、输出 Token、总 Token 和缓存命中 Token。用量数据由网关异步写入统计后端，可能与刚完成的请求存在短暂延迟；它表示实际调用记录，不等同于套餐中的实时限流剩余额度。

用量采集采用不阻塞模型请求的故障开放策略。统计通道或后端异常不会中断模型调用，但可能造成部分记录延迟或缺失，因此该接口适合运营分析和用量观察，不应作为唯一的财务计费或合规审计依据。

查询范围由 Token 身份和用量聚合权限确定，查询参数只能缩小范围，不能扩大权限：member 仅能查询当前项目中自己创建的消费者产生的用量；project_admin 可查询当前项目；domain_admin 可查询当前部门；cloud_admin 可查询全部部门和项目。

start 和 end 支持 RFC3339 或 YYYY-MM-DD，查询范围为 [start, end)；省略时默认查询截至当前时间的最近 7 天。eventTime 按北京时间自然日筛选，格式为 YYYY-MM-DD。分页默认第 1 页、每页 50 条，最多 200 条；page_size 优先于兼容参数 limit。

为兼容现有页面，字段 apiKeyId 和 apiKeyName 实际表示消费者 ID 和消费者名称，即同一消费者下多个 API Key 共享的调用身份；单次请求实际使用的 Key 标识由请求明细中的 keyId 返回。

当前项目的 CPU、内存和 AI 加速卡资源配额请参见租户与计算配额；消费者套餐的实时限流剩余额度请参见消费者与 API Key。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/tenants/current/usage	查询 Token 用量概览
GET	/tenants/current/usage/recent	查询最近请求用量明细
GET	/tenants/current/usage/model-daily	查询模型每日用量趋势

查询 Token 用量概览

功能介绍

查询授权范围内的 Token 用量汇总，并按部门、项目、用户、消费者、路由域名、模型和请求类型组成的完整维度进行分组。相同模型由不同消费者、用户或路由调用时会返回多条记录。

访问要求：有效 Token。返回范围由 member、project_admin、domain_admin 或 cloud_admin 用量权限确定。

URI

GET /api/v1/tenants/current/usage

查询参数

参数	类型	必选	描述
start	string	否	开始时间，RFC3339 或 YYYY-MM-DD；包含该时刻
end	string	否	结束时间，RFC3339 或 YYYY-MM-DD；不包含该时刻
limit	integer	否	兼容的每页数量参数，必须为正整数；page_size 优先
page	integer	否	聚合结果页码，从 1 开始，缺省为 1
page_size	integer	否	聚合结果每页数量，必须为正整数，缺省为 limit 或 50，最大为 200
apiKeyId	string	否	消费者 ID 精确筛选；字段名为历史兼容名称
domainId	string	否	部门 ID 精确筛选
projectId	string	否	项目 ID 精确筛选
userId	string	否	消费者创建者用户 ID 精确筛选
model	string	否	对外模型名称精确筛选
domainLike	string	否	调用方可见部门名称的模糊筛选
projectLike	string	否	调用方可见项目名称的模糊筛选
userLike	string	否	消费者创建者名称的模糊筛选，不区分大小写
modelLike	string	否	对外模型名称的模糊筛选，不区分大小写
apiKeyName	string	否	消费者名称的模糊筛选，不区分大小写；字段名为历史兼容名称
host	string	否	路由域名精确筛选
hostLike	string	否	路由域名模糊筛选，不区分大小写
requestType	string	否	请求类型精确筛选，例如 ai_chat、ai_completion、embeddings、responses、rerank、image、speech 或 transcription
status	integer	否	HTTP 响应状态码精确筛选，必须为正整数
eventTime	string	否	按北京时间自然日筛选，格式为 YYYY-MM-DD
sortField	string	否	排序字段；支持 totalTokens、requestCount、promptTokens、completionTokens、cacheHitTokens、domainId、projectId、userId、userName、apiKeyId、apiKeyName、host、model、requestType；缺省为 totalTokens
sortValue	string	否	排序方向：ascend 或 descend，缺省为 descend

请求消息

无请求体。

响应消息

参数	参数类型	描述
start	string(date-time)	实际查询开始时间，RFC3339
end	string(date-time)	实际查询结束时间，RFC3339
accessLevel	string	实际权限范围：member、project_admin、domain_admin 或 cloud_admin
domainId	string	请求中的部门 ID 筛选；未指定时为空字符串
projectId	string	请求中的项目 ID 筛选；未指定时为空字符串
userId	string	请求中的用户 ID 筛选；未指定时为空字符串
apiKeyId	string	请求中的消费者 ID 筛选；未指定时为空字符串
apiKeyName	string	apiKeyId 对应的消费者名称；无法解析或未指定时为空字符串
domainOptions	array	可用部门筛选项；仅 cloud_admin 返回可选项
projectOptions	array	可用项目筛选项；domain_admin 和 cloud_admin 返回可选项
userOptions	array	可用用户筛选项；project_admin、domain_admin 和 cloud_admin 返回可选项
apiKeyOptions	array	授权范围内可用的消费者筛选项
domainOptions[].id / projectOptions[].id / userOptions[].id	string	筛选项 ID
domainOptions[].name / projectOptions[].name / userOptions[].name	string	筛选项名称
domainOptions[].displayName / projectOptions[].displayName / userOptions[].displayName	string	用于界面展示的名称；重名时可能包含 ID 后缀
apiKeyOptions[].id	string	消费者 ID
apiKeyOptions[].name	string	消费者名称
apiKeyOptions[].displayName	string	消费者显示名称
summary	object	当前筛选范围的用量汇总，不受聚合列表分页影响
summary.requestCount	int64	请求总数
summary.promptTokens	int64	输入 Token 总数
summary.completionTokens	int64	输出 Token 总数
summary.totalTokens	int64	Token 总数
summary.cacheHitTokens	int64	缓存命中 Token 总数
byModel	array	按完整调用维度聚合的用量列表
byModel[].domainId	string	部门 ID
byModel[].domainName	string	部门名称
byModel[].projectId	string	项目 ID
byModel[].projectName	string	项目名称
byModel[].userId	string	消费者创建者用户 ID
byModel[].userName	string	消费者创建者名称
byModel[].apiKeyId	string	消费者 ID；字段名为历史兼容名称
byModel[].apiKeyName	string	消费者名称；字段名为历史兼容名称
byModel[].host	string	路由域名
byModel[].model	string	对外模型名称
byModel[].requestType	string	请求类型
byModel[].requestCount	int64	请求数
byModel[].promptTokens	int64	输入 Token 数
byModel[].completionTokens	int64	输出 Token 数
byModel[].totalTokens	int64	Token 总数
byModel[].cacheHitTokens	int64	缓存命中 Token 数
byModelTotal	int64	聚合结果总数
byModelPage	integer	聚合结果页码
byModelPageSize	integer	聚合结果每页数量
sortField	string	实际使用的排序字段
sortValue	string	实际使用的排序方向：ascend 或 descend

请求示例

GET https://{endpoint}/api/v1/tenants/current/usage?start=2026-09-15&end=2026-09-22&page=1&page_size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "start": "2026-09-15T00:00:00Z",
  "end": "2026-09-22T00:00:00Z",
  "accessLevel": "member",
  "domainId": "",
  "projectId": "",
  "userId": "",
  "apiKeyId": "",
  "apiKeyName": "",
  "domainOptions": [],
  "projectOptions": [],
  "userOptions": [],
  "apiKeyOptions": [
    {
      "id": "con-a1b2c3d4e5f6",
      "name": "生产应用",
      "displayName": "生产应用"
    }
  ],
  "summary": {
    "requestCount": 120,
    "promptTokens": 240000,
    "completionTokens": 60000,
    "totalTokens": 300000,
    "cacheHitTokens": 80000
  },
  "byModel": [
    {
      "domainId": "domain-a1b2c3d4",
      "domainName": "研发部门",
      "projectId": "project-a1b2c3d4",
      "projectName": "生产项目",
      "userId": "user-a1b2c3d4",
      "userName": "示例用户",
      "apiKeyId": "con-a1b2c3d4e5f6",
      "apiKeyName": "生产应用",
      "host": "api.example.com",
      "model": "qwen2.5-72b",
      "requestType": "ai_chat",
      "requestCount": 120,
      "promptTokens": 240000,
      "completionTokens": 60000,
      "totalTokens": 300000,
      "cacheHitTokens": 80000
    }
  ],
  "byModelTotal": 1,
  "byModelPage": 1,
  "byModelPageSize": 20,
  "sortField": "totalTokens",
  "sortValue": "descend"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_query	时间、分页、状态码、排序方向或排序字段无效，详细原因由 message 返回
401	unauthorized	authentication required
502	backend_unavailable	查询 Token 用量失败，详细原因由 message 返回
503	backend_unavailable	Token 用量后端未配置

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

查询最近请求用量明细

功能介绍

分页查询授权范围内的模型网关请求明细，包括调用身份、模型、请求类型、HTTP 状态码和 Token 数量。

访问要求：有效 Token。查询范围与 Token 用量概览接口一致。

URI

GET /api/v1/tenants/current/usage/recent

查询参数

参数	类型	必选	描述
start	string	否	开始时间，RFC3339 或 YYYY-MM-DD；包含该时刻
end	string	否	结束时间，RFC3339 或 YYYY-MM-DD；不包含该时刻
limit	integer	否	兼容的每页数量参数，必须为正整数；page_size 优先
page	integer	否	请求明细页码，从 1 开始，缺省为 1
page_size	integer	否	请求明细每页数量，必须为正整数，缺省为 limit 或 50，最大为 200
apiKeyId	string	否	消费者 ID 精确筛选；字段名为历史兼容名称
domainId	string	否	部门 ID 精确筛选
projectId	string	否	项目 ID 精确筛选
userId	string	否	消费者创建者用户 ID 精确筛选
model	string	否	对外模型名称精确筛选
domainLike	string	否	调用方可见部门名称的模糊筛选
projectLike	string	否	调用方可见项目名称的模糊筛选
userLike	string	否	消费者创建者名称的模糊筛选，不区分大小写
modelLike	string	否	对外模型名称的模糊筛选，不区分大小写
apiKeyName	string	否	消费者名称的模糊筛选，不区分大小写；字段名为历史兼容名称
host	string	否	路由域名精确筛选
hostLike	string	否	路由域名模糊筛选，不区分大小写
requestType	string	否	请求类型精确筛选
status	integer	否	HTTP 响应状态码精确筛选，必须为正整数
eventTime	string	否	按北京时间自然日筛选，格式为 YYYY-MM-DD
sortField	string	否	排序字段；支持 eventTime、totalTokens、promptTokens、completionTokens、cacheHitTokens、status、requestId、domainId、projectId、userId、userName、apiKeyName、consumerId、keyId、planId、model、host、requestType；缺省为 eventTime
sortValue	string	否	排序方向：ascend 或 descend，缺省为 descend

请求消息

无请求体。

响应消息

参数	参数类型	描述
start	string(date-time)	实际查询开始时间，RFC3339
end	string(date-time)	实际查询结束时间，RFC3339
recent	array	请求明细列表
recent[].requestId	string	网关请求 ID
recent[].domainId	string	部门 ID
recent[].domainName	string	部门名称
recent[].projectId	string	项目 ID
recent[].projectName	string	项目名称
recent[].userId	string	消费者创建者用户 ID
recent[].userName	string	消费者创建者名称
recent[].apiKeyName	string	消费者名称；字段名为历史兼容名称
recent[].consumerId	string	消费者 ID
recent[].keyId	string	本次请求使用的 API Key 标识，对应签发响应中的 keyId，不是 API Key 资源 ID
recent[].planId	string	请求发生时关联的套餐 ID
recent[].model	string	对外模型名称
recent[].host	string	路由域名
recent[].requestType	string	请求类型
recent[].promptTokens	int64	输入 Token 数
recent[].completionTokens	int64	输出 Token 数
recent[].totalTokens	int64	Token 总数
recent[].cacheHitTokens	int64 / null	缓存命中 Token 数；上游未提供时为 null
recent[].status	integer	HTTP 响应状态码
recent[].eventTime	string(date-time)	请求发生时间，RFC3339
recentTotal	int64	匹配的请求明细总数
recentPage	integer	请求明细页码
recentPageSize	integer	请求明细每页数量
sortField	string	实际使用的排序字段
sortValue	string	实际使用的排序方向：ascend 或 descend

请求示例

GET https://{endpoint}/api/v1/tenants/current/usage/recent?start=2026-09-15&end=2026-09-22&page=1&page_size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "start": "2026-09-15T00:00:00Z",
  "end": "2026-09-22T00:00:00Z",
  "recent": [
    {
      "requestId": "req-a1b2c3d4",
      "domainId": "domain-a1b2c3d4",
      "domainName": "研发部门",
      "projectId": "project-a1b2c3d4",
      "projectName": "生产项目",
      "userId": "user-a1b2c3d4",
      "userName": "示例用户",
      "apiKeyName": "生产应用",
      "consumerId": "con-a1b2c3d4e5f6",
      "keyId": "key-a1b2c3d4e5f6",
      "planId": "plan-a1b2c3d4",
      "model": "qwen2.5-72b",
      "host": "api.example.com",
      "requestType": "ai_chat",
      "promptTokens": 2000,
      "completionTokens": 500,
      "totalTokens": 2500,
      "cacheHitTokens": 800,
      "status": 200,
      "eventTime": "2026-09-21T08:30:00Z"
    }
  ],
  "recentTotal": 120,
  "recentPage": 1,
  "recentPageSize": 20,
  "sortField": "eventTime",
  "sortValue": "descend"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_query	时间、分页、状态码、排序方向或排序字段无效，详细原因由 message 返回
401	unauthorized	authentication required
502	backend_unavailable	查询请求用量明细失败，详细原因由 message 返回
503	backend_unavailable	Token 用量后端未配置

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

查询模型每日用量趋势

功能介绍

查询指定模型在授权范围内的每日请求数和 Token 用量。日期按北京时间划分，只返回存在用量记录的日期，不自动补充零值日期。

访问要求：有效 Token。查询范围与 Token 用量概览接口一致。

URI

GET /api/v1/tenants/current/usage/model-daily

查询参数

参数	类型	必选	描述
model	string	是	对外模型名称，精确匹配
start	string	否	开始时间，RFC3339 或 YYYY-MM-DD；包含该时刻
end	string	否	结束时间，RFC3339 或 YYYY-MM-DD；不包含该时刻
apiKeyId	string	否	消费者 ID 精确筛选；字段名为历史兼容名称
domainId	string	否	部门 ID 精确筛选
projectId	string	否	项目 ID 精确筛选
userId	string	否	消费者创建者用户 ID 精确筛选
domainLike	string	否	调用方可见部门名称的模糊筛选
projectLike	string	否	调用方可见项目名称的模糊筛选
userLike	string	否	消费者创建者名称的模糊筛选，不区分大小写
apiKeyName	string	否	消费者名称的模糊筛选，不区分大小写；字段名为历史兼容名称
host	string	否	路由域名精确筛选
hostLike	string	否	路由域名模糊筛选，不区分大小写
requestType	string	否	请求类型精确筛选
status	integer	否	HTTP 响应状态码精确筛选，必须为正整数
eventTime	string	否	按北京时间自然日进一步筛选，格式为 YYYY-MM-DD

请求消息

无请求体。

响应消息

参数	参数类型	描述
start	string(date-time)	实际查询开始时间，RFC3339
end	string(date-time)	实际查询结束时间，RFC3339
model	string	对外模型名称
series	array	按北京时间自然日升序排列的用量数据，只包含存在记录的日期
series[].date	string	日期，格式为 YYYY-MM-DD
series[].requestCount	int64	当日请求数
series[].promptTokens	int64	当日输入 Token 数
series[].cacheHitTokens	int64	当日缓存命中 Token 数
series[].completionTokens	int64	当日输出 Token 数
series[].totalTokens	int64	当日 Token 总数

请求示例

GET https://{endpoint}/api/v1/tenants/current/usage/model-daily?model=qwen2.5-72b&start=2026-09-15&end=2026-09-22
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "start": "2026-09-15T00:00:00Z",
  "end": "2026-09-22T00:00:00Z",
  "model": "qwen2.5-72b",
  "series": [
    {
      "date": "2026-09-20",
      "requestCount": 45,
      "promptTokens": 90000,
      "cacheHitTokens": 30000,
      "completionTokens": 22000,
      "totalTokens": 112000
    },
    {
      "date": "2026-09-21",
      "requestCount": 75,
      "promptTokens": 150000,
      "cacheHitTokens": 50000,
      "completionTokens": 38000,
      "totalTokens": 188000
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_query	model 缺失，或时间、状态码等查询参数无效，详细原因由 message 返回
401	unauthorized	authentication required
502	backend_unavailable	查询模型每日用量失败，详细原因由 message 返回
503	backend_unavailable	Token 用量后端未配置

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。