Venice计费

它解决什么问题

用 Venice 跑推理时，成本常常是一笔糊涂账：DIEM、捆绑额度、USD 余额分属不同池子，扣款顺序不透明；想找单次请求的扣费明细，或按模型、按 Key 统计谁花得多，往往得自己翻日志拼接。这个技能把账户级计费与分析收敛成三个只读端点，不需要自己解析交易流水。

核心能力与工作方式

• 余额查询 GET /billing/balance：返回 canConsume 标志、DIEM 与 USD 剩余量，以及当前 epoch 的 DIEM 配额上限（diemEpochAllocation），用 balances.diem / diemEpochAllocation 即可算出剩余比例。consumptionCurrency 告诉你此刻正在扣哪种币。
• 逐请求台账 GET /billing/usage：分页返回每笔扣费，支持 currency、startDate/endDate、limit（1–500）、sortOrder 过滤；Accept: text/csv 可直接导出 billing-usage.csv 做月度对账。inferenceDetails.requestId 关联原始 /chat/completions 响应，方便逐条回溯。
• 聚合分析 GET /billing/usage-analytics：按日期、模型、API Key 聚合，byDate/byModelDaily/byKeyDaily 已按时间序列预整形，topModels/topKeyNames 给图例准备 top-8。用 lookback=7d/30d 或 startDate+endDate 二选一查询。

扣款优先级：DIEM（staking 额度，每 epoch 重置）→ BUNDLED_CREDITS → USD → 已废弃的 VCU。

鉴权上，/billing/balance 和 /billing/usage 必须用 ADMIN Key，INFERENCE Key 会拿到 401；analytics 端点任意已认证 Key 均可（按 Key 所属账户限定范围）。

适用边界与坑

• 全线 Beta，字段可能变动，建议定期对照 swagger.yaml 校验。
• canConsume 只看 DIEM 和 USD 两个桶，不含 BUNDLED_CREDITS——判断“能不能消费”时要在代码里单独处理。
• analytics 缓存 10 分钟，突发流量在面板上有延迟；504 说明查询超时，应缩短窗口。
• byModelDaily.date 是 Unix 毫秒整数，byDate.date 是 YYYY-MM-DD 字符串，两种时间格式别混用。
• apiKeyId 为 null 的记录来自 Venice Web 端，对账时不要丢弃。
• 钱包（x402）余额不在此端点范围，要用 GET /x402/balance/{walletAddress}。