标准调用顺序
提交任务
调用具体能力的创建接口,同时判断 HTTP 状态、success 和 code。成功后立即保存 data.task_id。
查询对应任务类型
图片任务使用image_generation_query,视频任务使用 video_generation_query,其他能力使用 API 参考中的同类查询接口。不要拿图片任务 ID 查询视频任务。
等待终态
0 和 2 都是非终态;继续轮询但应逐步放慢。1 和 -1 是终态,收到后停止轮询。
处理结果或失败
status=1 时读取当前接口定义的结果字段;status=-1 时读取 error_message,修正原因后再创建新任务。
任务状态
单任务与批量查询
- 单任务查询适合用户正在等待某一个结果的交互页面。
- 批量查询适合后台作业或任务列表;提交
task_ids数组,一次最多 100 个 ID。 - 批量结果只包含当前应用与用户可访问的任务;不要只依赖数组位置匹配,应用
task_id建立索引。
安全轮询
JavaScript
注意
创建请求超时或网络中断时,结果可能处于“不确定”状态。若无法确认任务是否已创建,不要立即无限重放创建请求;先检查已有任务记录,必要时携带 requestId 联系支持。
使用 Webhook 接收终态
配置回调地址后,任务成功会发送task.completed,任务失败会发送 task.failed。事件 data 至少包含 task_id、status 和 error_message,成功时还会合并任务结果字段。
Webhook 适合减少轮询,但接收端必须验签、按 event_id 幂等并返回正确确认响应。为应对网络抖动,业务仍可在收到事件后调用对应查询接口核对最终结果。详见Webhook 事件目录。
常见误区
status=0 是失败吗?
不是。它表示任务等待处理。只有status=-1 才表示任务失败。
为什么 success=true 但还没有结果 URL?
创建接口的成功响应仅确认任务已创建。最终产物由查询接口在status=1 后返回。
任务一直是 0 或 2 怎么办?
保持退避轮询,不要重复创建。若超过你的业务等待上限,保存task_id 和最近一次 requestId 后联系支持。