异步任务通用说明
适用于视频生成、Suno 音乐、Kling 等 非即时返回 的接口。
标准流程
1. 提交任务（POST）→ 获得 task_id / task_batch_id
2. 轮询查询（GET）→ status: pending / processing / succeed / failed
3. 终态后读取 result URL 或产物列表
状态机（概念）
| 状态 | 含义 |
|---|---|
| pending / processing | 进行中，继续轮询 |
| succeed / success | 成功，读取结果字段 |
| failed / error | 失败，查看 message / error |
各平台字段名可能不同，以门户该接口 OpenAPI 响应 schema 为准。
轮询建议
- 间隔：3–10 秒（勿低于 1 秒高频轰炸）
- 超时：业务侧设置总超时（如 10–30 分钟）
- 幂等：同一
task_id可重复查询，勿重复提交相同任务除非文档允许
Open 格式 vs Legacy 格式
部分平台存在两套响应：
| 类型 | 任务 ID 字段示例 |
|---|---|
| Open | taskBatchId |
| Legacy | data 内 task_id |
文档元信息中会标注「适用协议」；勿混用轮询路径。
平台专题
| 平台 | 文档 |
|---|---|
| VEO / 统一视频 | 统一视频 VEO 接口文档 |
| Suno | Suno 接口文档 |
| Kling | 可灵 Kling 接口文档 |
常见错误
汇总自入门指南、HTTP 状态码、各平台 Quick Start / OpenAPI x-error-playbook，以及异步轮询侧常见现象。业务错误有时仍返回 HTTP 200，错误写在 JSON 的 message / error / fail_reason 中——勿只看状态码。
| 现象 | 可能原因 | 建议 |
|---|---|---|
invalid character '<' looking for beginning of value（或响应体以 < 开头） |
Base URL / 路径填错，返回了 HTML 登录页或官网页 | 确认网关地址与平台前缀（如 /suno/...、/kling/v1/...、/v1/video/...），响应须为 JSON |
| 401 | API Key 无效、过期、未传 Authorization |
使用 Bearer sk-...；在控制台确认令牌状态 |
| 403 | 无权限、令牌模型限制、分组不允许、IP 不在白名单 | 检查令牌可用模型 / 分组 / allow_ips |
400 / invalid_request |
参数缺失、类型错误、JSON 无法解析 | 对照该接口 OpenAPI 的 required / enum / 示例 |
404 / task_not_exist |
路径错误，或 task_id 不存在 / 不属于当前 Key |
核对 path；确认提交返回的 ID，勿用错字段 |
| 429 | 触发限流 | 退避重试；降低并发与轮询频率（建议 3–10s） |
| 408 / 客户端超时 | 提交或轮询 HTTP 超时过短 | 提交可适当加大 timeout；生成本身靠轮询，勿指望单次请求等出片 |
| 502 / 503 / 504 | 网关或上游暂不可用 / 超时 | 指数退避重试；高峰期降并发或换模型 |
| HTTP 200 但 body 报错 | 业务失败写在 JSON 内 | 解析 success / code / message / error，勿仅凭 HTTP 码判断成功 |
模型不存在 / 无可用渠道 (channel_not_found) |
模型名拼写错误，或当前分组/令牌无对应渠道 | 对照控制台「支持模型」与令牌分组；必要时换分组或模型 |
| 余额 / 额度不足 | 预扣费失败 | 充值或提高令牌额度后再提交 |
枚举 literal_error |
请求体 enum（如 Suno mv）不在上游允许列表 |
对照接口文档 enum / x-error-playbook 与渠道实测 |
| Open / Legacy 字段混用 | 用错任务 ID 字段或轮询路径 | Open 侧常见 taskBatchId；Legacy 常见 data.task_id；提交与查询必须成对、协议一致 |
task_id 与 clip_id 混用（Suno 等） |
轮询用了续写 ID，或续写用了任务 ID | 轮询用提交返回的 task_id；续写 / 补段用 fetch 结果中的 clip_id |
| 提交成功但一直 pending / processing | 上游排队、渠道拥堵或异常 | 按建议间隔继续轮询；业务侧设总超时（如 10–30 分钟）；持续异常带任务 ID 联系运维查渠道日志 |
任务超时失败（fail_reason 含 timed out 等） |
超过平台任务超时（常见约数十分钟量级） | 查看 fail_reason；失败终态通常会退还本次预扣额度；勿重复高频重提同一失败任务 |
终态 failed / error |
上游生成失败、参数不合规、内容审核等 | 读 message / error / fail_reason；按文案改 prompt / 素材后重试 |
| 参考图 / 素材 URL 失效 | 图床临时链过期，上游拉取失败 | 换可公网访问的稳定地址，或按图床说明转存后再传 |
| 图生 / 多模态任务失败 | 图片过大、非图片 MIME、格式不受支持 | 按接口限制压缩与转码后再提交 |
| 轮询路径 404 或状态字段为空 | 提交接口与查询接口不成对（如 Kling 各任务类型 path 不同） | 以门户该操作的 OpenAPI 为准，成对使用提交 + 查询 path |
| 重复提交同一任务 | 客户端超时后重试导致多扣费 / 多任务 | 同一业务请求先查已有 task_id；仅在文档允许时重新提交 |
更多平台专属排错见各接口 OpenAPI 的 x-error-playbook，以及 HTTP 状态码及其含义。