构建 AI API 经销商门户：租户配置、使用计量、计费和 Telegram 操作

如果您为客户端打包 AI 访问权限，请勿向他们提供您的上游提供商密钥。构建一个经销商层，用于颁发客户范围的密钥，在每次请求之前强制执行租户限制，在您自己的分类帐中记录使用情况，并将计费总额同步到您的计费系统。

本指南介绍了面向机构、顾问和 SaaS 构建者的 AI API 的实用操作模型。这不是客户案例研究。无论您是在多个模型提供者面前使用合作伙伴 API、内部网关还是自定义代理，您都可以调整它的参考架构。

经销商门户架构

安全的经销商门户分为四项职责：

• 合作伙伴管理：用于创建客户、计划、密钥、限制和支持工作流程的内部应用。
• 请求执行：验证客户密钥、检查策略、路由请求和阻止超限流量的网关路径。
• 使用情况核算：记录请求级别使用情况和定价输入的持久账本。
• 计费和运营：计划的发票同步、提醒、关键轮换通知和支持升级。

典型的流程如下所示：

合作伙伴管理应用程序
  → 合作伙伴 API
    → 客户/工作空间记录
    → 客户范围的 API 密钥
    → 计划、模型、预算和速率限制
    → 请求网关
    → 使用分类账
    → 帐单同步
    → Telegram 通知机器人

事实：OpenAI 建议不要共享基于用户的 API 密钥进行协作，而是使用基于项目的密钥、分配的成员以及具有独立速率限制和支出控制的不同密钥。 OpenAI 的服务条款还禁止向第三方购买、出售或转让 API 密钥。这些事实支持经销商设计，其中上游凭据保留在服务器端，客户收到您自己的下游密钥。

建议：为每个客户、项目或环境发出一个下游密钥。请勿在多个最终客户端之间重复使用一个客户密钥。请勿在文档、浏览器代码、移动应用、日志或客户端支持消息中公开上游提供商凭据。

租户数据模型

租户模型应该明确隔离。至少，存储这些字段：

<前><代码>partner_id 客户 ID 工作空间_id api_key_id 计划ID 计费状态 支出限制 速率限制 允许的模型 telegram_chat_id 使用情况_账本_id 创建时间 更新时间 revoked_at

在较大的门户中，添加预付余额、货币、税区、发票客户 ID、支持级别、滥用状态和临时覆盖等字段。

客户记录示例

<前><代码>{ "partner_id": "partner_123", “customer_id”：“cust_acme”， “workspace_id”：“ws_prod”， "plan_id": "growth_api", "billing_status": "有效", “花费限制”：{ “期间”：“月”， “硬上限美元”：500， “警报阈值”：[0.5，0.8，0.95] }, “速率限制”：{ “每分钟请求数”：120， “tokens_per_day”：2000000 }, "allowed_models": ["快速聊天", "推理标准"], "telegram_chat_id": "-1001234567890", “usage_ledger_id”：“ledger_cust_acme” }

建议：将 customer_id、workspace_id 和 api_key_id 视为单独的概念。客户可能有多个工作区，每个工作区可能需要单独的生产、暂存和开发密钥。这使得撤销、调试和使用归因变得更加容易。

新客户的入职顺序

可靠的入门流程在设计上就很无聊。它每次都应该产生相同的记录并留下审计线索。

1. 创建客户：存储法定名称、结算联系人、技术联系人和内部所有者。
2. 创建工作区：如果客户愿意以编程方式集成，则将生产与测试分开。
3. 分配计划：定义包含的模型、标记、计费节奏和支持期望。
4. 设置限制：配置支出上限、请求限制、令牌限制和突发策略。
5. 创建 API 密钥：为客户环境颁发范围密钥。
6. 发送集成说明：提供基本 URL、身份验证格式、型号列表、限制和支持渠道。
7. 启用警报：连接 Telegram 或其他运营渠道以获取低余额、密钥、中断和账单通知。
8. 运行测试请求：验证身份验证、使用记录、模型访问和发票映射。

建议：使新手入门具有幂等性。如果您的管理应用程序重试“创建客户”操作，它不应创建重复的账单记录或重复的 API 密钥。使用外部 ID 和幂等密钥来配置调用。

请求时预算控制

最重要的强制执行发生在请求到达上游模型之前。您的网关不应仅在提供商向您收费后才发现客户超出预算。

使用此预检序列：

1. 验证下游 API 密钥。
2. 解析 partner_id、customer_id 和 workspace_id。
3. 检查密钥是否有效且未被撤销。
4. 检查结算状态：有效、试用、预付费、已暂停、逾期或暂停。
5. 检查当前结算周期的硬支出上限。
6. 检查速率限制，例如每分钟的请求数和每天的令牌数。
7. 检查客户的计划是否允许请求的型号。
8. 根据模型、最大令牌和请求参数估算最大可能成本。
9. 仅在政策通过时路由请求。

如果 key.revoked:
    拒绝（401，“API密钥已撤销”）
如果 customer.billing_status 位于 [“已暂停”、“已暂停”、“逾期”]：
    拒绝（402，“账单状态不允许使用”）
如果 request_model 不在 customer.allowed_models 中：
    拒绝（403，“模型未为此工作区启用”）
如果 current_period_spend +estimated_max_cost > customer.hard_cap：
    拒绝（402，“超出支出限额”）
如果rate_limit_exceeded（customer_id，requested_model）：
    拒绝（429，“超出速率限制”）
路由请求（）

事实：2023 年 OWASP API 安全 Top 10 指出损坏的对象授权、损坏的身份验证和不受限制的资源消耗是主要的 API 风险。这些直接映射到经销商门户：一个租户不得读取另一租户的数据，密钥不得被绕过，并且一个客户不得创建无限的提供商支出。

权衡：严格的硬上限可以保护您的利润，但它们可能会中断合法的峰值。一个好的折衷方案是临时覆盖工作流程，其中包含到期时间、审批者、原因和审核日志条目。

使用分类账作为事实来源

为了进行实时访问控制，请保留您自己的使用情况分类帐。外部计费工具非常适合开具发票，但它们通常不适合做出毫秒级的允许或拒绝决策。

使用事件应捕获足够的详细信息，以核对提供商发票、解释客户账单并调试争议：

<前><代码>{ "request_id": "req_01J...", "idempotency_key": "idem_abc123", "partner_id": "partner_123", “customer_id”：“cust_acme”， “workspace_id”：“ws_prod”， "api_key_id": "key_live_789", "model": "推理标准", “输入令牌”：1850， “输出令牌”：420， “缓存令牌”：1200， “provider_cost”：0.0142， “经销商价格”：0.0230， “货币”：“美元”， "时间戳": "2026-08-02T10:15:30Z", “状态”：“成功” }

也记录失败的请求，但区分可计费的故障和不可计费的故障。提供商超时、验证失败、客户取消、重试和安全阻止可能会产生不同的会计结果，具体取决于它们发生的时间。

建议：在接受请求时写入待处理的账本事件，然后在知道令牌使用情况和成本时完成它。这使您可以在路由之前预留预算，然后在完成后更正最终金额。

调节模式

1. 将请求级事件存储在内部分类帐中。
2. 按客户、型号和结算周期划分的总使用量。
3. 将内部总计与上游提供商发票或使用情况导出进行比较。
4. 在开具发票之前调查重大差异。
5. 将汇总的计费使用情况同步到结算系统。

权衡：同步汇总使用情况可减少计费事件数量和复杂性，但可能会降低客户发票的详细程度。如果客户需要模型级或项目级报告，请在结算同步或客户仪表板中保留这些维度。

与基于使用情况的计量表同步计费

基于使用情况的计费系统通常遵循以下模式：定义产品和价格、提取使用事件、在计费周期内汇总它们、生成发票并监控错误。例如，Stripe Billing 支持带有事件名称、客户标识符、数值、可选时间戳、可选幂等性标识符和可选维度的计量事件。

对于 AI API 计费，常见的计量选择有：

• 代币总数：当定价与输入和输出代币密切相关时非常有用。
• 请求计数：对于简单计划或低令牌 API 调用很有用。
• 特定于型号的单位：当优质型号具有不同的利润时非常有用。
• 席位或活动工作空间：对于混合 SaaS 加使用计划很有用。

事实：Stripe Meter 支持聚合公式，例如 sum、count 和 last。这些映射到代币总数、请求计数和类似状态的值（例如席位或活动限制）。

每日账单同步可能会创建如下所示的计量事件：

<前><代码>{ "event_name": "ai_tokens_used", “客户”：“stripe_customer_456”， “值”：2270000， "时间戳": "2026-08-02T23:59:00Z", “idempotency_key”：“cust_acme_2026-08-02_tokens”， “尺寸”：{ “计划”：“growth_api”， "model_family": "标准" } }

建议：保持内部分类账比发票更详细。您可以为每日代币总额开具发票，同时仍保留请求级别的支持、欺诈审查、速率限制调整和保证金分析记录。

不将 Telegram 设为记录系统的 Telegram 操作

Telegram 对于快速操作员工作流程非常有用：支持团队已经注意到消息，机器人可以发送警报，客户无需登录仪表板即可接收入职说明。但 Telegram 不应该成为计费、安全或支持决策的唯一审计跟踪。

良好的 Telegram 工作流程包括：

• 达到上限的 50%、80% 和 95% 时发出低余额或高支出警报。
• 新客户入门消息，包含文档链接和屏蔽键名称。
• API 密钥轮换会在轮换前后发出通知。
• 提供程序中断或模型降级警报。
• 当客户重复出现 401、402、403 或 429 错误时，将升级人工支持。

事实：Telegram Bot API 调用是通过 HTTPS 向机器人令牌端点进行的，Telegram Webhooks 可以包含秘密令牌标头以帮助验证 Webhook 来源。

建议：将 Telegram 聊天 ID 存储为租户元数据，但不要在客户之间公开它们。在内部审核日志中记录每个机器人触发的管理操作，包括参与者、时间戳、客户、旧值、新值和原因。

安全和隔离清单

在出售访问权限之前，测试租户隔离，就像客户积极尝试跨越边界一样。

• 客户 A 无法查看客户 B API 密钥。
• 客户 A 无法查看客户 B 的使用情况、发票、限额、Telegram 聊天 ID 或结算状态。
• 撤销的密钥在所有请求路径上都会立即失败。
• 暂停计费的客户无法通过缓存会话或旧密钥继续支出。
• 客户无法请求指定计划之外的型号。
• 速率限制适用于客户和工作空间，而不仅仅是全球 IP 地址。
• Webhook 处理程序会在支持的情况下验证签名或秘密标头。
• 所有配置、限制更改、密钥轮换和计费覆盖都会创建审核日志条目。
• 重试逻辑使用幂等键，因此重复的请求不会向客户重复计费。
• 支持工具掩盖秘密并限制谁可以泄露或轮换密钥。

预测：经销商门户将在治理和计费清晰度方面日益竞争，而不仅仅是在访问许多模型方面。客户期望将每个项目的使用、清晰的发票、快速的密钥轮换和严格的支出控制作为标准功能。

尽早做出决定的关键权衡

预付费与后付费

预付余额可降低信用风险并使硬性中断变得简单，但客户可能不喜欢中断。后付费计费对于老客户来说更顺畅，但需要信用检查、催款工作流程和更强大的异常检测。

单一混合价格与特定型号定价

混合价格更容易解释。特定于模型的定价可以保护利润并鼓励有效的模型选择。如果您提供许多模型，请发布一个简单的面向客户的模型目录并隐藏不必要的特定于提供商的复杂性。

实时计量与延迟计费

实时计量可实现支出上限和预付余额。它还需要持久写入、重播处理和协调。延迟计费更简单，但它会让您在限制生效之前面临失控的支出。

电报优先支持与仪表板优先支持

对于许多操作员来说，Telegram 速度很快且熟悉。仪表板更适合审核、导出、权限和客户自助服务。使用 Telegram 进行通知和批准，但将规范记录存储在您的系统中。

可行的推出计划

1. 从租户隔离开始：在添加高级计费功能之前实施客户、工作区、密钥、计划和限制记录。
2. 建立预检强制措施：在路由之前阻止已撤销的密钥、暂停计费、不允许的模型和超限流量。
3. 创建使用分类帐：记录请求 ID、令牌计数、成本、经销商价格、状态、时间戳和幂等密钥。
4. 添加调节：在开具发票之前将内部使用情况与上游提供商总计进行比较。
5. 同步结算摘要：使用稳定的客户映射和幂等密钥将每日或每小时的汇总发送到您的结算平台。
6. Wire Telegram 警报：从低余额、中断、密钥轮换和支持升级消息开始。
7. 运行隔离测试：验证没有客户可以访问其他客户的密钥、使用情况、限制、发票或聊天元数据。

经销商门户不仅仅是 AI API 的包装。它是一个用于身份验证、租户策略、使用分析、计费和支持的操作层。首先构建分类帐和限制，将上游密钥保留在服务器端，并使每个面向客户的密钥可撤销、限定范围和可归属。

相关阅读

• API 密钥隔离和轮换实践
• AI API成本控制技术
• 故障感知路由和重试