图片、视频、文案、数字人、数字声音、音乐和部分内容分析接口会先返回任务 ID,再异步完成处理。创建请求成功只表示平台已接收任务,不表示最终产物已经生成。

标准调用顺序

提交任务

调用具体能力的创建接口,同时判断 HTTP 状态、successcode。成功后立即保存 data.task_id

查询对应任务类型

图片任务使用 image_generation_query,视频任务使用 video_generation_query,其他能力使用 API 参考中的同类查询接口。不要拿图片任务 ID 查询视频任务。

等待终态

02 都是非终态;继续轮询但应逐步放慢。1-1 是终态,收到后停止轮询。

处理结果或失败

status=1 时读取当前接口定义的结果字段;status=-1 时读取 error_message,修正原因后再创建新任务。

任务状态

单任务与批量查询

  • 单任务查询适合用户正在等待某一个结果的交互页面。
  • 批量查询适合后台作业或任务列表;提交 task_ids 数组,一次最多 100 个 ID。
  • 批量结果只包含当前应用与用户可访问的任务;不要只依赖数组位置匹配,应用 task_id 建立索引。

安全轮询

JavaScript
注意 创建请求超时或网络中断时,结果可能处于“不确定”状态。若无法确认任务是否已创建,不要立即无限重放创建请求;先检查已有任务记录,必要时携带 requestId 联系支持。

使用 Webhook 接收终态

配置回调地址后,任务成功会发送 task.completed,任务失败会发送 task.failed。事件 data 至少包含 task_idstatuserror_message,成功时还会合并任务结果字段。 Webhook 适合减少轮询,但接收端必须验签、按 event_id 幂等并返回正确确认响应。为应对网络抖动,业务仍可在收到事件后调用对应查询接口核对最终结果。详见Webhook 事件目录

常见误区

status=0 是失败吗?

不是。它表示任务等待处理。只有 status=-1 才表示任务失败。

为什么 success=true 但还没有结果 URL?

创建接口的成功响应仅确认任务已创建。最终产物由查询接口在 status=1 后返回。

任务一直是 0 或 2 怎么办?

保持退避轮询,不要重复创建。若超过你的业务等待上限,保存 task_id 和最近一次 requestId 后联系支持。