任务与错误
视频异步任务状态、轮询方式和常见错误
视频和部分图片生成采用异步任务；语音接口通常同步返回音频。
视频任务状态
| 状态 | 含义 |
|---|---|
queued | 已创建，等待执行。 |
in_progress | 上游正在处理。 |
completed | 已完成，可以读取结果或内容。 |
failed | 任务失败，查看 error。 |
unknown | 平台无法确定当前状态。 |
轮询建议
创建视频任务后，客户端用返回的 id 查询：
GET /v1/videos/{task_id}有公网 HTTPS 服务端时，可传 callbackUrl 接收成功或失败的终态通知，详见视频生成。纯客户端无法直接接收该 Webhook，可每 60 秒查询一次；应用回到前台或网络恢复后可立即查询。进行中的状态查询不会触发额外的上游状态轮询；高并发下仍会增加本站 API 和缓存负载。任务进入 completed 后，优先读取响应中的结果 URL；如需代理下载，使用：
GET /v1/videos/{task_id}/content/content 会传输视频文件，只在确认完成后调用，不要用它轮询状态。
错误响应
本平台错误响应兼容 OpenAI 风格：
{
"error": {
"message": "image input is required",
"type": "invalid_request_error",
"code": "invalid_request"
}
}视频任务失败时，任务对象里也可能包含错误：
{
"id": "task_xxx",
"object": "video",
"status": "failed",
"error": {
"message": "upstream task failed",
"code": "task_failed"
}
}常见 400 场景
| 场景 | 处理方式 |
|---|---|
文本模型缺少 messages | 调用 /v1/chat/completions 时传有效 messages 数组。 |
文本模型缺少 input | 调用 /v1/responses 时传有效 input。 |
prompt 为空 | 补充有效提示词。 |
| 只传尾帧、不传首帧 | 同时传 firstFrameUrl 和 lastFrameUrl。 |
| 参考图数量超限 | 按模型能力表减少 imageUrls 数量。 |
| 模型不支持参考视频或音频 | 查看模型能力表，当前启用的视频模型支持参考视频和音频。 |
generationType 值非法 | 使用 auto、text-to-video、image-to-video、reference-to-video、start-end-to-video、edit-video 或 video-extension。 |
| 模型不支持指定生成类型 | 查看模型能力表，换用支持该能力的模型或改用自动识别。 |
| 指定生成类型但缺少输入 | 按该类型补齐必需字段，例如图生视频要传图片，首尾帧要同时传首帧和尾帧。 |
| 使用上游内部模型名 | 改用本平台模型值，如 sora-v3-pro。 |