查询单次请求消耗

按请求 ID(响应头 X-Request-Id 的值,REQ- 开头)查询该次请求的实际消耗:token 用量与费用。适用于任务完成后回查单次请求的真实计费,例如视频生成等异步任务的结算核对。

一次请求如果触发了供应商切换,会产生多条记录:失败的尝试已被作废(status 为 upstream_failed、费用为 0),最终成功的那条为 billed。全部返回,按时间升序排列。

鉴权

在请求头携带 API Key:

Authorization: Bearer sk_live_YOUR_API_KEY

接口

GET/api/business/v1/customer/request-usage

查询单次请求消耗

按请求 ID(响应头 X-Request-Id 的值,REQ- 开头)返回该次请求的实际消耗 (token 用量与费用),适用于异步任务结算核对。一次请求在供应商间切换时会产生 多条记录:失败尝试已作废(upstream_failed,费用 0),最终成功一条为 billed, 按创建时间升序返回。只能查询属于该 API Key 组织的请求,否则 404。

Bearer API Key请求头使用 Authorization: Bearer sk_live_...,也支持 x-api-key。

请求结构

下方内容用于确认方法、地址和鉴权方式,属于 HTTP 结构片段,不是可独立执行示例。

HTTP
GET https://www.silvamux.com/api/business/v1/customer/request-usage
Authorization: Bearer $SILVAMUX_API_KEY

请求参数

参数类型与位置必填说明
request_idstring · query是响应头 X-Request-Id 的值(REQ- 开头)。

响应

200该请求产生的全部计费记录。

application/json · CustomerRequestUsageResponse

字段类型说明
ledgersarray<CustomerRequestUsageEntry>该请求产生的全部计费记录,按创建时间升序。
ledgers.cost_pointsstring折后实际扣费(points)。
ledgers.created_atstring (date-time)记录创建时间(RFC3339)。
ledgers.first_token_latency_msinteger (int64)首 token 延迟(ms,流式请求;0 表示未记录)。
ledgers.generated_artifactsinteger (int64)异步任务产物数(视频/图片)。
ledgers.is_streamboolean是否流式请求。
ledgers.original_coststring折前费用(points)。
ledgers.project_namestring项目名。
ledgers.request_modelstring请求时填写的模型名。
ledgers.statusstring (billed | upstream_failed | pending)billed 已计费 / upstream_failed 上游失败已作废(费用 0)/ pending 待结算。
ledgers.tokensCustomerRequestUsageTokens单条计费记录的 token 用量明细。
ledgers.tokens.billable_prompt_tokensinteger (int64)计费输入 token(prompt + cache creation)。
ledgers.tokens.cached_tokensinteger (int64)缓存读 token。
ledgers.tokens.completion_tokensinteger (int64)输出 token。
ledgers.tokens.prompt_tokensinteger (int64)输入 token(未命中缓存)。
ledgers.tokens.total_tokensinteger (int64)总 token。
ledgers.total_latency_msinteger (int64)总耗时(ms;0 表示未记录)。
request_idstring查询的请求 ID。

defaultRFC 7807 problem+json 错误(Business API 形态)。

application/problem+json · BusinessError

字段类型说明
detailstring错误详情。
errorsarray<object>字段级错误明细(422 校验失败时返回)。
errors.locationstring出错位置(如 query.request_id)。
errors.messagestring错误信息。
errors.valueany出错字段的值。
instancestring本次错误出现的 URI。
statusintegerHTTP 状态码。
titlestring错误摘要。
typestring错误类型标识(含错误码)。

参数

  • request_id:必填,响应头 X-Request-Id 的值(REQ- 开头)。
  • 只能查询属于该 API Key 所属组织的请求,否则返回 404。

示例

curl "https://www.silvamux.com/api/business/v1/customer/request-usage?request_id=REQ-01M2JBYGGVY77KPRWNZFDFTWZR" \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"

响应:

{
  "request_id": "REQ-01M2JBYGGVY77KPRWNZFDFTWZR",
  "ledgers": [
    {
      "request_model": "deepseek-v4-pro",
      "project_name": "Default Project",
      "status": "billed",
      "tokens": {
        "prompt_tokens": 85,
        "cached_tokens": 0,
        "billable_prompt_tokens": 85,
        "completion_tokens": 10,
        "total_tokens": 95
      },
      "generated_artifacts": 0,
      "is_stream": false,
      "first_token_latency_ms": 0,
      "total_latency_ms": 1358,
      "original_cost": "0.001035",
      "cost_points": "0.001035",
      "created_at": "2026-09-15T11:06:32.861800Z"
    }
  ]
}
字段说明
request_id查询的请求 ID
ledgers该请求产生的全部计费记录,按时间升序
ledgers[].request_model请求时填写的模型名
ledgers[].statusbilled(已计费)/ upstream_failed(上游失败已作废,费用 0)/ pending(待结算)
ledgers[].tokenstoken 用量明细
ledgers[].generated_artifacts异步任务产物数(视频/图片)
ledgers[].original_cost折前费用
ledgers[].cost_points折后实际扣费

错误处理

HTTP 状态错误码说明
401INVALID_TOKENAPI Key 缺失或无效
404REQUEST_USAGE_NOT_FOUND请求 ID 不存在,或不属于该 API Key 的组织
422—request_id 参数缺失