正式账单 API（v2.2）

本文档用于企业客户通过 API 拉取已出账的日账单明细与汇总数据。

明细接口：GET /getDailyList
汇总接口：GET /getDailySummary
鉴权方式：企业主账号的账单只读令牌
账单时区：UTC+0
出账规则：UTC 每日 02:00（北京时间 10:00）生成上一 UTC 自然日账单
数据范围：只返回已出账数据，未出账日期不展示

服务地址

环境	Base URL
正式环境	`https://cubicspaces.cloud`

鉴权

两个接口均使用企业主账号生成的 bill-... 账单只读令牌：

http

Authorization: Bearer bill-xxxxxxxxxxxxxxxx

该令牌只能读取账单，不能调用模型接口。普通模型 API Key、个人账号或企业子账号的账单令牌不能调用正式账单接口。

查询明细

http

GET /getDailyList

明细按以下粒度分别返回，不会把不同模型或不同 Token 类型合并成一行：

text

账单日 × 令牌 × 模型 × Token 类型 × 币种 × 账单条目类型

请求参数

参数	类型	必填	说明
`startDate`	string	是	开始账单日，格式 `yyyy-MM-dd`，包含当天
`endDate`	string	是	结束账单日，格式 `yyyy-MM-dd`，包含当天
`userId`	integer	否	账号 ID 过滤条件；企业主账号 ID 表示查询整个企业
`userName`	string	否	账号用户名过滤条件；企业主账号用户名表示查询整个企业
`pageSize`	integer	是	每页条数，最大 100
`pageNum`	integer	是	页码，从 1 开始

单次查询最多包含 92 个账单日。

请求示例

bash

curl --request GET \
  'https://cubicspaces.cloud/getDailyList?startDate=2026-07-22&endDate=2026-07-23&pageSize=100&pageNum=1' \
  --header 'Authorization: Bearer bill-xxxxxxxxxxxxxxxx'

只查询一个直属账号时，可增加 userName：

bash

curl --request GET \
  'https://cubicspaces.cloud/getDailyList?startDate=2026-07-22&endDate=2026-07-23&userName=enterprise-subaccount&pageSize=100&pageNum=1' \
  --header 'Authorization: Bearer bill-xxxxxxxxxxxxxxxx'

返回示例

同一模型会按 Token 类型返回多行；多个模型会继续增加明细行：

json

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 3,
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-23",
        "billingDateTimezone": "utc+0",
        "account": "key-production-a",
        "modelType": "claude",
        "modelName": "claude-opus-4-6",
        "tokenType": "textInputTokens",
        "tokenCount": "1200000",
        "tokenUnit": "piece",
        "currency": "USD",
        "subtotalBeforeTax": "3.60000000",
        "subtotalAfterDiscount": "3.09600000",
        "totalAmountAfterTax": "3.09600000",
        "discountDetail": {
          "type": "contract",
          "rate": "0.86000000",
          "amount": "0.50400000"
        }
      },
      {
        "billMonth": "202607",
        "billDay": "2026-07-23",
        "billingDateTimezone": "utc+0",
        "account": "key-production-a",
        "modelType": "claude",
        "modelName": "claude-opus-4-6",
        "tokenType": "cacheCreationTokens1h",
        "tokenCount": "50000",
        "tokenUnit": "piece",
        "currency": "USD",
        "subtotalBeforeTax": "0.30000000",
        "subtotalAfterDiscount": "0.25800000",
        "totalAmountAfterTax": "0.25800000",
        "discountDetail": {
          "type": "contract",
          "rate": "0.86000000",
          "amount": "0.04200000"
        }
      },
      {
        "billMonth": "202607",
        "billDay": "2026-07-23",
        "billingDateTimezone": "utc+0",
        "account": "key-image-production",
        "modelType": "gemini",
        "modelName": "gemini-3.1-flash-image-preview",
        "tokenType": "imageOutputTokens",
        "tokenCount": "12",
        "tokenUnit": "piece",
        "currency": "USD",
        "subtotalBeforeTax": "0.48000000",
        "subtotalAfterDiscount": "0.48000000",
        "totalAmountAfterTax": "0.48000000"
      }
    ]
  }
}

明细字段

字段	类型	必返	说明
`billMonth`	string	是	目标账单日所属月份，格式 `yyyyMM`
`billDay`	string	是	目标账单日，格式 `yyyy-MM-dd`
`billingDateTimezone`	string	是	计费日期时区，固定为 `utc+0`
`account`	string	是	出账时保存的令牌（API Key）名称；历史明细没有令牌名称时依次回退为账号用户名和账号标识
`modelType`	string	是	模型分类，如 `claude`、`gemini`、`gpt`
`modelName`	string	是	完整模型名，如 `claude-opus-4-6`
`tokenType`	string	是	Token 或用量类型
`tokenCount`	string	是	对应类型的用量数量；退款为负数
`tokenUnit`	string	是	固定为 `piece`
`currency`	string	是	币种
`subtotalBeforeTax`	string	是	折扣前、税前金额，固定保留 8 位小数
`subtotalAfterDiscount`	string	是	折扣后、税前金额，固定保留 8 位小数
`totalAmountAfterTax`	string	是	折扣后、税后金额，固定保留 8 位小数
`entryType`	string	否	正常消费时省略；退款时为 `refund`
`discountDetail`	object	否	存在合同折扣时返回
`discountDetail.type`	string	是	当前为 `contract`
`discountDetail.rate`	string	是	出账时保存的折扣保留率，如 `0.86000000`
`discountDetail.amount`	string	是	本行折扣金额

data.provider 是可选字段，表示模型或推理供应商。无法可靠确定唯一供应商时直接省略，不返回空字符串，也不使用平台名称代替模型供应商。

当前版本不返回 price。金额核对以三个金额字段为准。

account 在明细接口中用于区分令牌。同一直属账号下的多个令牌会分别出现在各自的明细行中；请求参数 userId 和 userName 仍按企业账号过滤。/getDailySummary 不按令牌拆分，仍按账号汇总，因此汇总行的 account 仍为账号用户名或账号标识。

Token 类型

`tokenType`	说明
`textInputTokens`	文本输入 Token
`textOutputTokens`	文本输出 Token
`imageInputTokens`	图片输入用量
`imageOutputTokens`	图片输出用量
`videoInputTokens`	视频输入用量
`videoOutputTokens`	视频输出用量
`audioInputTokens`	音频输入用量
`audioOutputTokens`	音频输出用量
`cacheCreationTokens5m`	缓存创建 Token（5 分钟 TTL）
`cacheCreationTokens1h`	缓存创建 Token（1 小时 TTL）
`cacheTokens`	缓存命中 Token
`reasoningTokens`	推理 Token

接口只返回模型实际产生且可记录的用量类型，不会为所有模型强制补齐全部类型。没有对应明细的类型不返回。

查询每日汇总

http

GET /getDailySummary

汇总接口按以下粒度返回净额：

text

账单日 × 账号 × 币种

请求参数

参数与 /getDailyList 相同，但：

单次查询最多包含 366 个账单日；
pageSize 最大为 400。

请求示例

bash

curl --request GET \
  'https://cubicspaces.cloud/getDailySummary?startDate=2026-07-01&endDate=2026-07-23&pageSize=100&pageNum=1' \
  --header 'Authorization: Bearer bill-xxxxxxxxxxxxxxxx'

返回示例

json

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "rows": [
      {
        "billMonth": "202607",
        "billDay": "2026-07-23",
        "billingDateTimezone": "utc+0",
        "account": "enterprise-subaccount",
        "currency": "USD",
        "subtotalBeforeTax": "4.38000000",
        "subtotalAfterDiscount": "3.83400000",
        "totalAmountAfterTax": "3.83400000",
        "entryCount": 3
      }
    ]
  }
}

entryCount 是该汇总行对应的 /getDailyList 明细行数。三个汇总金额分别等于对应明细金额之和，退款按负数参与汇总。

出账与数据规则

账单日期统一使用 UTC+0，不支持通过请求参数切换时区。
UTC 每日 02:00（北京时间 10:00）生成上一 UTC 自然日账单，满足 T+1、UTC 00:00 后可查询的要求。
查询范围可以包含未出账日期，但响应只展示其中已经出账的日期。
无匹配数据时返回 total: 0、rows: []。
页码超过最后一页时，total 保持真实总数，rows 返回空数组。
历史账单使用出账时保存的模型分类、折扣和结算金额；后续模型调价不会重新计算历史账单。

分页与排序

data.total 是满足条件的总记录数，不是当前页条数。
明细默认按账单日、账号、模型、Token 类型稳定排序。
汇总默认按账单日、账号稳定排序。

限流

接口按企业主账号限流，默认每 60 秒最多 120 次请求，不按来源 IP 计数。

超过限制时返回 HTTP 429，并通过响应头 Retry-After 告知最少等待秒数。

状态码

HTTP 状态码	说明
`200`	请求成功
`400`	参数缺失、日期格式错误或查询范围超限
`401`	未提供令牌，或令牌无效、过期、已重置、类型错误，或令牌所属账号已禁用
`403`	有效令牌不属于企业主账号
`429`	超过企业账号限流阈值；按 `Retry-After` 重试
`500`	服务器或数据库内部错误
`503`	系统维护或正式账单服务暂不可用

错误响应统一使用：

json

{
  "code": 40001,
  "message": "startDate is invalid, expected format: yyyy-MM-dd",
  "data": {}
}

接入建议

使用 /getDailySummary 拉取每日应付汇总。
使用 /getDailyList 拉取模型和 Token 类型明细进行核对。
保存 billDay + account + modelName + tokenType + currency + entryType 作为明细幂等键；正常消费未返回 entryType 时按 normal 处理。
金额字段按十进制定点数处理，不要使用二进制浮点数重新计算。
以服务端返回的金额和折扣为准，不要根据当前模型价格反推或重算历史账单。

正式账单 API（v2.2） ​

服务地址 ​

鉴权 ​

查询明细 ​

请求参数 ​

请求示例 ​

返回示例 ​

明细字段 ​

Token 类型 ​

查询每日汇总 ​

请求参数 ​

请求示例 ​

返回示例 ​

出账与数据规则 ​

分页与排序 ​

限流 ​

状态码 ​

接入建议 ​

正式账单 API（v2.2）

服务地址

鉴权

查询明细

请求参数

请求示例

返回示例

明细字段

Token 类型

查询每日汇总

请求参数

请求示例

返回示例

出账与数据规则

分页与排序

限流

状态码

接入建议