异步任务通用说明

适用于视频生成、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 状态码及其含义。