先看错误发生在哪一步

创建接口的 HTTP 成功只说明任务已被接受，不表示生成完成。统一视频通过 status 判断；Responses 同时关注响应状态和任务元数据。先保存任务 ID，再根据统一查询或Responses 查询处理。

情况处理建议
HTTP 400 或参数校验错误检查 JSON、动作对应的 model、seconds、resolution、metadata 类型与素材数量
HTTP 401/403检查 Bearer 后的空格、Key 有效性、分组权限及任务归属
HTTP 404检查本站路由和 ID，不能拿厂商原生路径或私有 task_id 查询本站
HTTP 413压缩图片或改用 URL；检查 multipart 15MiB 和上游请求体限制
HTTP 429放慢请求，采用退避，不要反复创建相同任务
HTTP 5xx / 网络超时先确认是否已有任务 ID；保存错误正文后重试查询，避免重复创建
status=failed查看 error.message/code 或 Responses error，定位异步失败原因
Responses incomplete当前观察不完整，不能直接认定生成失败，继续查询原响应

这些 HTTP 状态是排查方向，不是对所有上游错误映射的固定承诺。实际结构与状态以本站响应为准。

常见模型与参数问题

  • 新型号返回 ModelUnavailable：先请求 GET /v1/models，确认当前 Key、分组和动作已开放；官方页面列出型号不等于本站已上架。
  • vidu2.0 does not support text-to-video：没有可识别的顶层图片，或只写了 metadata.subjects。主体请求请选择当前动作允许的型号。
  • viduq1 duration must be 5：当前插件旧组合只能使用 5 秒、1080p；不要把此限制直接复制给 Q1 Classic 或 Q3。
  • vidu2.0 duration 8 only allows resolution 720p：图生/首尾帧的 8 秒任务须显式指定 720p；参考接口仍只能用当前表格列出的 4 秒组合。
  • viduq2 duration must be between 1 and 10：当前插件的基础 Q2 使用 1–10 的整数；Q2 Pro/Turbo 的官方组合另行核对。
  • metadata must be a JSON object string：multipart 中的 metadata 必须是合法 JSON 对象字符串；不能提交数组。
  • input is required：Responses 没有解析出文字或图片。metadata.subjects 不能替代顶层 input 的检查。

一张参考图变成图生、两张参考图变成首尾帧时，检查 metadata.action 是否明确为 reference_to_video。不要用模型名替换来绕过动作限制。

上游错误码

上游异步失败可能携带下列 err_code。统一格式在可用时将其放入 error.code/message；厂商积分不足不等同于用户青云账户余额不足。

官方错误码含义与建议
FieldLacking、FieldInvalid、FieldItemCountOutOfRange缺字段、值无效或数量越界，检查该动作的参数表
ImageDownloadFailure上游无法下载图片；换成公开、可直连的图片 URL
ImageFormatInvalid、ImageSizeInvalid、PageSizeOutOfRange图片格式、像素、体积或比例不合要求
ModelUnavailable上游模型不可用，保存模型和任务 ID 联系本站支持
CreditInsufficient上游积分不足，保留任务 ID 联系本站支持
QuotaExceeded、TooManyRequests、SystemThrottling并发或频率限制，采用退避
AuditSubmitIllegal、CreationPolicyViolation、AuditFailed输入或生成内容未通过审核，调整素材或提示词
TaskNotFound、CreationNotFound任务或产物找不到，检查标识、归属和文件有效期

完整列表见Vidu 官方错误码。向支持提供时间、模型、公开任务 ID 和脱敏错误正文，不提供完整 API Key。

回调的范围与签名

metadata.callback_url 会交给 Vidu 上游，并不是由本站统一包装的 webhook。官方回调结构与 Get Generation 结果一致，涉及 processing、success、failed 状态；不要假设回调 ID 就是本站公开任务 ID。

Vidu 官方签名使用 HMAC-SHA256，密钥来自创建上游任务所用的厂商凭据。通过本站调用时，客户端的青云 API Key 不是该签名密钥，不能套用它验签。详见官方回调签名。

建议以本站查询接口确认最终状态。无法验证回调来源时，不要仅根据回调触发业务操作，请使用已保存的本站任务 ID 查询。

任务取消和过期

本目录视频接口不提供取消任务入口。HTTP 超时、SSE 断线或停止轮询不等于取消任务。厂商直连的低峰取消、处理时限和退款规则不作为本站服务承诺。

下载地址可能过期，成功后请及时保存。状态暂时无法识别时可能返回 unknown，遇到这类情况应保留任务 ID 排查，不要当成成功或自动退款。