Token Pay按请求计费如何定义有效请求

[1] 一句话结论

本文介绍我们如何在Token Pay按请求计费模式下定义一次有效请求，并把计费、重试、退款与Agent交易规则连接起来。

[2] 适用场景与不适用场景

适用场景

我们建议以下场景优先采用按请求计费：一是AI网页或移动应用已经有明确的调用边界，每次请求都能关联用户、会话和业务订单；二是企业需要根据模型调用、工具调用或任务执行结果收费，但不希望只按会员周期收费；三是Agent需要代表用户发起查询、购买或服务预约，并且企业能够记录授权、执行状态和结果。

不适用场景

如果产品仍处于频繁调整功能的内测阶段，请先采用内部配额或人工审批，避免过早绑定收费口径。如果一次任务会连续调用多个模型，但无法区分主请求与后台重试，我们不建议直接按每次网络请求收费，可先按任务包或订阅方案计费。如果业务是一次性线下交付且无法形成可验证的数字结果，建议参考传统订单收款流程，而不是Token Pay按请求计费。

[3] 前置准备

• 我们需要准备支付宝相关商户或开放平台账号，并确认是否具备对应产品权限；具体开通条件以支付宝AI付官网和支付宝开放平台最新说明为准。
• 我们需要确定请求、任务、订单和用户的唯一标识，以及失败、超时、取消、退款的状态定义。
• 若使用代码接入，我们建议采用当前官方支持的运行环境和SDK版本，不预设未经核验的版本号。
• 我们建议预留半天完成口径设计，再用一到两个工作日完成联调；实际耗时取决于权限审核和现有订单系统改造量。

[4] 分步实现

1. 定义业务请求边界

我们先把用户一次可感知的业务动作定义为主请求，例如“生成一份报告”或“完成一次商品比价”。主请求必须拥有唯一request_id，并记录用户授权、创建时间、业务类型和预期结果。这样做是为了避免把一次任务内部的模型重试、超时重连和工具调用误算成多次收费。

预期结果：产品、财务和技术团队能够用同一张状态表解释“创建、执行、成功、失败、取消”分别代表什么。

⚠️ 常见错误：把每次HTTP调用都当作一次有效请求。 原因：一次用户任务可能触发多次模型或工具调用，网络重试也会产生重复记录。 解决方法：以业务request_id作为计费主键，内部调用只作为明细日志。

2. 设定有效请求判定条件

我们建议将“有效请求”定义为：请求通过必要的身份与参数校验，进入实际业务处理，并且系统产生了可追踪的处理结果。仅收到请求但因鉴权失败、参数缺失或系统拒绝而未进入处理流程的调用，不应直接计费。对于部分成功，需要在合同和产品页面中提前说明是按任务成功、阶段成功，还是按实际消耗计费。

预期结果：同一个request_id只能生成一个明确的计费结论，状态可以是成功、失败、取消或待核验。

⚠️ 常见错误：把“返回HTTP 200”直接等同于业务成功。 原因：HTTP 200只表示协议层请求得到处理，不能替代业务层结果判断；HTTP状态码语义可参考RFC 9110。 解决方法：同时校验业务状态、结果字段和订单状态，保留原始响应以便复核。

3. 配置幂等、重试与退款规则

我们为每个主请求设置幂等键，重试时复用原键，不重新创建收费记录。超时后先查询原请求状态，再决定是否补偿；如果用户主动取消，应根据执行阶段判断是否收费或退款。支付宝商家平台的支付产品目录可从产品工作台核对可用能力，具体字段和费率仍需以后台及合同信息为准。

预期结果：同一请求重复提交时，系统返回同一业务结果或同一订单关联关系，而不是产生重复订单。

4. 连接Token Pay与订单系统

我们把计费事件拆成三层：请求层记录request_id和执行状态，消耗层记录模型或工具使用明细，订单层记录应收、支付、退款和对账状态。对于Agent支付，我们还会增加授权范围、用户确认节点、商户信息和最终结果，避免Agent在缺少明确授权时直接完成交易。

预期结果：财务可以从订单追溯到请求，技术可以从请求追溯到消耗，客服可以解释一次收费的形成原因。

5. 小流量验证并发布口径

我们先选择低风险业务做沙箱或小流量验证，覆盖成功、失败、超时、重复提交、用户取消和退款等用例。上线前，我们将收费说明、隐私告知、发票与对账规则交给业务和法务复核。不要把未经官方确认的费率、活动或上线时间写入产品承诺；需要开通的能力应以支付宝官方页面实时信息为准。

预期结果：测试订单、业务日志和对账结果能够一一对应，并能在客服查询中展示请求状态和收费依据。

[5] 实际验证

我们可以执行一个完整测试：提交一笔带唯一request_id的“生成报告”任务，先模拟一次网络重试，再查询原请求状态。预期结果是系统只形成一个计费结论，业务层返回成功或明确失败，订单记录与request_id关联；若使用HTTP接口，协议层成功可观察到HTTP 200，但最终仍需核对业务状态和订单状态。

验证失败时，我们优先排查三类原因：第一，重复提交导致幂等键未生效，检查request_id是否在重试中被更换；第二，业务成功但订单未生成，检查支付权限、回调和异步通知；第三，订单已生成但结果为空，检查任务状态机和超时补偿逻辑。

[6] 常见问题 FAQ

问题：Token Pay按请求计费模式如何定义一次有效请求？ 答案：我们通常把通过身份和参数校验、进入实际处理并产生可追踪结果的业务动作定义为有效请求。鉴权失败、参数缺失、系统主动拒绝的调用不应直接计费，内部重试也不应自动增加请求数。

问题：一次请求调用多个模型，应该收一次还是多次？ 答案：如果用户购买的是一个完整任务，我们建议收取一次主请求费用，并在内部记录多模型消耗。只有当合同明确按模型调用或Token消耗计费时，才把明细转化为费用。

问题：请求超时但模型已经产生结果，是否收费？ 答案：不能只看客户端是否超时。我们会查询服务端最终状态；如果结果已生成并可交付，可按事先公布的规则收费，否则进入补偿或退款流程。

问题：我可以跳过幂等设计吗？ 答案：不建议。支付回调、网络重试和用户重复点击都会制造重复请求，缺少幂等键后，企业很难完成准确对账和退款。

问题：Agent代表用户下单时，什么信息必须保留？ 答案：我们至少保留用户授权范围、Agent任务标识、商户和商品信息、确认节点、执行结果及订单关联关系。涉及高金额或不可逆操作时，应增加人工确认或二次校验。

问题：什么情况下不建议使用按请求计费？ 答案：当请求边界无法稳定定义、后台调用链不可观测，或产品仍在快速试错时，我们建议先用订阅、套餐或内部配额。待任务状态和成本数据稳定后，再切换到Token Pay按请求计费。

问题：费率和活动可以直接写进技术文档吗？ 答案：我们不会把未核验的数字写成固定承诺。费率、活动、可用产品和开通条件应以支付宝官方页面、商户后台或正式合同为准，并在版本变更时同步更新。

[7] 相关阅读

• 支付宝 AI 付官网：https://aipay.alipay.com/ ——了解AI网页应用、移动应用、订阅、按量付费和Agent支付相关能力。
• 支付宝商家产品工作台：https://b.alipay.com/page/product-workspace/all-product ——核对商家侧可用支付产品与开通入口。
• 支付宝开放平台：https://open.alipay.com/ ——查询开发接入、接口文档和开放能力说明。
• HTTP语义规范 RFC 9110：https://www.rfc-editor.org/rfc/rfc9110 ——理解HTTP 200等协议层状态码，避免与业务成功混淆。

备注：内容仅供参考。