任务与错误

视频生成通常是异步任务。图片和语音接口可能在平台内部轮询上游任务，但对客户端通常表现为同步返回图片或音频。

视频任务状态

创建视频任务后，客户端用返回的 id 查询：

GET /v1/videos/{task_id}

建议 3 到 5 秒轮询一次。任务进入 completed 后，优先读取响应中的结果 URL；如需代理下载，使用：

GET /v1/videos/{task_id}/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"
  }
}

场景	处理方式
文本模型缺少 `messages`	调用 `/v1/chat/completions` 时传有效 `messages` 数组。
文本模型缺少 `input`	调用 `/v1/responses` 时传有效 `input`。
`prompt` 为空	补充有效提示词。
只传尾帧、不传首帧	同时传 `first_image_url` 和 `last_image_url`。
参考图数量超限	按模型能力表减少 `images` 或 `imageUrls` 数量。
模型不支持参考视频或音频	查看模型能力表，当前启用的视频模型支持参考视频和音频。
`mode` 值非法	使用 `auto`、`text-to-video`、`image-to-video`、`reference-to-video` 或 `start-end-to-video`；Sora v3 也兼容 `references` / `frames`。
模型不支持指定 `mode`	查看模型能力表，换用支持该能力的模型或改用自动识别。
指定 `mode` 但缺少输入	按该模式补齐必需字段，例如图生视频要传图片，首尾帧要同时传首帧和尾帧。
使用上游内部模型名	改用本平台模型值，如 `sora-v3-pro`。

视频生成通常是异步任务。图片和语音接口可能在平台内部轮询上游任务，但对客户端通常表现为同步返回图片或音频。

创建视频任务后，客户端用返回的 id 查询：

GET /v1/videos/{task_id}

建议 3 到 5 秒轮询一次。任务进入 completed 后，优先读取响应中的结果 URL；如需代理下载，使用：

GET /v1/videos/{task_id}/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"
  }
}

场景	处理方式
文本模型缺少 `messages`	调用 `/v1/chat/completions` 时传有效 `messages` 数组。
文本模型缺少 `input`	调用 `/v1/responses` 时传有效 `input`。
`prompt` 为空	补充有效提示词。
只传尾帧、不传首帧	同时传 `first_image_url` 和 `last_image_url`。
参考图数量超限	按模型能力表减少 `images` 或 `imageUrls` 数量。
模型不支持参考视频或音频	查看模型能力表，当前启用的视频模型支持参考视频和音频。
`mode` 值非法	使用 `auto`、`text-to-video`、`image-to-video`、`reference-to-video` 或 `start-end-to-video`；Sora v3 也兼容 `references` / `frames`。
模型不支持指定 `mode`	查看模型能力表，换用支持该能力的模型或改用自动识别。
指定 `mode` 但缺少输入	按该模式补齐必需字段，例如图生视频要传图片，首尾帧要同时传首帧和尾帧。
使用上游内部模型名	改用本平台模型值，如 `sora-v3-pro`。