用量与计费开放接口

TeamoRouter 用量与计费接口用于查询单次模型请求的 Token 用量和费用、按时间范围汇总用量与账单，以及获取账户余额。

本文档描述接口约定，实际请以线上接口返回结果为准。

接口概览

接口 说明
GET /v1/billing/requests/{request_id} 查询单次请求的 Token 用量与账单
GET /v1/billing/costs 查询当前鉴权 API Key 在指定时间范围内的账单汇总
GET /v1/usage 查询当前鉴权 API Key 在指定时间范围内的 Token 用量汇总
GET /v1/billing/balance 查询当前账户余额

开始使用

请求地址

请使用 TeamoRouter 控制台中提供的 API Base URL。下文使用 $TEAMO_BASE_URL 表示该地址：

bash
export TEAMO_BASE_URL="https://teamorouter.com"

鉴权方式

在每个请求的 Authorization 请求头中携带 TeamoRouter API Key：

http
Authorization: Bearer sk-teamo-xxx

请妥善保管 API Key，不要将其写入前端代码、公开仓库或日志。示例中的 Key 和 ID 均为虚构数据。

查询单次请求的用量与账单

根据请求 ID 查询一次模型调用产生的 Token 用量和最终费用。

http
GET /v1/billing/requests/{request_id}

路径参数

参数 类型 必填 说明
request_id UUID string 是 调用模型时返回的请求 ID

请求示例

bash
curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

响应示例

json
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1784081234,
  "model": "gpt-5.4",
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "cached_write_tokens": 800,
    "cached_read_tokens": 200,
    "total_tokens": 2500
  },
  "amount": {
    "value": "0.012680",
    "currency": "USD"
  }
}

Token 字段说明

字段 说明
input_tokens 未命中缓存的输入 Token 数
output_tokens 模型生成的输出 Token 数
cached_write_tokens 写入提示词缓存的 Token 数
cached_read_tokens 从提示词缓存读取的 Token 数
total_tokens 上述 Token 数量之和

不适用或上游未提供的 Token 类型返回 0。

查询时间范围内的账单

查询当前鉴权 API Key 在指定时间范围内的账单汇总。简单版仅返回汇总数据，不返回逐请求明细。

http
GET /v1/billing/costs

查询参数

参数 类型 必填 说明
start_time integer 是 查询开始时间，包含该时间点
end_time integer 是 查询结束时间，不包含该时间点

查询时间范围最长为 90 天，超过限制将返回 400 invalid_request。

请求示例

bash
curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

响应示例

json
{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "total_amount": {
    "value": "1.280000",
    "currency": "USD"
  },
  "requests": 86
}

查询时间范围内的 Token 用量

查询当前鉴权 API Key 在指定时间范围内的 Token 用量汇总。

http
GET /v1/usage

查询参数

参数 类型 必填 说明
start_time integer 是 查询开始时间，包含该时间点
end_time integer 是 查询结束时间，不包含该时间点

查询时间范围最长为 90 天，超过限制将返回 400 invalid_request。

请求示例

bash
curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

响应示例

json
{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "usage": {
    "input_tokens": 120000,
    "output_tokens": 30000,
    "cached_write_tokens": 10000,
    "cached_read_tokens": 80000,
    "total_tokens": 240000
  },
  "requests": 86
}

查询账户余额

查询当前 API Key 所属账户的可用余额。

http
GET /v1/billing/balance

该接口无需查询参数，账户身份从 API Key 中识别。

请求示例

bash
curl "$TEAMO_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

响应示例

json
{
  "balance": {
    "value": "85.320000",
    "currency": "USD"
  }
}

错误处理

接口调用失败时，响应体包含稳定的错误码和便于排查的信息。

json
{
  "error": {
    "code": "invalid_request",
    "message": "end_time must be greater than start_time"
  }
}

常见错误码

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 时使用指数退避重试。
准备好了？三步即可开始登录控制台 · 购买额度 · 创建 API Key
获取 API Key查看定价
微信扫码加入交流群
遇到问题？微信扫码加入交流群
用量与计费开放接口 · 帮助文档