账单 API

用调用模型的同一把 API Key，查询每次请求的费用、翻看请求记录、查看 Key 的剩余额度。

概览

接口	返回
`GET /v1/billing/requests`	请求记录（新的在前），含费用和 token 用量
`GET /v1/billing/requests/{id}`	单次请求，按 `x-token-share-request-id` 查询
`GET /v1/billing/balance`	Key 的额度和已用；CLI 管理 Key 还会返回账户余额

认证方式和 /v1 完全一样：Authorization: Bearer 或 x-api-key。能看到什么取决于 Key 的类型：

Key 类型	能看到	响应里的 `scope`
推理	只有这把 Key 自己发出的请求，以及它自己的额度	`key`
CLI 管理	账户下所有请求，以及账户余额	`account`

响应带 cache-control: private, no-store。金额单位均为美元。

GET /v1/billing/requests 按时间倒序返回请求。不传 since 和 until 时只查最近 24 小时，响应里的 range 会写明实际用的时间窗口。

curl "https://token-share.app/v1/billing/requests?since=2026-10-01&until=2026-10-07&page_size=100" \
  -H "Authorization: Bearer $TOKEN_SHARE_KEY"

字段	说明
`id`	请求 id，和响应头 `x-token-share-request-id` 的值相同。
`key_id`	发出这次请求的 Key。
`cost_usd`	实际扣费金额。未计费的请求为 `0`。
`payment_status`	`paid`：已从钱包扣款。`unpaid`：已计费，但钱包余额不够扣。`unbilled`：用量无法计量，未扣费。
`payment_source`	由哪个钱包支付：`balance`（充值余额）、`earned`（贡献收益）或 `promo`（活动赠送额度）。
`usage`	输入、输出、缓存读取、缓存写入的 token 数。
`total`、`total_cost_usd`	整个时间窗口内的请求数和总费用，不只是当前这一页。

GET /v1/billing/requests/{id} 的 id 就是任意 /v1 响应里的 x-token-share-request-id。返回字段与列表相同，另外还有：

字段	说明
`list_price_usd`	同样的用量按模型官方价计算的金额，用来对照折扣。
`failure_reason`	请求失败时，一个简短的机器可读原因。
`fallback_from_model`、`fallback_reason`	请求被切到其他线路时出现：你原本请求的模型和原因。此时 `model` 是实际服务并计价的那个。

curl https://token-share.app/v1/billing/requests/6f1c2a8e-3b4d-4f7a-9c1e-2d5b8a0f7e31 \
  -H "Authorization: Bearer $TOKEN_SHARE_KEY"

不存在的 id、属于其他账户的 id、以及（对推理 Key 而言）由其他 Key 发出的请求，都返回同样的 404 {"error": "not_found"}。响应刚结束时记录可能还没写入，也会返回 404，几秒后重试即可。

GET /v1/billing/balance 返回这把 Key 的额度和已用金额。Key 没有单独设上限时，limit_usd 和 remaining_usd 为 null。account 是账户可用余额，只返回给 CLI 管理 Key，推理 Key 拿到的是 null。

curl https://token-share.app/v1/billing/balance \
  -H "Authorization: Bearer $TOKEN_SHARE_KEY"