异步任务
七个状态、轮询策略、幂等键、取消与退费、产物链接的有效期。
内容最后核对: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 给出状态迁移的时间线(谁在什么时候把它推到了哪个状态)。排「为什么卡住」比看最终状态有用得多:能区分「一直没被上游受理」与「上游跑完但我们没收到」。