venice-billing

Venice 账单

用于查询账户级账单和分析数据的只读端点。usage-analytics 在规范中标记为 Beta——其架构和行为可能发生变化。

端点	用途
GET /billing/balance	当前的 canConsume 标志、剩余 DIEM、已赚取额度、捆绑额度和美元余额，以及周期额度。
GET /billing/usage-history	按请求记录的账本，支持键集（游标）分页。支持 JSON 或 CSV。
GET /billing/usage-analytics	汇总数据细分：按日期、模型和 API 密钥统计。
GET /billing/usage	已弃用。 2026-09-16 起停止服务；所有请求均返回 410。

三个仍可用的端点都需要使用 ADMIN 密钥进行 Bearer 身份验证——INFERENCE 密钥会得到 401（"Admin API key required"）。这些端点不接受 x402 钱包身份验证；查询钱包余额请使用 venice-x402。如果请求完全没有 Authorization 标头，会返回 402 x402 发现响应，而不是 401——请忽略其中的支付选项，改用 ADMIN Bearer 密钥；无效密钥会得到 401。

GET /billing/usage 已停止服务。 自 2026-09-16 起，无论请求是否通过身份验证，都会返回 410 Gone，且不提供使用数据。响应正文的 error 字符串会指出替代端点和参数重命名信息，响应还会包含 Deprecation: @1783555200、Sunset: Wed, 16 Sep 2026 00:00:00 GMT 和 Link: </api/v1/billing/usage-history>; rel="successor-version", <https://docs.venice.ai/api-reference/endpoint/billing/usage-history>; rel="deprecation"; type="text/html"。 该路由的速率限制为每个 IP 每分钟 60 次请求（之后返回 429，错误消息中会重复迁移指引）。请迁移到 GET /billing/usage-history： page + limit → pageSize + nextCursor，startDate / endDate → startTimestamp / endTimestamp。

货币／优先级

每个请求只会使用一种货币扣费，按以下顺序选择：

1. DIEM——来自质押的 DIEM；分配额每个周期（UTC 日）重置。
2. EARNED_CREDITS——以美元计价的已赚取额度。
3. BUNDLED_CREDITS——付费 Venice 订阅方案中包含的美元计价额度。
4. USD——预付法币余额。

对于排队任务和图像等预报价费用，会使用能够覆盖全部费用的第一种货币。按 Token 计价的请求会在运行后扣费，使用余额为正的第一种货币，因此余额可能会略微变成负数。

旧版 VCU（DIEM 的旧称）不再是可用于消费的货币；/billing/usage-history 的 currency 筛选器会拒绝它。

每个密钥的美元消费限额合并计算 USD、BUNDLED_CREDITS 和 EARNED_CREDITS；DIEM 限额则用于 DIEM（参见 venice-api-keys）。

GET /billing/balance

curl https://api.venice.ai/api/v1/billing/balance \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

{
  "canConsume": true,
  "consumptionCurrency": "DIEM",
  "balances": { "diem": 90.5, "usd": 25, "bundledCredits": 10, "earnedCredits": null },
  "diemEpochAllocation": 100
}

• 当账户可用于支出的 DIEM、已赚取额度、捆绑额度和 USD 合计至少为 $0.10 时，canConsume 为 true。它不考虑每个密钥的限额或账户的 API 等级——每次推理请求都会执行实际准入检查。若要进行包含这些因素的检查，请使用 GET /api_keys/rate_limits → accessPermitted。
• consumptionCurrency 是余额为正的第一种货币，顺序为 DIEM、EARNED_CREDITS、BUNDLED_CREDITS、USD；若都不符合，则为 null。规范枚举中也列出了 VCU，但实际不会返回。
• 账户未质押 DIEM 时，balances.diem 为 null；否则为本周期剩余的 DIEM。
• balances.usd、balances.bundledCredits 和 balances.earnedCredits 在余额不为正时为 null。
• diemEpochAllocation 是当前周期的 DIEM 总额——balances.diem / diemEpochAllocation = 剩余比例。

GET /billing/usage-history

按请求记录的账本，使用键集（游标）分页，时间戳按升序排列。

curl "https://api.venice.ai/api/v1/billing/usage-history?startTimestamp=2026-06-01T00:00:00Z&endTimestamp=2026-07-01T00:00:00Z&pageSize=1000&currency=USD" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Accept: application/json"

查询参数

请求要么是带筛选条件的第一页，要么是不带筛选条件的续页请求。将 cursor 与任何筛选条件一并发送会返回 400，发送任何未知参数也会返回 400—— 验证器采用严格校验。

参数	说明
startTimestamp	可选。包含下限，采用带 Z 后缀的 ISO 8601 UTC 格式（最长 40 个字符）。仅适用于第一页。
endTimestamp	可选。不包含上限，格式相同。必须晚于 startTimestamp。边界相同的连续时间窗口可遍历完整历史记录，不会遗漏或重复。
currency	可选。USD / DIEM / BUNDLED_CREDITS / EARNED_CREDITS。
pageSize	整数，范围为 10–1000。默认值为 1000。
cursor	不透明的续页令牌（[A-Za-z0-9_-]，≤ 512 个字符），取自先前响应中的 nextCursor。它包含所续接遍历的筛选条件和页面大小，因此应单独发送。

如果游标已过期、被篡改或签发给了其他用户，则返回 400（"Invalid or expired cursor; restart from the first page"）。新用量记录产生时，页面内容仍保持稳定；不会报告结果总数。

响应（JSON）

{
  "data": [
    {
      "timestamp": "2026-06-15T19:05:10.504Z",
      "sku": "zai-org-glm-5-1-llm-output-mtoken",
      "units": 0.000227,
      "pricePerUnitUsd": 2.8,
      "amount": -0.06356,
      "currency": "DIEM",
      "notes": "API Inference",
      "inferenceDetails": {
        "requestId": "chatcmpl-4007fd29f42b7d3c4107f4345e8d174a",
        "promptTokens": 339,
        "completionTokens": 227,
        "inferenceExecutionTime": 2964
      }
    }
  ],
  "nextCursor": "AZq3fK9tXhIVDm2j4vN8cQwYt1sB6uEoLxRgPzKaJdHfM5nC7yW0K3w"
}

最后一页的 nextCursor 为 null。

字段

• sku — 计费明细项（模型 + 单位类型 + 格式）。
• units — 对于大模型，表示百万个令牌（例如，0.000227 = 227 个令牌）。
• pricePerUnitUsd — 每单位以 USD 计价的费率。
• amount — 借记时为负数。
• currency — USD、DIEM、BUNDLED_CREDITS 或 EARNED_CREDITS。
• inferenceDetails — 非推理条目为 null。存在时，requestId 是原始响应返回的 id；未记录时，promptTokens、completionTokens 和 inferenceExecutionTime（ms）均可为 null（非大模型用量的令牌数为 null）。

CSV

发送 Accept: text/csv。列：timestamp, sku, pricePerUnitUsd, units, amount, currency, notes, inferenceDetails.requestId, inferenceDetails.inferenceExecutionTime, inferenceDetails.promptTokens, inferenceDetails.completionTokens。 Content-Disposition 为 attachment; filename=billing-usage-history-<UTC export stamp>.csv，因此遍历中的每一页都会以唯一且可排序的名称下载。由于 CSV 没有封套，续页令牌会放在 x-next-cursor 响应头中；最后一页不会包含该响应头。

遍历完整历史记录

let url = `${base}/billing/usage-history?startTimestamp=${start}&endTimestamp=${end}`
for (;;) {
  const page = await fetch(url, { headers }).then(r => r.json())
  handle(page.data)
  if (page.nextCursor === null) break
  url = `${base}/billing/usage-history?cursor=${encodeURIComponent(page.nextCursor)}`
}

GET /billing/usage-analytics

用于仪表板的汇总概览。按用户和周期缓存 10 分钟。

curl "https://api.venice.ai/api/v1/billing/usage-analytics?lookback=7d" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY"

查询参数（选择一种方式）

• lookback=Nd — 必须匹配 ^[1-9]\d*d$。默认值为 7d。超过 90d 的值会被限制为 90 天（此时响应中的 lookback 为 "90d"）。
• 或者 startDate=YYYY-MM-DD 和 endDate=YYYY-MM-DD（包含首尾日期，按 UTC 天计算）。范围最多为 90 天，且 endDate 不得早于 startDate。请同时发送两者：若只提供其中一个，则会忽略该参数并应用 lookback。

响应（选定字段）

{
  "lookback": "7d",
  "byDate": [{ "date": "2026-04-20", "USD": 0.5, "DIEM": 10.25 }],
  "byModel": [
    {
      "modelName": "GLM 5.1",
      "unitType": "tokens",
      "modelType": "LLM",
      "totalUsd": 0.4,
      "totalDiem": 12.5,
      "totalUnits": 50000,
      "breakdown": [
        { "type": "Output", "usd": 0.3, "diem": 10, "units": 35000 },
        { "type": "Input",  "usd": 0.1, "diem": 2.5, "units": 15000 }
      ]
    }
  ],
  "byModelDaily": [{ "date": 1705276800000, "GLM 5.1": 5.5, "Kimi K2.6": 3.2 }],
  "byModelDailyUsd": [{ "date": 1705276800000, "GLM 5.1": 0.4, "Kimi K2.6": 0 }],
  "topModels": ["GLM 5.1", "Kimi K2.6"],
  "byKey": [
    { "apiKeyId": "key_abc123", "description": "Production Key",
      "totalUsd": 0.8, "totalDiem": 15, "totalUnits": 75000 },
    { "apiKeyId": null, "description": "Web App",
      "totalUsd": 0, "totalDiem": 4, "totalUnits": 25000 }
  ],
  "byKeyDaily": [{ "date": 1705276800000, "Production Key": 8.5, "Web App": 2 }],
  "byKeyDailyUsd": [{ "date": 1705276800000, "Production Key": 0.8, "Web App": 0 }],
  "topKeyNames": ["Production Key", "Web App"]
}

• byDate 在时间窗口内每天都有一条记录（按升序排列，缺失值补零）。USD 总额包含 BUNDLED_CREDITS，但不包含 EARNED_CREDITS：使用已赚取额度支付的支出不会计入任何分析总额。
• byModel / byKey 会列出所有模型和密钥，并按总支出（USD + DIEM）排序。只有当模型使用了多种令牌类型时，才会提供 breakdown（Input / Output / Cache Read / Cache Write …）。
• byModelDaily / byKeyDaily 是图表数据行：包含 date（Unix 毫秒）以及每个系列的一个字段，数值合并了 USD + DIEM。byModelDailyUsd / byKeyDailyUsd 是相同的数据行，但只包含 USD（含捆绑额度）部分。这两个 *Usd 数组会在响应中返回，但尚未纳入已发布的 schema。
• topModels / topKeyNames 是图表中的系列：按支出列出排名前 50 的系列，后面再附加一个汇总第 50 名之后所有数据的 "Other" 系列（仅当系列超过 50 个时）。规范文本仍写着“top 8”；API 实际返回 50 个。
• apiKeyId: null / description: "Web App" 表示来自 Venice Web 应用的用量。没有描述的密钥会显示为 Key ...<last 6 of id>；重复的描述会附加 (...<last 6 of id>) 后缀，避免系列名称冲突。
• 购买额度不计入；只汇总扣款。

用法示例

账户余额不足时，在调用推理前中止

/billing/balance 的 canConsume 会忽略每个密钥的限额和账户的 API 层级，因此应改用 GET /api_keys/rate_limits 返回的 accessPermitted 进行拦截（适用于你即将使用的密钥，包括 INFERENCE 密钥）：

const { data } = await fetch(`${base}/api_keys/rate_limits`, { headers }).then(r => r.json())
if (!data.accessPermitted) throw new Error('Venice balance exhausted — top up before continuing')

每月 CSV 导出

curl -D headers.txt "https://api.venice.ai/api/v1/billing/usage-history?startTimestamp=2026-04-01T00:00:00Z&endTimestamp=2026-05-01T00:00:00Z&pageSize=1000" \
  -H "Authorization: Bearer $VENICE_ADMIN_KEY" \
  -H "Accept: text/csv" \
  -o billing-april-001.csv

从 headers.txt 读取 x-next-cursor，并使用 ?cursor=<token> 重新请求（不带其他参数），直到响应头中不再包含该字段。

模型排行图表

const a = await fetch(`${base}/billing/usage-analytics?lookback=30d`, { headers }).then(r => r.json())
// chart(a.byModelDaily, { series: a.topModels, xField: 'date' })

错误

代码	含义
400	/billing/usage-history：cursor 与任何筛选条件一起发送、参数未知、时间戳格式错误、pageSize 不在 10–1000 范围内、endTimestamp 不晚于 startTimestamp，或游标无效 / 已过期。/billing/usage-analytics：lookback / 日期格式错误、endDate 早于 startDate，或日历日期范围超过 90 天（lookback 超过 90d 时会截断，不会拒绝）。
401	密钥无效，或在任何计费端点使用了非 ADMIN 密钥。
402	完全没有 Authorization 请求头 — x402 身份验证质询。
410	/billing/usage — 始终如此。于 2026-09-16 停用。
429	/billing/usage 每个 IP 每分钟超过 60 次请求；或触发通用 API 错误预算。
500	内部错误。
504	/billing/usage-analytics 查询超时 — 缩短 lookback 或日期范围。

注意事项

• 所有计费端点都需要 ADMIN 密钥，包括 usage-analytics（旧版文档曾表示任意密钥均可使用 — 这一要求于 2026-07-21 变更）。
• 完全不要调用 /billing/usage。它不会返回数据；遇到任何 410 都应视为“立即迁移”。
• /billing/usage-history 接受 startTimestamp / endTimestamp（带 Z 的完整 ISO 日期时间）和 pageSize；/billing/usage-analytics 接受 lookback 或作为普通 YYYY-MM-DD 日期的 startDate / endDate。不要混用格式。
• /billing/usage-history 的 currency 筛选器不接受 VCU；请使用 DIEM。
• 非推理条目（例如订阅扣费）的 inferenceDetails 为 null。
• 一次推理请求可能对应多条账本记录（例如输入和输出令牌 SKU 分开记录），这些记录中的 inferenceDetails 会重复。对各行的 amount 求和，但在汇总令牌数量前，需按 requestId 去重。
• 分析端点会缓存 10 分钟 — 突发峰值会在仪表板中延迟显示相应时长。
• byModelDaily.date 是 Unix 毫秒整数；byDate.date 是 YYYY-MM-DD 字符串。
• 来自 Venice Web 应用的用量，其 apiKeyId: null — 对账时不要将其剔除。
• 对于 x402（钱包）余额，不要使用这些端点 — 请使用 GET /x402/balance/{walletAddress}。