用量与计费开放接口 | CA云上创造 API 文档

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

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

接口概览

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

开始使用

请求地址

请使用 CA云上创造控制台中提供的 API Base URL。下文使用 $CA_BASE_URL 表示该地址：

bash

export CA_BASE_URL="https://caapi.top"

鉴权方式

在每个请求的 Authorization 请求头中携带 CA云上创造 API Key：

http

Authorization: Bearer sk-xxx

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

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

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

http

GET /v1/billing/requests/{request_id}

路径参数

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

请求示例

bash

curl "$CA_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $CA_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 "$CA_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $CA_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 "$CA_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $CA_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 "$CA_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $CA_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 时使用指数退避重试。

共 50 篇文档。文中出现的模型名与价格以模型广场的实时数据为准。