接入文档

把你的产品接入 AI Relay:选档位、写清单、实现 POST /relay、过接入验收。

计费与结算

前置环节免费,成交按效果计费。Relay 只向你(供给方)收钱,从你的预付余额里扣;用户付给你的钱照旧走你自己的收款渠道,Relay 不经手。你的代码不做任何计费动作:什么时候扣、扣多少、退不退,都由 Relay 按清单、平台定价和订单状态算。

收什么

推广期: 平台有两个推广期,分开开关,不一定同时结束。订单免手续费的推广期开着时,订单(有没有成交价都一样)和查询都不收手续费,余额是 0 也照样能被搜到、能接单,也不提示余额偏低;推广期里建的订单之后也不补收,推广期开始前建好的订单照建单时的手续费收。免入驻费的推广期开着时入驻费全部免收。下表是两个推广期都结束后的收法;现在各在不在推广期,以后台「余额与流水」页「收费方式」里对应的那一行为准。

板块 怎么收 什么时候扣
订单(有成交价的收费动作) 成交价 × 平台费率,当前 3%,四舍五入到分 订单完成时(on_accept 的在接单时);失败、取消、过期不收
订单(没有成交价的收费动作) 清单里写的固定 fee,¥1–¥100 / 笔 同上
查询类(只读动作) 按次,平台定单价;目前不收 每次成功返回
入驻费 个人开发者 ¥30、商家 ¥300,每个账号只收一次 首次审核通过时
  • 成交价就是清单里的 amount:发起时从输入取(比如 {"from": "input.price_cents"}),或者在清单里写死金额。有成交价的多方案单(按完成计费)以用户选定方案的 price_cents 为准,方案没写报价的按发起时的预算;on_accept 的多方案单接单时按预算扣,之后不按方案调整;没有成交价(按固定 fee)和只读的多方案单不随方案报价变。
  • 武汉本土首批入驻的商家第一年享 1% 优惠费率,由平台在后台为你设置,到期自动回到平台费率。优惠只往下优惠:平台费率以后调得比它还低时,按平台费率收。
  • 费率和单价以后台「余额与流水」页的「收费方式」为准。手续费和当时的费率在建单时记进订单,平台之后调价不影响已经建好的订单。
  • 免入驻费的推广期内审核通过的,以后也不补收入驻费。这个推广期结束后,首次审核通过前要先充值到够付入驻费(体验额度不能抵入驻费)。

两笔钱:fee 和 amount

字段 谁付给谁 用来做什么
amount 用户在这笔交易里付给你的钱(成交价) 和用户给 AI 设的单笔上限比较;平台按它乘费率算手续费。Relay 不收这笔钱
fee 你付给 Relay 的固定手续费,整数分 只对没有成交价(amount 为 "none")、不是只读的收费动作生效,100–10000 分(¥1–¥100)每笔。有成交价的动作、只读动作(按查询单价收)不用管,填 0 即可;不收费的动作写 0

amount 三种写法:"none"(没有用户金额)、固定整数分、{"from": "input.<字段>"}(取输入里的字段,这个字段必须是必填的 integer,单位分)。收到下单请求后,核对 amount 对应的字段和你的真实价格一致,对不上回 invalid_input。

用户给每个 AI 的默认授权是:最高中风险、单笔 ¥200、每笔确认。金额超过上限的调用会被拒绝,用户被引导去授权页调高;多方案的选方案一步用方案的 price_cents 比较。

什么时候扣

清单 billing 扣费时刻
on_complete Relay 收到 completed(同步响应或回调)的同一个事务里
on_accept 收到 accepted 时,只用于异步动作。多方案的单此时还没选方案,按发起时的成交价(预算)扣
none 不扣(只读动作按查询类单价扣,见上表)
  • 每单最多扣一次。重复的响应、重复的回调、补拉拿到的同一个结果都不会再扣。
  • 失败、取消、过期的订单不收费。on_complete 的单不产生流水;on_accept 的单接单时已扣,之后进失败、取消、过期时 Relay 在同一事务里自动写一条等额退款流水(备注写明原因),净额为 0。
  • on_accept 仍不推荐:接单到失败之间余额会先被占用一笔。没有特别理由请用 on_complete。
  • 结果未知的订单(发出后 5xx 或超时)先不扣,进「待核对」,管理员核对后按 billing 补扣或标失败。
  • 手续费在建单时记进订单,之后改清单、平台调价都不影响在途订单。有成交价的多方案单(按完成计费)在用户选方案时按方案报价重算,费率仍用建单时的;重算后变高时,你的可用额度(余额减去其他还没结算的订单的手续费,再加透支额度,见下面「余额」)要够新的手续费,不够这次选择不发给你、也不改价,用户可以换方案。选择没生效或你撤回了已选方案,手续费回到按预算算的数(只降不升)。
  • 你撤回同一个方案时 Relay 还没记下你对这次 proposal.select 的答复(一般是还没答复就撤回):以 Relay 收到的答复为准。答 selected / completed 照常生效,方案恢复成已选,按这个方案的报价收(Relay 自己耽搁了、发出选择 5 分钟后才记下答复,手续费已经退回按预算算的数的,也改回这个方案的价;这期间用户又改选了别的方案的,completed 在订单还没按改选的方案结束时按这个方案成交,selected 在改选的方案还算数时以改选的为准);答 failed,或者答复没送到 Relay(超时、5xx、连接断开)时,方案保持撤回、这次选择不生效,手续费回到按预算算的数,这个方案不会再被选定:之后回调报来的写着它的方案号(output.data.proposal_id)的 completed 都不成交,不写方案号的会被当成用户另选的方案的结果,所以多方案单的 completed 要写方案号,撤回了的方案的 completed 丢掉,回调和 task.poll 都别再报。等答复期间被拒的回调(比如方案号对不上的 completed)不算对这次选择的答复。要接着办,用新的 proposal_id 重新提交方案让用户再选;还可能接受的方案不要撤回。选择发出到 Relay 收到答复之间,和这段时间交叠的 task.poll 回的方案列表里暂时没有选择涉及的方案,Relay 不按撤回处理,下一次补拉再看。

余额

  • 后台「余额与流水」看当前余额、可用额度和每一笔流水,每笔扣费对应一个订单号,可以按月导出 CSV。
  • 首次审核通过时,Relay 自动送一笔体验额度(¥100,每个账号一次:一个账号开了多个供给方,只送给最先审核通过的那个),流水备注「体验额度(首次审核通过赠送)」。拿到体验额度的供给方审核通过就能被搜到,不用先等充值(成交价写死在清单里、一笔手续费超过体验额度的动作除外,要充值到够一笔才会出现);账号已经领过的,新供给方审核通过时余额是 0,收费动作要可用额度(下面说)不低于它的手续费才会出现(订单免手续费的推广期内不看余额,收费动作也能被搜到)。
  • 余额按供给方算:同一账号的几个供给方各有各的余额,不能互相转。
  • 充值:平台开了在线充值时,在「余额与流水」页扫码充值,到账自动加余额;没开时联系管理员,管理员按付款凭证加余额并写一笔充值流水。
  • 可用额度:每一单发给你之前,Relay 先看可用额度够不够付这一单的手续费。可用额度 = 余额 − 还没结算的订单占着的手续费 + 透支额度。还没结算的订单是已经发给你、还没出结果的单,以及按完成扣(on_complete)的已接单、等用户选方案的单;按接单扣(on_accept)的单接单时已经扣过,不再占。透支额度是平台给所有供给方统一设的一个数(默认 ¥50,以「余额与流水」页为准):余额用完以后还能再接这么多手续费的单,余额会变成负数,下次充值先补上。
  • 可用额度不够付手续费时,收费动作从搜索结果里隐藏:成交价从输入取的动作可用额度为 0 就隐藏(事先不知道这一单多少);成交价写死在清单里的,可用额度低于一笔的手续费就隐藏,算出来是 0 时也要至少 1 分(多方案单选方案时还会按方案报价重算);按固定手续费收的,可用额度低于一笔就隐藏;查询类可用额度低于单价就隐藏。能进搜索、但可用额度不够这一单的手续费时,这一单不下发、不收费,你后台订单列表里这一单会写「没发给你:当时可用额度不够付这一单的手续费,没扣钱」。已经发给你的订单照常做完、照常扣费(手续费下发前已经占好;平台调小透支额度、管理员扣回余额时,余额可能低于 −透支额度)。
  • 提醒:可用余额(余额 − 还没结算的订单占着的手续费)低于提醒线,或者已经开始用透支额度时,后台提示并给联系邮箱发邮件;可用额度不够收费最高的那个动作一笔时再发一封,写明哪些新订单暂停了(手续费超过可用额度的)、充值后马上恢复。邮件只发给上线中的供给方(暂停中的充了值也要等暂停解除)。同一档或更低一档的提醒一天最多一封:在途单失败、取消让占用变少、下一单又占满,不会来回发;中间充过值的,再跌破照常提醒。提醒线至少 ¥50;有按固定手续费收的、成交价写死在清单里的动作,或者有只读动作且查询单价不是 0 时,是这些动作里最高一笔手续费(只读动作按查询单价算)的 20 倍(取大的)。余额全是体验额度时不提示偏低(为付入驻费充的钱不算),开始透支或可用额度用完时照常提醒。
  • 不收费的动作(包括目前不收费的查询类)不看余额:余额被扣成负数也照常能被搜到、能调用。
  • 订单免手续费的推广期内,所有动作都不看余额、不提示余额偏低。这个推广期一结束就按上面的规则:可用额度不够的,收费动作当场从搜索里隐藏,并收到邮件提醒,所以推广期快结束时先把余额充够。平台调小透支额度也是当场生效。
  • 注销:余额是负数(透支欠着手续费)时不能自己注销,先充值补上。

争议与退款

觉得某一单不该扣费(比如用户没到店、重复下单),在扣费后 72 小时内提异议:在后台「争议」里选订单写原因,或者发 order.dispute 回调(见 L2)。管理员看订单的完整事件时间线和双方说法后裁定:退款(不超过这一单扣的手续费,写退款流水)或驳回,都会写原因。

质量与暂停

后台「质量」页每 5 分钟更新一次指标,也影响你在搜索里的排序。最近 24 小时有 20 单以上时,成功率低于 80%、超时率高于 20%、首次应答 p95 超过 30 秒任一条成立,供给方会被自动暂停:搜索里看不到你的动作,已经发给你的订单照常走完,还在等用户确认的不会再发给你。修好后联系管理员恢复。平台也可能只下架某一个动作(比如描述和实际不符),后台首页「上线状态」和清单页会写明原因,其他动作照常;这个动作同样只有已经发给你的订单照常走完。争议率(最近 7 天)连续一个月高于 10% 时进人工复核。用户取消、没选方案、not_available 这类业务结果不算你的失败。

规范原文见第 12 节。设计原因见 ADR-005 完成时计费、ADR-008 手续费与用户金额分开和 ADR-011 按成交价抽成的盈利模式。