用于 AI 访问的合作伙伴和经销商 API：密钥、使用情况、计费和客户控制

转售或嵌入 AI API 访问权限不仅仅是将请求转发给模型提供商的问题。当每个下游客户需要自己的凭证、限制、使用记录、计费事件、支持控制和审计跟踪时，真正的运营工作就开始了。合作伙伴或经销商 API 负责管理该控制平面。

对于代理机构、顾问、SaaS 构建者、经销商小组和内部平台团队，合作伙伴 API 位于推论 API 之上。推理 API 运行聊天完成、嵌入、图像生成、转录或其他模型调用。合作伙伴 API 管理这些调用周围的业务对象：客户、API 密钥、密钥组、支出控制、请求历史记录、余额交易、异步作业、回调和帐户状态。

这一点很重要，因为共享提供商密钥很容易开始使用，但很难持续下去。一旦多个客户使用相同的凭证，归属就变得脆弱。虐待反应影响到每个人。速率限制和余额是汇总的。计费纠纷很难调查。弹性转销商设置需要客户范围内的访问权限和一个分类账，该分类账可以解释所发生的情况、造成的原因、成本以及应用了哪些控制措施。

合作伙伴 API 应该做什么

合作伙伴 API 是可信系统的服务器到服务器管理界面。它不应直接暴露给浏览器、移动应用程序、插件或不受信任的客户代码。您的后端、配置面板、计费工作人员、Telegram 机器人、支持控制台或经销商门户调用合作伙伴 API 来创建和管理下游访问。

在 AI 网关上下文中，合作伙伴 API 应支持至少四项持久职责。首先，它应该提供客户范围内的凭据。其次，它应该将这些凭证组织成组、计划、项目或租户边界。第三，它应该公开可以为计费和支持系统提供数据的使用和交易记录。第四，它应该提供生命周期操作，例如冻结、解冻、旋转、移动和删除键。

Model Gate 就是这种模式的一个示例。其合作伙伴 API 被记录为用于机器人、经销商面板、内部配置系统和可信集成的服务器到服务器接口。它使用带有合作伙伴 API 密钥的承载身份验证，并公开 API 密钥、组、密钥和组使用、最近请求记录、余额事务和异步结果轮询的操作。这些是控制平面功能，而不是模型推理端点。

区别很重要。客户可能会看到简单的产品界面，例如 AI API 经销商门户、白标 AI API 包或机构管理的 AI 集成。在这一表面背后，合作伙伴系统需要足够的结构来创建凭据、执行计划规则、计量消耗和处理支持事件，而不要求每个客户创建直接提供商帐户。

当代理机构和 SaaS 团队需要一个

当 AI 访问是产品或托管服务的一部分而不是一次性集成时，合作伙伴 API 就变得必要。机构可能需要一个 AI API，以便每个客户都有单独的预算、单独的使用报告和单独的终止开关。 SaaS 公司可能需要每个租户的密钥，即使最终用户从未看到它们，因此平台可以将模型成本归因于正确的帐户。内部平台团队可能需要部门、环境或应用程序的项目级边界。

如果您需要客户 API 密钥配置、基于计划的支出限制、委托使用分析或自动暂停和轮换，则应考虑经销商或合作伙伴 API。当客户从您那里购买访问权限而不是直接从底层模型提供商处购买访问权限时，您还应该考虑这一点。在这种情况下，客户关系、发票、支持路径和可接受使用强制措施部分或全部属于您的产品。

直接提供商帐户对于某些客户来说仍然是正确的选择。他们为买方提供直接的供应商控制权和清晰的供应商发票。但它们使得统一经销商计费、客户级硬上限、支持分类和模型可移植性变得更加困难。提供商管理 API 可能会公开项目、工作区、API 键、预算或报告，但这些对象在不同供应商之间并不总是相同的。多模型网关之上的合作伙伴 API 为您提供面向客户的合同的规范化层。

核心数据模型

持久的合作伙伴集成始于清晰的本地数据模型。至少，定义客户帐户、外部客户 ID、计划、计费模式、API 密钥、密钥组、使用限制、模型权限、当前状态和支持元数据。不要假设帐户所有者、计费所有者、凭证主体、客户租户和最终用户是相同的身份。在转销商和 SaaS 环境中，它们常常有所不同。

实用模型通常包括以下对象：

• 客户或租户：用于归因和计费的商业或应用边界。
• API key：客户、应用、环境或内部服务使用的凭据调用推理API。
• 组或计划边界： 共享限制、模型权限、定价规则或报告的容器。
• 使用记录： 描述请求 ID、客户、密钥、组、模型、端点、令牌计数、状态、时间戳和成本的规范化事件组件。
• 余额事务： 用于贷项、借项、调整、退款或结算的财务分类账条目。
• 异步作业： 提交的模型任务，可能稍后完成，需要轮询、回调处理和最终结算状态。
• 审核事件： 配置、限制更改、密钥轮换、暂停、支持操作和协调结果的内部记录。

即使网关公开类似的对象，此模型也应存在于您的系统中。您可以在本地数据库中将业务意图与网关状态连接起来：哪个客户购买了哪个计划、创建密钥的原因、哪个发票行使用了哪些使用事件，以及发生超时或回调失败时发生的情况。

配置工作流

配置应被视为状态机，而不是单个尽力而为的脚本。典型的工作流程首先在系统中创建或映射客户，选择计划，创建范围网关密钥，将密钥分配给组，应用限制和模型权限，仅安全地存储返回的密钥，并通过批准的渠道提供访问权限。

有用的状态包括pending、key_created、limits_applied、delivered、active、suspended、rotation_required 和 deleted。这些状态使重试和支持操作变得可以理解。如果密钥创建成功但限制分配超时，系统应该知道从哪里恢复。如果客户从预付费积分升级到后付费发票，系统应记录更改的控件以及更改时间。

凭据处理需要特别小心。 API-密钥秘密传递应该是一次性安全事件。不要记录秘密。请勿将提供商凭据发送到客户浏览器或移动应用程序。仅存储支持客户所需的内容，并提供轮换路径，以便在生产工作负载依赖旧密钥和新密钥时在计划的转换期间运行旧密钥和新密钥。

对于更广泛的凭据设计，客户范围的网关密钥应成为更大的API密钥管理策略的一部分，该策略涵盖轮换、冻结、最小权限、环境分离和支持可见性。

幂等性是一种计费功能

幂等性不仅仅是API的优点。在合作伙伴API自动化中，它可以保护客户和财务系统免受重复的副作用。创建两次密钥、两次添加积分或在超时后应用冲突的限制都会对客户产生真正的影响。

改变合作伙伴操作应需要稳定的幂等性密钥。 Model Gate 记录了对更改 POST、PATCH 和 DELETE 合作伙伴 API 请求的期望，并指示实现者在超时后使用相同的幂等性密钥重试相同的逻辑操作。它还记录了幂等记录的 7 天保留窗口。

密钥应源自业务意图，而不是源自随机重试尝试。例如，create-key:customer_123:prod:plan_pro 是一个稳定的逻辑运算。同一操作的新重试应该重用它。稍后为不同环境创建第二个密钥的操作应使用不同的幂等性密钥。

您的本地操作分类帐应存储请求方法、端点、幂等性密钥、外部客户 ID、负载哈希、网关请求 ID、响应状态和最终结果。该记录是工作流引擎和网关之间的桥梁。它还为支持和财务团队提供了一种方法来回答当工作人员崩溃、发生网络超时或客户声称信用调整被应用两次时发生的情况。

使用情况、计量和计费

基于 AI 使用情况的计费应基于标准化记录，而不是仪表板屏幕截图或广泛的提供商发票。有用的使用分类账包括请求 ID、客户 ID、密钥 ID、组 ID、模型、端点、模式、状态、代币和价格细分、时间戳和结算状态。在相关的情况下，它应保留令牌类别，例如输入、输出、缓存输入、工具使用、批处理模式或特定于提供商的调整。

金钱、积分、余额、乘数和使用数量应解析为精确的小数。 Model Gate 将其合作伙伴 API 中的财务和使用字段记录为 JSON 十进制字符串，并指示实施者使用任意精度的十进制算术而不是二进制浮点。该设计可避免发票、余额显示和经销商利润计算中出现的小舍入误差。

Stripe 式计量计费具有类似的要求：明确的客户标识符、使用值、时间戳、维度和幂等性标识符。如果将网关使用情况导出到外部计费提供商，请不要过早折叠太多详细信息。您可以按简化的单位计费，但仍然需要足够的来源来协调请求记录、余额交易、发票、退款和客户支持票证。

对于设计计划和利润的团队，合作伙伴计量直接连接到AI API计费。网关可以标准化模型访问和使用分析，但转销商仍然需要定价目录、生效日期、舍入政策、税务和发票规则，以及比较本地使用情况、网关状态、余额交易、回调事件和记帐提供商记录的调节作业。

支出限制、配额和费率限制

转销商产品通常需要硬控制。提供商仪表板可能会提供预算或警报，但警报与硬执行不同。一些提供商项目支出限制是软阈值。它们会通知或指导行为，但可能不会在您的产品承诺的客户边界停止使用。

合作伙伴API应该允许您按客户、密钥、组、计划或模型类实施限制。预付积分更容易设定上限，因为剩余余额是明确的。后付费发票可以适合企业采购，但需要更强大的异常检测、信用控制和收款工作流程。硬限制可以保护经销商的利润，但可能会中断客户的工作量。软警报可减少中断，但可能会导致超支。

费率限制还需要明确的所有权。客户可能会达到经销商级别限制、网关级别限制或上游提供商限制。您面向客户的文档应解释如何处理 HTTP 429 响应，尤其是 Retry-After 行为。 Model Gate 记录带有 HTTP 429、Retry-After 和 X-RateLimit 标头的速率限制响应。客户应根据这些标头后退，而不是立即重试并造成负载峰值或超额支出。

请求历史记录、分页和保留

最近的请求记录对于支持、调试和近期协调非常有用。它们不能替代永久财务数据库，除非网关明确承诺保留模型。将请求历史 API 视为操作窗口。导出并保留结算、审核、支持和分析所需的记录。

合作伙伴 API 通常对收集端点使用游标分页。 Model Gate 文档限制加上不透明的光标分页和 UTC RFC3339 时间戳。游标应被视为不透明标记。不要手动构建它们、在其中存储业务含义或构建呈现光标形状的计费逻辑。您的导出商应该记住最后一个成功的检查点，安全地处理重复记录，并按请求 ID 而不是单独按页面位置进行协调。

保留期限也会影响支持。如果客户询问两个月前的发票，您的答案不应取决于最近请求端点是否仍然具有原始事件。存储您需要的持久元数据：客户、密钥、组、模型、请求 ID、状态、使用数量、结算成本、时间戳和发票映射。

回调、轮询和异步推理

异步推理应建模为一流的工作流程。长时间运行的图像、音频、批处理或工具密集型作业可能会在最终使用情况和成本已知之前返回作业 ID。合作伙伴系统应存储提交的作业、轮询或接收回调、处理处理、已完成、失败、过期和取消状态，并根据最终结算政策进行计费。

轮询更容易实现，也更容易测试。回调可减少延迟并避免不必要的轮询负载，但它们需要签名验证、重播保护、重复数据删除、重试处理和死信处理。错过回电不应造成永久性的计费缺口。调节工作线程应比较异步作业状态、回调事件、请求历史记录和余额事务。

Model Gate 在合作伙伴 API 文档中记录异步结果轮询，并在其 API 文档中记录回调行为。在经销商产品中，这些功能应该包含在弹性交付模型中。客户应该看到清晰的作业状态和最终结果，而合作伙伴后端保留支持和计费所需的操作详细信息。

在不丢失来源的情况下进行提供商抽象

多模型网关可以向客户隐藏不必要的提供商差异。当您需要一种与 OpenAI 兼容的界面、一种计费关系以及一种跨提供商的运营模型时，这一点非常有价值。但抽象不应该抹去起源。您仍然需要知道哪些提供商、模型、端点、请求模式和令牌类别产生了成本或失败。

当提供商更改价格、弃用模型、更改速率限制或公开不同的管理语义时，这一点尤其重要。 OpenAI 项目、Anthropic 工作区、云 API 网关密钥和第三方 AI 网关虚拟密钥都解决了相关问题，但它们不公开相同的控件。经销商控制平面需要自己的规范化模型，并且应将提供商特定的字段视为支持调试、事件响应、客户信任和迁移规划的来源。

计划设计也与AI 模型选择相交叉。客户可能会购买简单的层，但您的后端可能会根据质量、延迟、价格、区域或可用性跨模型路由请求。保留足够的详细信息，以便在成本发生变化或产出不同时解释这些选择。

支持和滥用控制

应在第一个客户事件发生之前设计支持工作流程。操作员需要检查最近的请求元数据、确定哪个客户和密钥导致了峰值、冻结或解冻访问、轮换凭据、在组之间移动密钥、根据合同适当调整限制，并为每个操作保留审核事件。

良好的支持控制台不需要在默认情况下公开原始提示。元数据优先的可观察性通常为计费和操作分类提供足够的上下文，同时降低隐私和保留风险。如果存储或检查原始内容，请定义访问控制、保留期限、客户通知和审核日志记录。

滥用控制应该精确。冻结一把钥匙不应暂停不相关的租户。吵闹的客户不应耗尽所有其他客户的共享帐户余额或提供商容量。组级和关键级控制使响应速度更快、干扰更少。

白标、联合品牌或透明访问

经销商必须决定客户对底层网关和模型提供商的了解程度。白标 AI API 可能仅显示经销商品牌。联合品牌服务可能会公开网关或提供商。透明的企业产品可能会显示模型来源、提供商区域和详细的使用类别。

没有单一的正确答案。隐藏细节可以使客户产品更简单。披露详细信息可以改善信任、采购、合规审查和事件处理。重要的是一致性。发票、支持流程、可接受的使用政策、速率限制语言和数据处理承诺应与访问权限的呈现方式相匹配。

常见错误

最常见的失败是为许多客户使用一个共享的 API 密钥。在出现计费争议、滥用报告、延迟峰值、配额问题或客户流失事件之前，此功能一直有效。如果没有客户范围的凭据，每项调查都会变成猜测。

另一个常见错误是在没有幂等性的情况下重试变异操作。超时是不明确的。即使您的工作人员没有收到响应，操作也可能已成功。稳定的幂等性密钥和本地操作分类账可防止重复的密钥、积分和状态更改。

舍入误差也很容易被低估。将小数货币和使用字段解析为浮点数可能会产生在发票之间累积的微小差异。对积分、余额、乘数和结算成本使用任意精度的小数算术。

团队还过度信任提供商的预算。警报和项目级限制可能不会强制执行经销商计划中承诺的客户级硬上限。尽可能在网关或合作伙伴层实施限制，然后在完成后协调已确定的使用情况。

最后，不要仅根据总计建立结算。总计是有用的摘要，但发票需要有说服力的谱系。存储请求 ID、客户 ID、网关请求 ID、使用详情、交易记录、记帐事件 ID 和结算状态。

实施清单

从客户生命周期开始。定义如何创建、升级、暂停、重新激活、轮换和删除客户。将每个状态映射到合作伙伴 API 操作和本地审核事件。

接下来，设计操作分类帐。每个变异合作伙伴 API 请求都应具有稳定的幂等性密钥、负载哈希、可用的网关请求 ID、响应状态、重试计数和最终结果。该分类账是可靠合作伙伴API自动化的支柱。

然后构建使用情况导出和对账。按计划导出请求和交易记录。使用精确的小数。检查是否有缺失的事件、重复的结算提交、未解决的异步作业、回调失败和发票不匹配。

然后，仔细公开客户自助服务视图。显示使用情况、剩余预算、当前密钥、轮换选项、限制和最近的故障。不要公开提供商凭据或不相关的租户数据。尽可能使支持操作可审核且可逆。

最后，记录面向客户的重试和限制行为。解释 429 处理、关键轮换期望、异步作业状态、使用报告延迟以及硬上限、软警报、经销商限制、网关限制和上游提供商限制之间的差异。

结论

合作伙伴和经销商 API 是将 AI 模型访问转变为可靠产品的控制平面。它应该创建客户范围的凭据，将其组织成组或计划，实施支出和费率控制，公开使用情况和交易记录，支持异步工作流程，并提供轮换、冻结和对账等支持操作。

中心原则很简单：每个面向客户的承诺都需要持久的后端对象和审计跟踪。如果您承诺单独计费，请创建单独的归属。如果您承诺预算，请执行并协调它。如果重试操作，请将其设为幂等。如果您对使用情况开具发票，请保留精确的十进制记录和请求级出处。

Model Gate 的合作伙伴 API 功能是相关的，因为它们解决了围绕 OpenAI 兼容的多模型网关的控制平面工作：服务器到服务器身份验证、API 密钥和组自动化、十进制使用和财务字段、请求历史记录、余额事务、异步结果轮询、幂等性要求、速率限制响应、回调、统一计费、API-密钥管理、使用情况分析和团队控制。如果仔细使用，这些原语可以让代理机构、SaaS 团队和经销商打包 AI API 访问权限，而无需放弃计费控制或运营责任。