文档目录

异步任务

七个状态、轮询策略、幂等键、取消与退费、产物链接的有效期。

内容最后核对:2026-11-18

本页目录

哪些是异步的

能力形态拿结果
文本 / 图片 / 语音转写同步响应里直接有
语音合成同步响应体是音频字节
视频异步提交拿 id,轮询到终态
音乐异步同上

同步接口没有「任务」这个概念:请求返回时结果已经产生,费用当场结算。

任务的七个状态

异步任务只有这七个状态。控制台与通用格式用这套名字,四种视频格式各用自己的词表达(映射表在视频 API)。

状态含义终态下一步
QUEUED已受理,排队中否等
RUNNING上游在生成否等
VERIFIED完成且产物可下载是取产物
LINK_EXPIRED生成成功,但产物链接过期是refresh-url 换新链接
FAILED上游失败是看 failCode / failDetail
SUBMIT_FAILED提交阶段就失败,预扣已全额释放是按 error.message 改参数后重提
CANCELED已取消是看退费政策

三条判据:

  • 能不能停止轮询,只看是否终态。 不要按某一个格式的字符串猜。
  • 未知状态一律当「还在跑」。 把一次网络抖动当成失败会让你重提,那是第二笔钱。
  • VERIFIED 之后链接仍会被复查,所以它可能转成 LINK_EXPIRED。状态没变不代表链接一定能下。

轮询怎么做

  • 间隔 5 秒起步,30 秒封顶。任务动辄几十秒,网关每 5 秒检查一次上游进度,比它更勤不会更快。
  • 用指数退避而不是固定 1 秒:固定高频轮询只增加你自己的 QPS 与日志量。
  • 每次查询都是幂等的 GET,失败随便重试 —— 但提交不是。
  • 一直 QUEUED 超过 10 分钟,看控制台「异步任务」页的 upstreamId:任务可能在上游排队,那不是网关能加速的。

幂等:提交必须带键

视频与音乐的提交是真扣费。没有幂等键时,超时后的第一次重试就是一笔新订单、一笔新冻结,而响应看起来完全正常(一个新的 task_id)。

curl -s "$BASE/v1/video/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: order-20261118-0001" \
  -H 'Content-Type: application/json' \
  -d '{"model":"<视频模型>","prompt":"窗台上的橘猫","duration":5}'
  • 键由你生成并保持一致(订单号、业务主键都行),不要每轮重试换一个新的。
  • 同一个键、同一个请求体 → 返回同一个任务;同一个键、不同请求体 → 409。
  • 留空 = 每次重试都真下一单。这一条比其它所有重试建议都重要。

请求体里的 idempotencyKey 与请求头 Idempotency-Key 都认。

取消与退费

取消有两个入口:DELETE /v1/videos/{id}(API Key)与控制台 POST /api/jobs/{id}/cancel。

退不退钱取决于上游:有的提交即计费、取消不退,有的可退。规则由各家上游自己决定,不由接口决定 —— 所以同一个取消动作,在不同模型上结果不同。取消后看 settleStatus 确认到底退没退。

产物与链接

  • 网关不长期保存产物:任务返回的是上游链接,有有效期(resultExpiresAt / Sora 形状的 expires_at)。
  • 拿到就下载,别把链接当成永久地址保存。
  • 过期用 POST /v1/videos/{id}/refresh-url 续期;上游已删产物时会失败,那时只能重新生成。
  • 要字节可以直接走 /content(视频是 GET /v1/videos/{id}/content),网关代为拉取一次,你的出口 IP 不会出现在上游的访问记录里。

事件流水

控制台的 GET /api/jobs/{id}/events 给出状态迁移的时间线(谁在什么时候把它推到了哪个状态)。排「为什么卡住」比看最终状态有用得多:能区分「一直没被上游受理」与「上游跑完但我们没收到」。