AI API 使用情况报告 API 是一种编程方式，可以回答一个简单但业务关键的问题：我们的 AI 使用情况和支出从何而来？
对于小型原型，提供商仪表板可能就足够了。一旦应用程序为真实用户提供服务、使用多个 API 键、调用多个模型、流响应、运行批处理作业或向客户转售 AI 访问权限，仪表板总数就不再足够了。开发人员需要知道哪个密钥、项目、模型、用户、租户、客户、工作负载或工具创建了使用。财务团队需要与提供商发票相符的报告。产品团队需要面向客户的使用视图。运营商需要在预算耗尽之前发出警报。
这就是 AI API 使用情况报告 API 的作用。它以软件可以查询、聚合、导出、审计和执行的形式公开使用情况和成本数据。良好的 LLM 使用情况报告 API 的作用不仅仅是计算令牌。它记录提供程序、模型、端点、请求状态、缓存使用情况、托管工具费用、媒体生成单元、流式处理结算、异步作业状态、货币、价格版本以及将使用情况与负责人员或系统相关联的归因字段。
AI API 使用情况报告 API 应该做什么
使用情况报告 API 至少会返回一段时间范围内的 AI API 活动。大多数团队都需要过滤器，例如开始时间、结束时间、模型、API 键、项目、工作区、端点、状态和客户。他们还需要按有用的维度进行分组：天、小时、模型、提供商、密钥、用户、团队、环境或租户。
有两个相关但不同的报告界面。使用 API 报告原始使用单位，例如输入令牌、输出令牌、缓存的输入令牌、图像生成、音频分钟、搜索调用、向量存储、请求计数和批处理项。 AI API 成本报告 API 报告资金：估计成本、结算成本、发票成本、积分、折扣、加价、货币和计费周期。成熟的系统会暴露这两者，因为没有使用的成本很难审核，而没有成本的使用则无法回答预算问题。
API 还应该支持两个详细级别。汇总报告回答了诸如按天和型号划分的总成本等问题。请求级报告回答了哪个确切的呼叫导致了峰值、哪个客户使用了密钥、流是否完成或者客户对费用提出异议的原因。聚合对于仪表板和账单摘要来说是高效的；请求历史记录对于审核和支持至关重要。
为什么信息中心和发票还不够
提供商信息中心很有用，但它们与持久报告不同API。仪表板可能会延迟更新、以 UTC 格式显示使用情况、使用特定于提供商的存储桶边界、将使用间隔与计费间隔分开，或者省略对您的产品重要的应用程序级标识符。它们是为审核而设计的，而不是用于自动客户计费、支出执行或对账工作流程。
发票对于付款具有权威性，但对于运营控制而言，它们到达得太晚了。当发票关闭时，使用已经发生。发票还倾向于在对会计有用但不一定对调试有用的级别上汇总行项目。它们可能不会告诉您哪个重试、后备、客户、API 键或工作负载创建了特定费用。
单独的 API 响应有时可能会在模型调用后立即包含使用数据。这有助于近乎实时的会计，但它不是一个完整的报告系统。流式响应可能仅在最后返回使用情况（如果有的话）。异步和批处理作业可能会稍后解决。一些提供商公开单独的管理 API 来计算成本，而其他提供商则通过云计费表或仪表板分析来显示支出。报告API必须将这些信号整合到一个一致的模型中。
核心数据模型：请求级使用分类账
最可靠的设计从请求级分类账开始。这是每个人工智能操作及其背后的每个提供商尝试的持久内部记录。它应该易于追加、可查询，并且明确说明成本是估算、结算还是开具发票。
实用的分类帐记录包括：
- 请求 ID 以及提供商请求 ID（如果有）。
- 帐户、组织、团队、项目、工作区、API 密钥、客户、租户、最终用户、工作负载和环境标识符。
- 已请求模型或别名、解析的提供商模型、提供商、端点、路由和服务层。
- 开始时间、结束时间、响应延迟、聚合存储桶和计费周期。
- 状态、错误类别、重试次数、后备链、取消状态和流式传输完成状态。
- 使用单位，例如输入令牌、输出令牌、缓存读取、缓存写入、推理令牌、图像单元、音频持续时间、文件搜索调用、网络搜索调用、向量存储、工具会话和批次项目计数。
- 定价目录版本、估算费用、结算费用、发票对齐费用、货币、积分、调整和调节状态。
- 隐私安全元数据，例如内容长度、哈希值、提示类别或跟踪 ID，无需原始提示和输出存储默认值。
此分类账成为实时 AI 支出分析 API 响应的事实来源。然后，提供商使用情况 API 和发票可用于结算、更正和核对账本，而不仅仅是报告开始的地方。
重要报告维度
使用情况报告的价值 API 取决于归因。如果所有使用情况都记录在一个共享密钥或一个通用项目下，则令牌计数的用处不大。
最重要的维度通常是API密钥、项目、团队、模型、提供商、端点、客户、租户、最终用户、工作负载和环境。对于 SaaS 应用程序，客户和租户归因通常最重要。对于内部开发者平台来说，项目、团队、环境、关键归属可能更重要。对于代理机构或经销商来说，下游客户和利润报告成为核心。
提供商原生维度各不相同。一个提供程序可能会通过 API 键和模型公开使用情况。另一个可能会通过云项目公开计费。另一个可能支持工作区 ID、推理地理、服务层或特定于工具的类别。强大的报告层规范了公共字段，但保留了提供者本机字段以进行调试和协调。
API关键边界尤其重要。如果每项服务共享一个密钥，则报告可以显示总支出，但不能显示责任。键级别报告还自然地与 LLM API 键支出限制 等控件相关联，其中报告 Feed 阈值检查、警报和硬停止。
使用单位比令牌更广泛
许多团队从令牌报告开始，后来发现它无法解释他们的账单。现代 AI 平台不仅仅对普通输入和输出令牌收费。
持久的 AI API 使用情况报告 API 应考虑缓存输入令牌、缓存写入、缓存读取、推理令牌、批量请求、实时会话、音频输入、音频输出、图像生成、视频生成、文件搜索、网络搜索、代码执行、向量存储、基础、微调和特定于提供商的托管工具。有些类别是使用单位而不是请求单位。其他是基于时间、基于存储或每次操作的。
请勿将它们折叠到单个令牌列中。令牌总数很有用，但成本报告需要原始单位类型。缓存读取的定价可能与新输入的定价不同。批处理作业的速率可能与同步请求不同。即使代币使用看起来很平常，托管工具也会产生费用。如果报告 API 隐藏了这些区别，客户支持团队将很难解释账单。
估算、结算和开具发票的成本
成本报告应将估算、结算金额和发票金额分开。将它们混合到一个字段中会产生调节问题。
估算费用是在请求期间或请求之后立即使用当前定价目录计算的。它对于仪表板、警报、预付余额和预算执行非常有用。结算成本是在了解最终提供商使用情况后计算的。它可能会有所不同，因为流被取消、异步作业稍后完成、提供程序在响应后返回最终使用情况，或者重试路径更改了实际提供程序尝试。开具发票的成本与提供商帐单一致，可能包括折扣、抵免、税费、企业费率、最低金额、退款或调整。
AI API 成本报告 API 应明确成本状态。 estimated_cost、settled_cost、invoice_cost、cost_status、settlement_time、invoice_period、货币、provider_amount、reporting_amount、adjustment_amount 和 price_version 等字段可帮助消费者了解他们正在查看的数字。
对金钱使用精确的小数处理。二进制浮点运算不太适合发票和客户余额。将货币代码、小数值和提供商原始金额与转换后的报告金额分开存储。
定价目录版本控制
历史报告不应仅仅因为模型价格今天发生变化而发生更改。每个使用记录都应该知道在请求时应用了哪个价格版本。这对于提供商模型价格、缓存费率、批量折扣、托管工具价格、合作伙伴加价、客户特定折扣和协商费率很重要。
定价目录应包括有效的开始和结束时间、单位名称、货币、提供商、模型、端点、服务层、缓存类别、批量模式以及任何加价或折扣规则。分类帐应存储已解析的价格版本或足够的定价上下文，以便稍后重现计算。
如果没有价格版本控制，月末对账就变成了猜测。今天生成的上个月报告可能不再与发票或使用发生时显示的面向客户的金额不匹配。
流式传输、重试、回退和异步作业
LLM 报告比普通 API 计量更困难，因为请求生命周期并不总是干净的请求-响应事件。
对于流式传输，API 应记录流式传输的时间启动、客户端是否断开连接、提供者是否返回最终使用情况、发出了多少输出令牌以及成本是否是最终的。如果应用程序显示部分答案但分类帐没有记录任何使用情况，或者提供商账单包含客户从未收到过的生成输出，则取消的流可能会产生争议。
重试和回退需要仔细建模。如果请求首先调用一个提供者，在部分工作后失败，然后回退到另一个模型，则分类帐应记录每个提供者的尝试。面向客户的结算成本可以仅对成功的尝试、所有尝试或特定于策略的金额进行计费。报告 API 应使内部提供商成本和外部计费政策均可审核。
异步和批处理作业需要生命周期状态：排队、正在运行、已完成、失败、已取消、部分完成和已解决。当提供商返回项目级使用情况时，报告 API 应保留项目级结算，以便一项失败的项目不会影响整个作业。
聚合、向下钻取、导出和分页
报告 API 通常需要多种访问模式。
聚合端点应支持时间窗口、存储桶宽度、过滤器和分组维度。常见示例包括按天和模型划分的成本、按密钥和端点划分的令牌、按状态和提供商划分的请求或按月划分的客户支出。短桶有助于操作和异常检测。每日和每月存储桶有助于财务、结算和产品分析。
向下钻取端点应通过确定性排序和光标分页来检索请求历史记录。使用数据集很快就会变大，因此偏移分页可能会变得缓慢或不一致。稳定的游标、有时限的过滤器和不可变的请求 ID 使导出更加安全。
导出端点应支持 CSV、JSON 和仓库友好的架构。较大的导出应作为幂等作业运行，可以重试而不会出现重复行或跳过页面。财务和 FinOps 团队可能需要 FOCUS 启发的成本和使用表来进行分配、监控和优化，但 AI 特定单元（例如缓存读取、工具调用和生成媒体）通常需要补充列。
对于人工审核，报告 API 通常支持 AI API 使用情况分析仪表板。 API 和信息中心应在定义上达成一致，但 API 在没有信息中心的情况下也应保持可用。
提供商和发票之间的对账
对账是解释应用程序分类账、提供商使用 API、提供商发票、付款记录、积分、退款和客户发票之间差异的过程。一旦涉及真实资金，它就不是可选的。
有用的对帐模型可存储提供商发票期间、提供商发票行参考、结算周期开始和结束、结算时间戳、调整原因、退款金额、信用金额和对帐状态。它还应保留提供商本机单位和标识符，以便支持工程师可以将报告的总数追溯到原始提供商数据。
预期差异。提供商仪表板的更新可能晚于请求日志的更新。计费周期可能与本地客户周期不匹配。一些提供商以 UTC 格式报告。云计费表可能包括税费、积分或项目级聚合。自定义定价协议在运行时响应中可能不可见。一份好的报告 API 并不假装这些差异不存在；而是假装这些差异不存在。它为团队提供了解释它们的字段。
隐私和保留
默认情况下，使用情况报告不应要求存储原始提示或模型输出。大多数成本和归因问题都可以通过元数据来回答：请求 ID、密钥 ID、客户 ID、模型名称、令牌计数、工具使用情况、时间戳、状态和成本字段。
在某些情况下，内容捕获有助于调试、滥用审查或支持。如果存储内容，则应通过明确的策略、访问控制、保留限制和编辑规则来控制内容。对于许多 LLM 使用报告系统来说，仅元数据日志记录是更安全的默认设置。
应记录保留情况。一种常见的模式是在较短的时间内保留详细的请求历史记录，并在较长的时间内保留汇总摘要。面向客户的账单报告可能需要在发票或合同的有效期内保持可用。内部调试跟踪的保留期可能会短得多。
访问控制和租户边界
报告 API 可能会暴露敏感的业务信息。它们显示了谁在使用 AI、他们花费了多少、他们调用了哪些模型、哪些客户处于活跃状态以及哪些工作负载在增长。
访问控制应与产品模型相匹配。个人开发者可能只能看到他们自己的密钥。团队管理员可以查看工作区中的所有项目。财务用户可能会看到成本，但看不到请求的内容。合作伙伴和经销商可能需要客户范围的报告，而无法了解不相关的租户。服务帐户的导出和自动化范围应较小。
对于在 AI 网关之上构建服务的团队来说，报告通常会连接到合作伙伴API自动化：客户配置、每个客户的余额、下游使用情况报告、回调和经销商结算。在这种环境中，租户隔离是报告设计的一部分，而不是事后的想法。
网关适合的位置
多模型网关会改变报告架构。网关可以在流量通过时记录标准化使用情况，而不是在事后将单独的 OpenAI、Anthropic、Gemini 和其他提供商报告拼接在一起。这使得关键级别归因、跨提供商分析、支出限制、请求历史记录和客户报告更易于实施。
网关级别报告并不自动对最终提供商发票具有权威性。它仍然需要协调、特定于提供商的出处和定价版本控制。但它有一个主要优点：它可以在请求时捕获应用程序级上下文。它可以在提供商发票数据存在之前了解客户 ID、团队、API 键、路由、请求的模型别名、解析的提供商模型、后备路径、回调状态和余额影响。
具体而言，对于 Model Gate，相关功能包括统一计费、API-密钥管理、使用情况分析、团队控制、请求历史记录、事务、Telegram 集成、回调、余额端点以及跨多个模型的合作伙伴 API 自动化。实用价值不仅仅是一份更好的报告；它是归因、限制、对账和下游计费的一致控制层。
实施清单
设计或评估 AI API 使用情况报告API时，请使用此清单：
- 定义实时使用情况、结算使用情况和发票对齐成本的真实来源。
- 记录请求级别在依赖聚合之前先存储分类帐行。
- 同时存储请求的模型别名和解析的提供程序模型/版本。
- 将原始使用单位与货币成本分开。
- 明确跟踪缓存、工具、媒体、存储、批量和实时单位。
- 在不同的字段中存储估算、结算和开具发票的金额。
- 版本定价目录并将价格版本附加到使用记录中。
- 表示流式传输、取消、重试、回退、异步和批处理状态。
- 对资金使用精确的小数处理并保留货币代码。
- 支持分组报告、请求向下钻取、导出和稳定的游标分页。
- 保留审核和处理所需的提供商本机字段协调。
- 对每个报告和导出应用租户感知的访问控制。
- 记录报告延迟、时区、存储桶边界和保留。
- 在报告 Feed 预算执行时提供警报挂钩或回调。
常见错误
最常见的错误是将令牌计数视为发票。代币只是成本的一种输入。缓存令牌、工具调用、生成的媒体、服务层级、批量费率、折扣和协商定价都可能改变账单。
另一个常见的失败是丢失归因。如果多个应用程序、客户或环境共享相同的密钥，则报告 API 稍后无法重建责任。在请求时传播客户、租户、用户、工作负载和环境标识符。
团队还过早地将估算成本和最终成本混合在一起。这可能使仪表板看起来很简单，但它使客户支持和协调变得更加困难。让成本状态可见。
过度标准化是另一个风险。统一的模式很有用，但特定于提供者的字段也很重要。如果系统丢弃推理区域、服务层、缓存类别、托管工具类型、批处理模式或提供商请求 ID，则稍后可能无法解释计费差异。
最后，避免将原始提示存储为可观察性的默认答案。隐私安全的元数据通常能够以较低的风险回答报告问题。
可行的结论
AI API使用情况报告API应该为开发者、运营商、财务团队和产品所有者提供有关 AI 消费的共享、程序化视图。持久设计是一个请求级分类账，具有明确的归属、原始使用单位、单独的成本状态、定价版本、提供商来源、调节字段和注重隐私的保留。
对于单一提供商原型，提供商信息中心和管理 API 可能就足够了。对于生产系统、面向客户的产品、多模型应用程序或经销商工作流程，报告需要成为应用程序架构的一部分。Model Gate 等网关可以提供 API 密钥、使用情况分析、交易、团队权限、统一计费和合作伙伴 API 工作流程交汇的控制点，同时仍保留协调最终帐单所需的提供商详细信息。