AI模特API接口对接实录：批量出图的限流、幂等与记账

动工前先做三个决定：同步异步、轮询回调、批量粒度

批量出图一律选异步提交加回调通知，单张试跑才用同步；回调做主、轮询做兜底，批量任务按店铺分批提交，这三个决定定了整个架构。

单张生成30秒起步，同步接口挂着HTTP等结果，网关超时都熬不到它画完，所以批量场景直接pass同步。异步提交返回任务ID，结果靠两种方式拿：回调推送和主动轮询。我们的方案是回调为主、轮询兜底，每5分钟扫一次超过10分钟还没结果的存量任务。这个兜底后来立过大功，不细说，后面有数据。

批量粒度上我们吃过亏。最早一口气把一个店200张任务全扔进去，赶上对面高峰期限流，整批失败一半，重提又全量重扣。改成按店铺分批、每批50张、批间隔随机抖几秒，高峰期成功率立刻稳住了。

放量之后的三种坑：限流、回调丢失、重复扣费

限流要按429状态码做退避重试，回调丢失靠超时兜底扫描捞回，重复扣费靠客户端自生成的幂等键挡住，三件事各有各的做法。

限流的坑在于它不提前打招呼。对面文档写着并发上限，实际还有隐藏的每分钟配额，大促前我们压测时连续吃了一串429。解法是标准的指数退避：第一次等2秒，翻倍重试，最多5次，配合客户端全局排队，把发起频率压到配额的八成，给突发留余量。

回调丢失是三月份最诡异的一晚：凌晨两点批量任务跑完600张，回调只到了570张。30张任务在对面系统里其实成功了，结果一直没推过来。靠轮询兜底扫描捞回来28张，2张任务状态查不到，工单找客服核实后退了费。教训就是那句老话：不能指望通知一定到，兜底扫描不是可选项，是必选项。

重复扣费最肉疼。我们的重试逻辑最早写糙了，超时就重提，任务其实已经在跑，等于一张图扣两次钱，账单对不上才发现。加幂等键之后根治：每个任务由客户端生成唯一ID随请求带上，对面收到相同ID直接返回已有任务。这个字段文档里写着但没强调，我建议每个对接的人都当第一优先级处理。

按张记账：成本核算和失败单处理要进代码里

每张任务从提交到落库记录状态、耗时、扣费和重试次数，月底按这张表对账，失败单按状态码分流处理，账才对得平。

我们的任务表记四个字段就够用：任务ID、状态、扣费金额、重试次数。三个月跑下来41200张，失败2870张，占7%。失败原因分流：参数错的属于我们自己的bug，修代码；限流超限的进重试队列；对面服务内部错误的提工单，按张申请退费。月底拿这张表跟账单对，第一还差过400多块的差额，就是没记重试次数的锅。

单张综合成本算给你看：接口按张计费约1.8元，加上重试和失败损耗摊到1.95元左右，比外包实拍一套两百多的报价，账怎么算都成立。运营同事现在的口径是：批量出图走我的接口，主推款大图照旧实拍，两条线互不打架。

写到这里补一句感受：这类接口的文档质量参差，参数说明漏一半是常态，真遇到含糊的地方直接提工单要示例，别自己猜。我猜错过一个字段枚举值，白烧了六十多张的额度。

绕回开头：API对接的功夫，一半在写代码前的三个决定，一半在放量后的三种坑。异步加回调兜底、退避重试、幂等键、按张记账，这套组合拳打完，4万多张任务的批量出图才算真正跑稳。你如果正准备对接，先把兜底和记账写进第一版，别等账单教做人。

常见问题

单张生成一般多久，超时时间设多少合适？

我们统计的中位数在35秒左右，长尾能拖到3分钟。异步模式下提交接口秒回任务ID，不存在超时问题；兜底轮询我建议扫10分钟还没终态的任务，超过30分钟直接判异常进人工核对，别无限等。

回调一直收不到，排查顺序是什么？

先查本地回调服务能不能被外网访问，我们栽过内网穿透配置变更后忘了更新的跟头；再对面板确认任务状态是不是已经终态但推送失败；最后核对你返回给对面的响应码，对面要求收到后回200，本地处理抛异常回了500，有的服务会判推送失败不再重发。

幂等键具体怎么设计，会不会重复生成？

用业务侧的唯一标识拼出来：店铺ID加SKU加图片哈希。同一件衣服同一张素材，天然就该是同一个任务，重提时对面识别到相同键返回原任务，不会二次扣费。注意键的生效窗口，有的服务只保留24小时，隔天重提要走查询接口先确认。

没有后端的小团队能直接用这类API吗？

能，但建议先用平台自带的批量后台顶一阵。回调接收、重试、记账这三样哪怕最简版也得有个常驻服务，纯前端凑合不了。真要上，用一个轻量函数计算服务接回调加一张云数据表，两三天能搭起来，别一上来就造完整系统。

延伸阅读

• 国内ai模特平台怎么选？摄影工作室老板的三类方案实测——选平台阶段的横向对比，和本文的对接实操正好一前一后。
• ai模特图评测：同一条裙子测了6家工具，可用率差三倍——接口跑得稳之外，图本身可用率同样决定成本。