轮询是异步任务唯一稳定可靠的获取结果方式。因扣子平台不支持websocket或sse回调,需通过get /task/{id}/status接口轮询,返回标准状态与进度,并采用指数退避策略控制请求频率,及时终止已完成或失败任务的轮询。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

当扣子工作流执行图像生成、视频渲染或批量数据处理等耗时超过5分钟的任务时,必须放弃同步等待模式,否则用户会看到“任务处理超时”并中断流程,后台任务实际仍在运行却无人知晓结果。
为什么轮询是异步任务的必选项
异步任务提交后,工作流立即返回任务ID,但系统不会主动通知你结果;不轮询,你就永远不知道任务是否完成、失败还是卡死。轮询不是“多此一举”,而是唯一能闭环的关键链路——就像快递已发出,你得自己查物流,而不是干等门铃响。
扣子平台不支持WebSocket推送或SSE回调,外部渠道(如飞书、微信)更无回调能力,【轮询是当前唯一稳定可靠的获取结果方式】。
设计轮询接口:三要素缺一不可
第一步:在你的后端服务中暴露一个 GET /task/{id}/status 接口,返回标准 JSON 结构:{"status":"RUNNING","progress":35,"message":"正在渲染第12/20帧"} 或 {"status":"COMPLETED","result_url":"https://xxx.png"}。
第二步:状态字段必须包含 RUNNING / PROCESSING / COMPLETED / FAILED 四种值,不能用 pending、wait 等非标准命名,否则前端解析会出错。
第三步:接口必须支持 HTTP 200 响应码返回所有状态,禁止对 FAILED 状态返回 4xx/5xx,否则前端轮询库可能直接终止重试。
前端轮询实现:控制节奏与防雪崩
方法一:指数退避轮询(推荐)
初始间隔 2 秒 → 失败或 RUNNING 则翻倍(4s→8s→16s)→ 最大间隔不超过 60 秒 → 连续 5 次无变化自动终止。这样既避免高频请求压垮后端,又能在任务快完成时及时捕获结果。
方法二:固定间隔轮询(仅用于调试)
每 5 秒发起一次请求,简单直接,但上线后容易触发限流,尤其在并发量超过 200 时,后端 CPU 会飙升到 95% 以上。
【切勿在前端使用 setInterval 无限轮询而不设退出条件】——用户切走页面、关闭标签页后,定时器仍运行,造成无效请求堆积。
轮询结果处理:区分状态并终止循环
收到 status=COMPLETED 时,提取 result_url 渲染图片,并立即清除轮询定时器;收到 status=FAILED 时,显示错误 message 并停止;若 status 长期为 RUNNING 且 progress 停滞超过 3 分钟,主动标记为“疑似卡死”,提示用户联系管理员。
轮询过程中,前端必须显示实时 progress 百分比和 message 文本,而不是只转圈——用户需要感知进度,不是猜谜。
一旦收到 COMPLETED 或 FAILED,必须调用 clearInterval() 或 AbortController.abort() 彻底终止所有待发请求,【未清理的轮询会持续发送,直到页面关闭】。











