Cubicspaces API

简体中文

English

简体中文

English

Appearance

日志查询与导出 ​

企业客户接入 /getDailyList 和 /getDailySummary 时，请直接阅读正式账单 API（v2.2）。该独立文档已按客户账单规范整理，本页主要介绍实时用量与日志接口。

查询调用日志 ​

你可以通过日志接口查看每次请求的模型、耗时、Token 消耗和状态码，用于排查线上问题或复盘使用情况。

http
GET /api/log/self?start_timestamp=1711929600&end_timestamp=1713830400

按日查看用量 ​

按日用量接口适合对接内部报表、财务对账或客户自助账单系统。接口按日期汇总成功消费和退款记录，返回请求数、Token 用量、原始额度 quota，以及按当前站点额度展示配置换算后的金额字段。

接口信息 ​

http
GET /api/usage/daily
Authorization: Bearer YOUR_BILLING_READ_TOKEN

鉴权方式 ​

推荐对外接入使用账单只读令牌，令牌格式为 bill-...。用户可在控制台「个人设置」的「安全设置」中生成或重置账单只读令牌。一个用户只有一个账单只读令牌，重置后旧令牌立即失效。

账单只读令牌只能查询账单数据，不能调用 /v1/models、/v1/chat/completions 等模型接口。

企业主账号生成的同一个 bill-... 账单只读令牌，还可以调用企业聚合用量接口。该权限只能读取所属企业的子账号账单，不授予模型调用、子账号管理或 API Key 管理权限。

也支持使用普通 API Key 查询当前 API Key 自己的日用量：

http
GET /api/usage/daily?start_timestamp=1711929600&end_timestamp=1713830400&timezone_offset=0
Authorization: Bearer YOUR_API_KEY

使用账单只读令牌查询用户整体日账单：

http
GET /api/usage/daily?scope=user&start_timestamp=1711929600&end_timestamp=1713830400&timezone_offset=0
Authorization: Bearer YOUR_BILLING_READ_TOKEN

使用账单只读令牌查询用户下某个 API Key 的日账单：

http
GET /api/usage/daily?scope=token&token_id=28&start_timestamp=1711929600&end_timestamp=1713830400&timezone_offset=0
Authorization: Bearer YOUR_BILLING_READ_TOKEN

请求参数 ​

参数类型必填说明
start_timestampinteger否开始时间，秒级 Unix 时间戳；不传时默认最近 30 天
end_timestampinteger否结束时间，秒级 Unix 时间戳；不传时默认当前时间
timezone_offsetinteger否日期分桶使用的时区偏移秒数；不传时默认为 0（UTC）；允许范围为 -50400 到 50400
scopestring否查询范围，支持 user 或 token；账单只读令牌默认是 user，普通 API Key 只能使用 token
token_idinteger否查询某个 API Key 的日账单。使用账单只读令牌且 scope=token 时必填，且必须属于当前用户
model_namestring否按模型过滤，例如 gpt-4o-mini
group_by_modelboolean否设为 true 时按日期和模型拆分明细行；支持 true、1、yes

单次查询时间跨度不能超过 366 天。

时区规则 ​

按日用量接口和企业账单接口使用相同的时区规则：未传 timezone_offset 时默认使用 UTC（0）；为兼容已有调用，也可以传其他有效偏移量按指定时区划分日期和月份。start_timestamp、end_timestamp 仍为秒级 Unix 时间戳，时区参数只影响日、月周期边界。

响应示例 ​

json
{
  "success": true,
  "message": "",
  "data": {
    "object": "daily_usage",
    "scope": "user",
    "user_id": 1,
    "token_id": 0,
    "start_timestamp": 1711929600,
    "end_timestamp": 1713830400,
    "timezone": "UTC",
    "timezone_offset": 0,
    "billing_currency": "USD",
    "billing_unit_type": "currency",
    "billing_amount_is_invoice_amount": false,
    "billing_amount_basis": "current_site_display_config",
    "quota_per_unit": 500000,
    "data_status": "preliminary",
    "is_final": false,
    "generated_at": 1713830401,
    "data": [
      {
        "date": "2024-04-01",
        "start_timestamp": 1711900800,
        "end_timestamp": 1711987199,
        "request_count": 10,
        "prompt_tokens": 269,
        "completion_tokens": 11645,
        "token_used": 11914,
        "cache_read_tokens": 200,
        "cache_creation_tokens": 100,
        "cache_creation_5m_tokens": 80,
        "cache_creation_1h_tokens": 20,
        "quota": 657472,
        "billing_amount": 1.314944,
        "billing_currency": "USD",
        "usage_amount": 1.314944,
        "usage_unit": "USD"
      }
    ]
  }
}

如果传入 group_by_model=true，明细行会额外返回 model_name：

json
{
  "date": "2024-04-01",
  "model_name": "gpt-4o-mini",
  "request_count": 10,
  "prompt_tokens": 269,
  "completion_tokens": 11645,
  "token_used": 11914,
  "cache_read_tokens": 200,
  "cache_creation_tokens": 100,
  "cache_creation_5m_tokens": 80,
  "cache_creation_1h_tokens": 20,
  "quota": 657472,
  "billing_amount": 1.314944,
  "billing_currency": "USD",
  "usage_amount": 1.314944,
  "usage_unit": "USD"
}

字段说明 ​

字段说明
success请求是否成功
data.object固定为 daily_usage
data.scope实际查询范围，user 表示用户整体，token 表示单个 API Key
data.user_id当前用户 ID
data.token_id查询单个 API Key 时为对应令牌 ID；用户整体查询时为 0
data.timezone实际日期分桶时区；不传 timezone_offset 时为 UTC
data.billing_currency当前站点展示币种或额度单位，例如 USD、CNY、TOKENS
data.billing_unit_typecurrency 表示货币展示，quota 表示原始额度展示
data.billing_amount_is_invoice_amount固定为 false；该接口返回用量展示值，不是正式发票应付金额
data.billing_amount_basis当前为 current_site_display_config，表示按查询时的站点展示配置换算
data.quota_per_unit原始 quota 与标准金额单位的换算基数。例如为 500000 时，657472 quota = 1.314944 USD
data.data_status当前为 preliminary，表示接口返回实时聚合结果
data.is_final当前为 false；接口暂不提供正式出账承诺
data.generated_at本次响应生成时间，秒级 Unix 时间戳
data.data日账单明细数组
date账单日期，按 timezone_offset 分桶
request_count成功消费请求数；退款记录不会增加请求数
prompt_tokens输入 Token 合计
completion_tokens输出 Token 合计
token_usedprompt_tokens + completion_tokens
cache_read_tokens缓存读取 Token 合计
cache_creation_tokens缓存创建 Token 合计
cache_creation_5m_tokens其中 5 分钟缓存创建 Token 合计
cache_creation_1h_tokens其中 1 小时缓存创建 Token 合计
quota平台原始额度用量净值，消费为正，退款为负
billing_amount按当前站点额度展示配置换算后的金额或额度值
billing_currency当前明细行的币种或额度单位
usage_amount与 billing_amount 相同的明确语义别名，表示用量展示值
usage_unit与 billing_currency 相同的明确语义别名

金额换算 ​

quota 是平台内部用于精确计费和对账的原始额度值。对外展示时建议直接使用接口返回的 billing_amount 和 billing_currency，不要在客户端自行猜测汇率或换算规则。

当站点使用默认 USD 展示时：

text
billing_amount = quota / quota_per_unit

例如 quota_per_unit = 500000，则 21301158 quota = 42.602316 USD。

如果站点配置为人民币、自定义币种或 Token 展示，接口会按照服务端当前配置返回对应的 billing_amount 和 billing_currency。

billing_amount 是用量展示值，不是最终发票税前应付金额。税费、合同调整、最低消费和其他发票项目不在此接口中体现。

按当前站点配置，接口返回的 billing_currency 和 usage_unit 均为 USD，不会返回 TOKENS。只有服务端主动将账单展示模式改为 Token/额度模式后，才可能返回 TOKENS；目前未启用该配置。实际 Token 数请读取 prompt_tokens、completion_tokens 和 token_used。

当 billing_currency 为 TOKENS 时，billing_amount 与 quota 相同。这里的 TOKENS 表示平台原始额度单位，不是 ISO 货币，也不保证等于 token_used；真实输入、输出 Token 数应读取 prompt_tokens、completion_tokens 和 token_used。

历史用量不因后续模型调价重新计价。

正式账单明细接口（v2.2） ​

需要按“令牌 × 账单日 × 模型 × Token 类型”核对明细，或按账号查看每日汇总时，请使用正式账单接口。它与上面的实时用量接口并存，不会替换现有接口：

可下载 OpenAPI 3.0 规范，直接导入 Apifox、Postman、Swagger UI、YApi 或 Insomnia。

http
GET /getDailyList?startDate=2026-07-01&endDate=2026-07-23&pageSize=100&pageNum=1
GET /getDailySummary?startDate=2026-07-01&endDate=2026-07-23&pageSize=31&pageNum=1
Authorization: Bearer YOUR_BILLING_READ_TOKEN

两个接口共用企业主账号的 bill-... 账单只读令牌。普通模型 API Key、个人账号或企业子账号的账单令牌不能调用。响应统一使用：

json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "rows": []
  }
}

data.provider 是可选的模型/推理供应商字段。当前版本无法在混合模型账单中可靠、无歧义地确定一个统一供应商，因此省略该 key；不会返回空字符串，也不会用 cubicspace 代替模型供应商。

成功响应中的 data.total 始终是满足查询条件的总记录数，与当前页返回多少条无关。查询条件完全无数据时返回 total: 0 和 rows: []；页码超过最后一页时仍返回真实 total，但 rows 为空。

请求参数 ​

参数必填说明
startDate是开始账单日，格式 yyyy-MM-dd
endDate是结束账单日，格式 yyyy-MM-dd
userId否企业主账号 ID 表示查询其全部账号；也可传直属账号 ID 精确过滤
userName否企业主账号用户名表示查询其全部账号；也可传直属账号用户名精确过滤
pageSize是正整数；明细接口最大 100，汇总接口最大 400，超过时按最大值处理
pageNum是从 1 开始的正整数

/getDailyList 的日期跨度最多 92 天；/getDailySummary 最多 366 天。

/getDailyList 响应中的 account 返回正式出账时保存的令牌（API Key）名称。同一直属账号下的多个令牌会分别出现在各自的明细行中；历史明细没有令牌名称时，依次回退为账号用户名和账号标识。userId 与 userName 仍按企业账号过滤。/getDailySummary 不按令牌拆分，其 account 仍为账号用户名或账号标识。

明细响应 ​

/getDailyList 每一行的唯一粒度是：

text
billDay × API Key × modelName × tokenType × currency × entryType

同一个模型会按 Token 类型拆成多行。例如 claude-opus-4-6 可以分别返回文本输入、文本输出、缓存创建 5 分钟、缓存创建 1 小时和缓存读取统计：

json
{
  "billMonth": "202607",
  "billDay": "2026-07-22",
  "billingDateTimezone": "utc+0",
  "account": "key-production-a",
  "modelType": "claude",
  "modelName": "claude-opus-4-6",
  "tokenType": "cacheCreationTokens5m",
  "tokenCount": "50000",
  "tokenUnit": "piece",
  "currency": "USD",
  "subtotalBeforeTax": "0.18000000",
  "subtotalAfterDiscount": "0.16200000",
  "totalAmountAfterTax": "0.16200000",
  "discountDetail": {
    "type": "contract",
    "rate": "0.90000000",
    "amount": "0.01800000"
  }
}

支持的 tokenType 包括：

  • textInputTokens、textOutputTokens
  • imageInputTokens、imageOutputTokens
  • videoInputTokens、videoOutputTokens
  • audioInputTokens、audioOutputTokens
  • cacheCreationTokens5m、cacheCreationTokens1h、cacheTokens
  • reasoningTokens

各模型的真实用量会在消费日志写入时统一归一化为文本、图片、视频、音频和缓存等独立字段；异步任务按模型所属模态记录，不会把视频、音频或图片用量统一写成文本 Token。同一模型只会为实际存在的非零 Token 类型生成对应明细行。

没有对应上游明细的 Token 类型不会凭空产生数量。缓存创建存在一项历史兼容规则：如果日志只有缓存创建总数，或者总数大于已记录的 5m 与 1h 之和，未拆分的正差额归入 cacheCreationTokens5m；cacheCreationTokens1h 只使用明确记录的 1h 数量。如果拆分合计大于总数，则保留明确记录的拆分值，不做负向扣减。固定价格但上游没有 Token 数的服务可能返回 tokenCount: "0"，金额仍按实际落账记录保留。

当前版本不返回可选的 price 字段。账单金额以 subtotalBeforeTax、subtotalAfterDiscount 和 totalAmountAfterTax 为准；当 tokenCount 为 0 或金额由多种 Token 权重分摊时，不应自行反推单价。

正常消费默认省略 entryType，语义为 normal。退款返回 entryType: "refund"，其 Token 数和金额为负数，原消费行不会被覆盖。adjustment 是规范预留值，当前版本尚不生成调账条目。

金额、折扣与汇总 ​

  • subtotalBeforeTax：折扣前、税前金额。
  • subtotalAfterDiscount：应用企业合同折扣后的税前金额。
  • totalAmountAfterTax：折扣后、税后金额。
  • 金额始终使用 8 位小数字符串，避免浮点误差。
  • discountDetail.rate 直接返回正式出账时保存的合同折扣率。例如配置 86 折时固定返回 0.86000000，不会因 Token 类型金额分摊和 8 位小数舍入变成近似值。
  • 合同折扣按“企业主账号 × 服务类型”独立配置，并自动适用于该企业的全部直属子账号和该服务下的全部模型、Token 类型；直属账号也可以覆盖企业默认规则。例如 Claude 服务使用一个统一折扣，不区分输入、输出或缓存 Token。
  • 规则按生效日期追加版本，已经出账的历史账单不会被新规则重算。未配置合同折扣的企业或服务，subtotalBeforeTax 与 subtotalAfterDiscount 都按实际落账金额返回，不会把通用用户组倍率误报为合同折扣。

/getDailySummary 按 billDay × account × currency 返回账号级净额。每个汇总金额严格等于 /getDailyList 中属于该账号、对应日期和币种的全部令牌明细（包括退款）之和；由于明细的 account 显示令牌名称，客户端不能仅凭两个接口的 account 字符串直接关联。

每日汇总响应 ​

/getDailySummary 的 data.total 表示满足条件的“账单日 × 账号 × 币种”汇总行数。每行包含：

字段说明
billMonth账单月份，格式 yyyyMM
billDay账单日，格式 yyyy-MM-dd
billingDateTimezone固定为 utc+0
account正式出账时保存的实际账号标识
currencyISO 4217 货币代码，当前为 USD
subtotalBeforeTax当日折扣前、税前净额
subtotalAfterDiscount当日折扣后、税前净额
totalAmountAfterTax当日折扣后、税后净额
entryCount对应 /getDailyList 明细条数

请求：

http
GET /getDailySummary?startDate=2026-07-23&endDate=2026-07-23&userName=enterprise-subaccount&pageSize=10&pageNum=1
Authorization: Bearer bill-YOUR_BILLING_READ_TOKEN

返回：

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

分页、排序与零消费日 ​

  • /getDailyList 按 billDay DESC、modelName ASC、tokenType ASC、currency ASC 稳定排序；相同维度使用内部出账行顺序作为最终稳定键。
  • /getDailySummary 按 billDay DESC、账号内部稳定顺序、currency ASC 排序；不要依赖账号名称的字典序。
  • 明细分页粒度是一条 Token 类型明细，不是一天；建议从 pageNum=1 开始连续拉取，直到累计条数等于 data.total。
  • 超过最大 pageSize 时服务端自动按明细 100、汇总 400 截断，不返回错误。
  • 零消费日不生成明细或汇总行。

出账时间 ​

正式账单按 UTC+0 计费日期生成。系统在 UTC 每天 02:00（北京时间 10:00）完成上一 UTC 自然日出账；UTC 02:00 前最多返回到 D-2。自动出账覆盖所有处于启用状态的企业主账号；正式账单策略只配置折扣和税率，不作为是否出账的开关。未配置适用策略时，账单仍会生成，并按实际结算金额、折扣率 1.0 记录。系统使用数据库唯一标记保证多实例只成功出账一次，单个企业出账失败不会阻塞其他企业，并会按 5 分钟间隔重试。正式账单接口只返回已出账数据，未出账日期的数据不会生成或展示；查询范围同时包含已出账和未出账日期时，只返回其中已出账日期的明细与汇总。结算金额和当时的额度换算比例随消费日志保存；已经出账的行不因模型调价、全局换算比例、折扣规则变化或迟到日志重新生成，后续退款作为新日期的负数记录追加。

后台自动出账通过环境变量 BILLING_STATEMENT_FREEZE_ENABLED 控制（变量名为内部兼容标识）。未配置时默认开启；设为 false 后需要重启服务生效，并停止启动时和 UTC 每天 02:00 的后台出账任务。读取接口始终为只读，只查询已经出账的数据，不会补生成或触发任何日期出账。首次部署或调整合同策略时，可设置 BILLING_STATEMENT_FREEZE_ENABLED=false 停止生成；如还需同时关闭正式账单查询服务，再设置 BILLING_STATEMENT_SERVICE_AVAILABLE=false。完成表结构迁移、企业策略和 Billing Token 配置后，再按发布计划启用相应开关并重启服务。

当前版本不会在正式账单响应中返回 isFinal 或 latestAvailableBillDay。请求尚未出账的当天或 D-1 时可能得到 code: 0、total: 0、rows: []；该空数组不能证明该日已经出账且确实为零消费。接入方必须按 UTC 02:00 的出账规则限制 endDate，并预留重试。

正式账单错误响应 ​

正式账单接口的错误结构与实时用量接口不同，固定使用：

json
{
  "code": 40001,
  "message": "startDate is invalid, expected format: yyyy-MM-dd",
  "data": {}
}
HTTPcode场景
40040001日期、分页或 userId 格式错误
40040002缺少 startDate、endDate、pageSize 或 pageNum
40040003日期倒置，或明细超过 92 天、汇总超过 366 天
40140100Token 缺失、无效、过期、已重置、所属账号已禁用，或误用普通模型 API Key
40340300Token 有效且所属账号已启用，但该账号不是企业主账号
42942900当前企业主账号超过正式账单接口的请求频率限制
50050000出账或查询发生服务端/数据库错误
50350300系统处于维护模式，或正式账单服务暂时不可用

正式账单接口在账单令牌鉴权成功后按企业主账号独立限流，不按来源 IP 共享额度；默认阈值为每个企业主账号每 60 秒 120 次。超过限制时，响应头 Retry-After 返回至少需要等待的秒数。阈值可能随部署配置调整；批量拉取仍应使用允许的最大 pageSize，并按 Retry-After 延迟重试。

企业主账号聚合用量 ​

企业主账号可以使用自己的账单只读令牌拉取全部直属企业子账号的账单：

http
GET /api/usage/enterprise?start_timestamp=1711929600&end_timestamp=1713830400&granularity=daily&timezone_offset=0
Authorization: Bearer YOUR_BILLING_READ_TOKEN

granularity 支持 daily 和 monthly，默认值为 daily。企业账单与按日用量接口使用相同的时区规则：不传 timezone_offset 时默认为 UTC（0），也可以传入其他偏移量改变日、月周期边界。响应包含所有子账号的 quota、请求数、输入/输出 Token、模型类别汇总，以及与日用量接口相同的用量展示字段和完整性元数据。

参数类型必填说明
start_timestampinteger否开始时间，秒级 Unix 时间戳；默认从当前时间向前一个月
end_timestampinteger否结束时间，秒级 Unix 时间戳；默认当前时间
granularitystring否daily 或 monthly；默认为 daily
timezone_offsetinteger否日、月周期分桶使用的时区偏移秒数；默认 0（UTC），允许范围为 -50400 到 50400

响应示例：

json
{
  "success": true,
  "message": "",
  "data": {
    "object": "enterprise_usage",
    "total_quota": 750000,
    "prompt_tokens": 1000,
    "completion_tokens": 500,
    "token_used": 1500,
    "cache_read_tokens": 200,
    "cache_creation_tokens": 100,
    "cache_creation_5m_tokens": 80,
    "cache_creation_1h_tokens": 20,
    "billing_amount": 1.5,
    "billing_currency": "USD",
    "usage_amount": 1.5,
    "usage_unit": "USD",
    "billing_amount_is_invoice_amount": false,
    "billing_amount_basis": "current_site_display_config",
    "timezone": "UTC",
    "timezone_offset": 0,
    "data_status": "preliminary",
    "is_final": false,
    "items": [
      {
        "sub_user_id": 2,
        "username": "team-a",
        "display_name": "Team A",
        "total_quota": 750000,
        "prompt_tokens": 1000,
        "completion_tokens": 500,
        "token_used": 1500,
        "cache_read_tokens": 200,
        "cache_creation_tokens": 100,
        "cache_creation_5m_tokens": 80,
        "cache_creation_1h_tokens": 20,
        "usage_amount": 1.5,
        "usage_unit": "USD",
        "buckets": [
          {
            "period": "2026-07-01",
            "period_start": 1782835200,
            "quota": 750000,
            "request_count": 10,
            "prompt_tokens": 1000,
            "completion_tokens": 500,
            "token_used": 1500,
            "cache_read_tokens": 200,
            "cache_creation_tokens": 100,
            "cache_creation_5m_tokens": 80,
            "cache_creation_1h_tokens": 20,
            "usage_amount": 1.5,
            "usage_unit": "USD",
            "model_family_quotas": {
              "gpt": 500000,
              "claude": 250000
            }
          }
        ]
      }
    ]
  }
}

只有企业主账号的 bill-... 令牌可以调用该接口。个人账号或企业子账号令牌返回 403，普通模型 API Key 返回 401。

企业接口在顶层、每个子账号和每个日/月分桶中均返回 prompt_tokens、completion_tokens 和 token_used；其中 token_used = prompt_tokens + completion_tokens。

按日用量和企业账单接口还会返回 cache_read_tokens、cache_creation_tokens、cache_creation_5m_tokens 和 cache_creation_1h_tokens。如果模型或上游没有提供对应缓存明细，字段返回 0；cache_creation_5m_tokens 与 cache_creation_1h_tokens 是缓存创建总量的分项，不应与 cache_creation_tokens 重复相加。

数据完整性与 D-1 ​

/api/usage/daily 和 /api/usage/enterprise 仍是实时聚合接口，响应通过 data_status=preliminary 和 is_final=false 标识尚未正式出账的数据。需要固定 D-1、不可重刷的正式账单时，应使用 /getDailyList 和 /getDailySummary；正式账单在 UTC 每天 02:00 完成上一 UTC 自然日出账。

错误响应 ​

json
{
  "success": false,
  "message": "token invalid"
}

常见错误包括：

HTTP 状态码场景
401未提供令牌、令牌无效、令牌已过期、账单只读令牌已被重置
403用户被禁用
500服务端或数据库异常

参数错误也会返回 success=false，例如 start_timestamp 大于 end_timestamp、查询跨度超过 366 天，或 timezone_offset 超出范围。

接入建议 ​

  • 对外账单系统优先使用账单只读令牌，不要使用普通 API Key。
  • 服务端保存令牌时应按密钥处理，不要出现在前端页面源码、日志或公开文档中。
  • 拉取月账单时建议传入明确的 start_timestamp、end_timestamp 和 timezone_offset，避免自然月边界偏移。
  • 对账时使用 quota 做精确校验，给用户展示时使用 billing_amount 和 billing_currency。

导出用量数据 ​

支持按模型、令牌和时间区间导出 CSV，便于和内部 BI、财务系统对账。日志查询与导出属于控制台管理接口，需要用户登录态；管理员可使用 /api/log/ 和 /api/log/export 查询或导出全量日志。

http
GET /api/log/self/export?start_timestamp=1711929600&end_timestamp=1713830400

推荐做法 ​

  • 为不同业务线拆分项目和 API Key
  • 定期导出月度用量数据
  • 对 429 和 5xx 请求单独做告警

Copyright © 2026-present Cubicspaces