为经销商和 SaaS 租户构建面向客户的 AI 使用情况报告 API

您的内部网关分类帐与面向客户的报告不同API。分类账证明了平台内发生的事情。客户报告解释了租户、客户、工作区或最终客户在发票时间之前可以安全地查看、查询、协调和使用的内容。

对于向自己的客户公开 AI 使用情况的经销商、代理机构、嵌入式 AI 产品和 SaaS 团队来说，这种区别很重要。顾客不仅会问“我花了多少钱？”他们询问哪个密钥、模型、端点、工作流程、用户群体或时间段导致了支出；该数字是否是最终数字；为什么发票与昨天的仪表板不同；以及该过程中是否公开提示或提供者凭据。

实际的答案是发布稳定的 AI API 使用情况报告 API，并由不可变的使用事件、版本化定价、范围访问令牌和协调端点支持。 API 应该是无聊、明确且不易误解的。

在数据模型之前定义报告协定

从客户问题开始，而不是从存储架构开始。报告API应回答四个问题：

• 该租户使用什么？
• 根据客户可见的定价规则，费用是多少？
• 这个数字是估计的、调整后的还是最终的？
• 它如何与发票、积分、充值或合作伙伴保证金关联？

这与内部运营信息中心不同。内部系统可能会公开提供者请求 ID、路由决策、原始错误负载、重试状态或凭证池名称。面向客户的 API 应仅公开归因、成本解释、审核和产品分析所需的字段。

事实：AI 提供商和计费系统通过不同的字段名称、分组选项和聚合行为公开使用情况和费用数据。一些使用 API 按模型、工作区、密钥或服务层等维度进行分组；其他表面因端点类型而异。网关应在发布客户报告之前对此进行标准化。

建议：将报告API视为产品合同。从第一个版本开始对其进行版本控制，即使第一个版本只有几个端点。

使用租户范围的维度

报告 API 应使租户边界无法绕过。每个查询在触及使用数据之前都必须解析为授权租户范围。

有用的维度包括：

• customer_id：下游客户或租户。
• project_id：客户内部的应用、环境、团队或工作区。
• api_key_id：网关颁发的密钥，而不是上游提供商密钥。
• model_alias：客户可见的型号名称或配置文件。
• provider：可选，并且仅当公开提供商选择是合同的一部分时。
• endpoint_family：聊天、响应、嵌入、图像、音频、批量、实时、工具或其他稳定类别。
• workflow_tag：客户提供的标签，例如 support-bot、invoice-parser、coding-agent 或 qa-eval。
• user_hash：默认情况下不暴露个人数据的匿名最终用户标识符。
• time_bucket：每小时、每天、每月或自定义间隔边界。

对于经销商和代理机构，此报告合同属于合作伙伴配置界面。如果客户和密钥是通过合作伙伴API自动化创建的，则使用情况报告应使用相同的客户和密钥标识符，而不是发明第二个命名系统。

分别公开使用单位和货币字段

一份好的报告将实际使用情况与定价分开。代币、工具调用、图像、音频秒和批处理作业都不是钱。金钱是根据使用情况、定价规则、折扣、积分、保证金和调整来计算的。

每个聚合行至少应包含以下字段：

{
  "bucket_start": "2026-09-01T00:00:00Z",
  "bucket_end": "2026-09-02T00:00:00Z",
  "customer_id": "cus_123",
  "project_id": "proj_support",
  "api_key_id": "key_789",
  "model_alias": "support-fast",
  "endpoint_family": "chat",
  "request_count": 18420,
  "input_tokens": 9821000,
  "cached_input_tokens": 2410000,
  "output_tokens": 1268000,
  "reasoning_tokens": 310000,
  "tool_calls": 860,
  "estimated_cost": "142.36",
  "settled_cost": "141.91",
  "currency": "USD",
  "pricing_catalog_version": "2026-09-01",
  "invoice_status": "pending"
}

不要仅仅因为发票以货币计价就隐藏令牌类别。客户需要单元字段来调试行为。缓存的输入令牌、推理令牌、托管工具费用和媒体单元通常可以解释为什么两个相似的工作流程花费不同的金额。

建议：将十进制货币存储为 API 响应中的字符串。避免成本字段使用浮点值。在每一行上使用货币字段，而不是假设一种全球货币。

单独的临时使用、调整后使用和最终使用

面向客户的 AI 报告经常会失败，因为它们假装每个数字都是最终数字。实际上，第一个请求完成后，用法可能会发生变化。

常见原因包括：

• 在提供程序返回最终使用情况之前客户端断开连接的情况下流式传输响应。
• 批处理、媒体或托管工具的提供商延迟使用。
• 在应用程序看到一个逻辑请求但网关看到多个可计费尝试时进行重试。
• 退款、积分、价格更正或欺诈逆转。
• 模型别名发生变化，其中客户可见的名称与上游模型 ID 不同。

不要以导致昨天的API响应无法解释的方式默默地覆盖行。相反，发布一个状态模型：

• provisional：根据网关估算值或部分提供商数据计算得出。
• settled：根据标准化提供商使用情况和有效定价目录计算得出。
• adjusted：因后续更正、贷记、退款或对帐事件而更改。
• invoiced：包含在客户可见的发票或对账单中。

原始使用事件应该是不可变的。更正应显示为与原始事件或聚合期间链接的调整行。

{
  "adjustment_id": "adj_456",
  "original_event_id": "evt_abc",
  "customer_id": "cus_123",
  "reason": "provider_usage_correction",
  "cost_delta": "-0.45",
  "currency": "USD",
  "created_at": "2026-09-03T10:15:00Z"
}

权衡：近实时报告更有利于预算提醒和客户信任，但它需要可见的临时状态。仅最终报告更容易核对，但当客户试图在发票到达之前阻止超支时，它的用处就小得多。

提供聚合和原始事件访问权限

一个端点无法服务于所有用例。仪表板需要廉价的聚合。财务团队和企业客户可能需要行级证据。

实用报告API通常至少包含三个端点系列：

GET /v1/usage/summary
GET /v1/usage/events
GET /v1/usage/reconciliation

端点摘要

摘要端点应返回一小组维度和时间段的预聚合使用情况。

GET /v1/usage/summary?customer_id=cus_123&from=2026-09-01T00:00:00Z&to=2026-09-08T00:00:00Z&bucket=day&group_by=model_alias,api_key_id

将其用于仪表板、预算页面和面向客户的成本明细。它应该足够快，可以重复调用而无需扫描原始事件表。如果产品包含 AI API 使用情况分析仪表板，则此端点通常是使 UI 与导出的报告保持一致的后端合约。

事件端点

事件端点应通过游标分页公开不可变的使用记录。将其用于审核繁重的客户、支持调查和仓库导出。

GET /v1/usage/events?customer_id=cus_123&from=2026-09-01T00:00:00Z&limit=500&cursor=eyJpZCI6...

每行应包含稳定的 event_id、时间戳、请求系列、模型别名、密钥 ID、规范化使用单位、成本字段和状态。默认情况下不应包含原始提示或完成。

调节端点

调节端点将使用情况连接到客户可见的结算对象。

GET /v1/usage/reconciliation?customer_id=cus_123&invoice_id=inv_2026_09

返回发票行项目、使用总额、已应用的积分、充值、税费（如果适用）、合作伙伴保证金规则（如果客户可见）以及第一次估算后所做的任何调整。这就是使用情况报告变成可解释的计费而不是一堆计数器的地方。

建议： 发票和使用情况报告保持相关但不相同。用法 API 解释了消耗。发票解释了应付金额。它们应该通过稳定的 ID 进行协调，而不是陷入一个过载的端点。

使用Cursor分页和稳定的排序

偏移分页对于使用事件来说很脆弱，因为新记录和后期调整可能会在客户分页时到达。使用具有稳定排序的游标分页。

持久模式是：

• 按event_time和event_id排序。
• 当存在更多记录时返回next_cursor。
• 使光标不透明。
• 记录迟到事件是否可以出现在已读窗口中。
• 为调节作业提供updated_since过滤器。

对于聚合端点，客户可能需要可重复的报告。支持 finalized_before 或 report_version 参数，以便财务导出可以一致地重新运行。

GET /v1/usage/summary?customer_id=cus_123&month=2026-09&status=finalized&report_version=2026-10-02

预测：随着提供商添加新的令牌类型、工具费用、服务层级和媒体计费单位，AI 使用情况的报告架构将不断变化。版本化的报告合约比公开当前提供商响应恰好包含的任何内容的端点更容易老化。

版本定价和架构一起

使用字段和定价规则独立更改。模型可能会获得缓存令牌定价。提供者可以引入推理令牌控制。经销商可以在履行旧合同的同时更改新客户的保证金规则。

每个费用行应包括：

• pricing_catalog_version
• schema_version
• rate_effective_at
• currency
• cost_basis：估算、结算、调整、开具发票

当平台提供跨多个模型提供商的统一 AI API计费时，这一点尤其重要。仅当客户能够了解异构使用如何标准化为一致的成本类别时，单一账单才有用。

事实：开放式成本和使用模式正在不断发展，以涵盖 AI、云、SaaS、数据中心和其他技术供应商。这支持版本化方法，而不是硬编码一个永久导出形状。

将访问控制设计为API

的一部分

使用数据属于敏感数据。它可以揭示客户增长、产品发布、自动化失败、滥用事件或内部工作流程。访问控制应该是报告设计的一部分，而不是事后的想法。

明确定义角色：

• customer_admin：可以查看其客户范围的所有使用情况。
• project_admin：可以查看分配的项目的使用情况。
• billing_viewer：可以查看费用和发票对账，但不能查看用户级别的细分。
• support_operator：可以通过审核日志记录检索支持案例的窄片段。
• partner_operator：可以查看分配的租户，但默认情况下不是每个租户。

使用范围令牌进行机器访问。 A token that can query usage for cus_123 should not be able to change keys, modify pricing, or read another customer’s usage by guessing IDs.

还要确定哪些维度对隐私敏感。 user_hash 字段对于某些客户来说可能是安全的，但对于其他客户来说则过于暴露。如果客户将收购目标或法律审查等名称放入元数据中，工作流标签可能会泄漏业务上下文。清楚地记录保留和修订行为。

最低实施清单

使用此顺序可以避免构建看起来完整但无法协调的报告 API。

1. Create immutable usage events. Assign every billable event a stable ID, tenant scope, request family, model alias, normalized units, timestamps, and source status.
2. Normalize provider usage into internal units. Keep raw provider payloads internally if needed, but expose stable customer fields.
3. 应用版本化定价目录。存储用于每次估算、结算和调整的目录版本。
4. 具体化每小时和每日的聚合。不要让信息中心查询扫描客户规模的原始事件。
5. 添加调整行。切勿在没有说明的情况下通过更改旧费用总计来隐藏更正。
6. 构建游标分页事件导出。包括不透明游标、稳定排序和更新后过滤器。
7. 构建发票调节。将用量行链接到发票行、贷项、充值和保证金规则。
8. 强制执行租户范围的授权。测试每个报告端点是否存在损坏的对象级授权。
9. 发布架构版本。为客户端提供请求稳定报告形状的方法。
10. 默认为不保留原始提示。使用情况报告不应要求提示或完成存储。

常见的权衡

聚合优先或事件优先：聚合优先 API 对于大多数客户来说更安全、更便宜。事件导出功能更强大，但会带来更大的隐私、分页和支持负担。首先报价汇总，除非您的买家有审核要求。

公开或隐藏提供商名称：公开上游提供商可以帮助经验丰富的客户分析性能和成本。隐藏提供者可以使产品抽象更加清晰。如果路由是您价值主张的一部分，请考虑将提供商公开为由计划或角色控制的可选维度。

实时估算或最终报告：实时估算可帮助客户在支出成为结算问题之前采取行动。最终报告更适合会计。大多数成熟的系统都需要两者。

严格的财务架构或产品友好的架构：面向财务的架构可以减少集成工作，但对于客户产品来说可能过于繁重API。实际的折衷方案是在内部使用受金融启发的字段，同时发布更简单的版本化客户架构。

可行的结论

面向客户的 AI 使用情况报告 API 不应该是提供商计费响应或内部管理表的薄包装。它应该是一份稳定的合同，让租户在开具发票之前了解使用情况、深入了解正确的维度、区分临时成本和最终成本，并在不暴露提示或上游凭据的情况下协调费用。

围绕三个端点构建第一个版本：摘要、事件和调节。通过不可变的使用事件、调整行、版本化定价、游标分页和租户范围的访问令牌来支持它们。该基础足以支持仪表板、客户导出、转销商运营和结算纠纷，而无需将每个发票问题都转变为手动支持调查。

相关阅读

• 构建不可变的 AI API 结算分类账