查询单次请求消耗

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

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

鉴权

在请求头携带 API Key:

Authorization: Bearer sk_live_YOUR_API_KEY

接口

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

Get actual usage for a single request

Return the ledgers (tokens + cost) produced by one gateway request, identified by the request_id query parameter (the X-Request-Id response header value, REQ-...). Fields match the dashboard ledger view. A request that failed over between providers produces multiple ledgers (voided attempts + the final billed one). API key only.

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

请求参数

参数类型与位置必填说明
Authorizationstring · headerBearer API Key (sk_live_...)
X-Organization-Idstring · headerNot required for API key auth
request_idstring · queryRequest ID from the X-Request-Id response header (REQ-...)

响应

200OK

application/json · CustomerRequestUsageResponse

字段类型必填说明
$schemastring (uri)A URL to the JSON Schema for this object.
ledgersarray<CustomerRequestUsageEntry>Ledgers produced by this request, ordered by created_at asc
ledgers.cost_pointsstringCost in points after discount
ledgers.created_atstring (date-time)Ledger creation time (RFC3339)
ledgers.first_token_latency_msinteger (int64)Time to first token in ms (streamed requests; 0 = unrecorded)
ledgers.generated_artifactsinteger (int64)Generated artifact count (video/image async tasks)
ledgers.is_streambooleanWhether the request was streamed
ledgers.original_coststringCost in points before discount
ledgers.project_namestringProject name
ledgers.request_modelstringModel name as supplied in the request
ledgers.statusstringLedger status (billed / upstream_failed / pending)
ledgers.tokensRequestTokens
ledgers.tokens.billable_prompt_tokensinteger (int64)Billable prompt tokens (prompt + cache creation)
ledgers.tokens.cached_tokensinteger (int64)Cache-read prompt tokens
ledgers.tokens.completion_tokensinteger (int64)Completion tokens
ledgers.tokens.prompt_tokensinteger (int64)Prompt tokens (uncached)
ledgers.tokens.total_tokensinteger (int64)Total tokens
ledgers.total_latency_msinteger (int64)Total request latency in ms (0 = unrecorded)
request_idstringGateway request ID (X-Request-Id response header)

defaultError

application/problem+json · ErrorModel

字段类型必填说明
$schemastring (uri)A URL to the JSON Schema for this object.
detailstringA human-readable explanation specific to this occurrence of the problem.
errorsarray<ErrorDetail>Optional list of individual error details
errors.locationstringWhere the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
errors.messagestringError message text
errors.valueanyThe value at the given location
instancestring (uri)A URI reference that identifies the specific occurrence of the problem.
statusinteger (int64)HTTP status code
titlestringA short, human-readable summary of the problem type. This value should not change between occurrences of the error.
typestring (uri)A URI reference to human-readable documentation for the error.;默认值:about:blank

参数

  • 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 的组织
422request_id 参数缺失