异步任务通用说明：视频、音乐、图片怎么拿结果

一句话：视频、音乐、部分图片接口不即时返回，都是「提交 → 轮询 → 读结果」三步。看懂这一页，所有异步接口都能接。
整理日期：2026-10-18 ｜相关：配置报错对照表 · 按任务选模型

一、哪些接口是异步的

类型	是否异步	典型模型 / 通道
视频生成	✅ 异步	`MiniMax-H3`、`kling-video`、`viduq3-pro`、海螺、即梦、豆包、veo、sora
音乐生成	✅ 异步	Suno 系列
图片生成（部分）	⚠️ 混合	Nano Banana、gpt-image 多为同步返回；部分通道走异步任务
对话 / Embeddings	❌ 同步	直接返回结果

判断依据很简单：如果接口文档里出现 task_id，它就是异步的。

二、三步流程

1. 提交任务（POST）→ 拿到 task_id 或 taskBatchId
2. 轮询查询（GET）→ status: pending / processing / succeed / failed
3. 终态后读 result URL 或产物列表

三个容易踩错的点：

点	说明
提交和查询必须成对	有提交路径就有一个对应的查询路径，不能拿 A 的 ID 去 B 的路径查
终态才读结果	只有 `succeed` 才去取 URL；`processing` 时结果字段是空的
不要靠单次请求等出片	视频经常要几分钟，靠延长 timeout 等结果必然超时，正确做法是轮询

三、状态机

状态	含义	该做什么
`pending` / `queued`	排队中	继续轮询
`processing` / `running`	生成中	继续轮询
`succeed` / `success` / `completed`	成功	读结果字段
`failed` / `error`	失败	读 `message` / `error` / `fail_reason`

⚠️ 各平台的字段名不完全一样。同名状态在不同通道可能叫 succeed 或 completed，判断时用「包含匹配」而不是等号。

四、轮询怎么设才不亏

参数	建议值	原因
间隔	3–10 秒	低于 1 秒是无效请求，既花钱又可能触发限流
总超时	10–30 分钟	视频类常见几分钟，设太长会挂着不放
并发	少量	批量出片时按队列跑，别一次打几十个
幂等	复用已有 `task_id`	超时重试前先查一次，避免重复提交多扣费

一个实用的退避策略：前 3 次每 3 秒查一次，之后每 10 秒，超过 10 分钟按失败处理。

五、Open 格式 vs Legacy 格式（最容易混）

部分平台同时存在两套响应格式：

类型	任务 ID 字段	特征
Open 格式	`taskBatchId`	较新的统一封装
Legacy 格式	`data.task_id`	沿用厂商原生结构

规则：提交用哪套，查询就必须用哪套。混用会报 task_not_exist 或直接 404。

珂艾的「品牌平台」目录下多为 Open 格式，「视频模型 / 绘画模型」下多为 Legacy 格式。以具体接口文档为准。

六、错误对照表

异步场景的特殊性：业务失败常常仍返回 HTTP 200，错误写在 JSON 里。只看状态码会误判成功。

现象	可能原因	怎么办
HTTP 200 但 body 报错	业务失败写在 JSON 内	解析 `success` / `code` / `message` / `error`，别只看状态码
响应体以 `<` 开头	地址或路径填错，返回了网页 HTML	确认 base_url 与平台前缀（如 `/kling/v1/...`、`/suno/...`），响应必须是 JSON
`401`	密钥无效 / 未传 Authorization	用 `Authorization: Bearer sk-...`
`403`	无权限、令牌不含该模型、分组不允许	检查令牌可用模型与分组
`400` / `invalid_request`	参数缺失、类型错、JSON 解析失败	对照接口文档的必填项与枚举值
`404` / `task_not_exist`	路径错，或 ID 不存在 / 不属于当前密钥	核对路径；用提交时返回的 ID
`429`	触发限流	退避重试，降低轮询频率
客户端超时（408）	提交或轮询的 timeout 太短	提交可稍大；生成本身靠轮询，别指望单次等出片
`502` / `503` / `504`	网关或上游临时不可用	指数退避重试；高峰期降并发或换模型
模型不存在 / 无可用渠道	模型名错，或分组里没有这个渠道	对照控制台模型列表与令牌分组
余额 / 额度不足	预扣费失败	充值或提高令牌额度
提交成功但一直 pending	上游排队或拥堵	继续轮询；超过总超时带任务 ID 联系客服
任务超时失败	超过平台任务上限	看 `fail_reason`；失败终态通常退还预扣额度，别重复高频重提
终态 failed	生成失败、参数不合规、内容审核	读具体文案，改 prompt 或素材后重试
参考图 / 素材 URL 失效	图床临时链接过期，上游拉不到	换成可公网访问的稳定地址
图生任务失败	图片过大、格式不支持	压缩或转码后再提交
轮询路径 404	提交与查询不成对	成对使用提交 + 查询路径
重复提交同一任务	超时重试导致多扣费	先查已有 `task_id`，确认没跑成功再重提

七、拿到结果之后

终态为成功时，结果通常在以下几个位置之一：

位置	说明
`result.video_url` / `result.image_url`	直接的产物链接
`data.output` 数组	多产物时是列表
`data.clips[]`	Suno 类，每段音频一个 clip

这些链接通常有时效（几小时到几天）。要做长期存储的话，拿到就该转存到自己的对象存储或图床，别直接对外暴露临时链接。

八、一个最小可跑的轮询伪代码

路径与字段名以具体接口文档为准，上面这段主要是演示「提交 → 轮询 → 判终态」的骨架。

九、相关阅读

全部报错排查：配置报错对照表

视频模型怎么选：按任务选模型

单个视频模型详情：MiniMax H3 模型介绍

图床问题：自建图床 API

十、更新记录

日期	改了什么
2026-10-18	首次发布。覆盖提交、轮询、终态读取全流程，附轮询伪代码与 20 余条错误对照

异步任务通用说明：视频、音乐、图片怎么拿结果

一、哪些接口是异步的#

二、三步流程#

三、状态机#

四、轮询怎么设才不亏#

五、Open 格式 vs Legacy 格式（最容易混）#

六、错误对照表#

七、拿到结果之后#

八、一个最小可跑的轮询伪代码#

九、相关阅读#

十、更新记录#