用量与计费开放接口
Syon 用量与计费接口用于查询单次模型请求的 Token 用量和费用、按时间范围汇总用量与账单，以及获取账户余额。 本文档描述接口约定，实际请以线上接口返回结果为准。接口概览
| 接口 |说明 |GET /v1/billing/requests/\{request_id\}
|查询单次请求的 Token 用量与账单
|
|GET /v1/billing/costs
|查询当前鉴权 API Key 在指定时间范围内的账单汇总
|
|GET /v1/usage
|查询当前鉴权 API Key 在指定时间范围内的 Token 用量汇总
|
|GET /v1/billing/balance
|查询当前账户余额
|
开始使用
请求地址
请使用 Syon 控制台中提供的 API Base URL。下文使用$SYON_BASE_URL 表示该地址：
鉴权方式
在每个请求的Authorization 请求头中携带 Syon API Key：
查询单次请求的用量与账单
根据请求 ID 查询一次模型调用产生的 Token 用量和最终费用。路径参数
| 参数 |类型 |必填 |说明 |request_id
|UUID string
|是
|调用模型时返回的请求 ID
|
请求示例
响应示例
Token 字段说明
| 字段 |说明 |input_tokens
|未命中缓存的输入 Token 数
|
|output_tokens
|模型生成的输出 Token 数
|
|cached_write_tokens
|写入提示词缓存的 Token 数
|
|cached_read_tokens
|从提示词缓存读取的 Token 数
|
|total_tokens
|上述 Token 数量之和
|
不适用或上游未提供的 Token 类型返回 0。
查询时间范围内的账单
查询当前鉴权 API Key 在指定时间范围内的账单汇总。简单版仅返回汇总数据，不返回逐请求明细。查询参数
| 参数 |类型 |必填 |说明 |start_time
|integer
|是
|查询开始时间，包含该时间点
|
|end_time
|integer
|是
|查询结束时间，不包含该时间点
|
查询时间范围最长为 90 天，超过限制将返回 400 invalid_request。
请求示例
响应示例
查询时间范围内的 Token 用量
查询当前鉴权 API Key 在指定时间范围内的 Token 用量汇总。查询参数
| 参数 |类型 |必填 |说明 |start_time
|integer
|是
|查询开始时间，包含该时间点
|
|end_time
|integer
|是
|查询结束时间，不包含该时间点
|
查询时间范围最长为 90 天，超过限制将返回 400 invalid_request。
请求示例
响应示例
查询账户余额
查询当前 API Key 所属账户的可用余额。请求示例
响应示例
错误处理
接口调用失败时，响应体包含稳定的错误码和便于排查的信息。常见错误码
| HTTP 状态码 |error.type / error.code
|说明
|400
|invalid_request
|请求参数无效，例如时间范围错误
|
|401
|missing_auth_credential / 401
|未提供 API Key
|
|401
|invalid_api_key
|API Key 无效
|
|404
|not_found
|请求记录不存在，或当前 API Key 无权访问该记录
|
|429
|rate_limit_exceeded
|请求过于频繁，请稍后重试
|
|500
|internal_error
|服务内部错误
|
使用建议
-
对账时使用相同的
start_time和end_time，确保查询口径一致。 -
价格可能调整。历史账单以实际返回的
amount为准，不要使用当前价格表反推历史费用。 -
对查询接口设置合理的重试和超时策略；遇到
429或5xx时使用指数退避重试。