Sora 2 API 模型解析指南
快速结论
- Sora 2 在单页中覆盖 Text-to-Video、Image-to-Video、R2V、Video Edit 四种流程。
- 页面支持参数对比与最小请求样例，便于快速验证和接口对接。
- 建议先在本页收敛参数，再迁移到生产 API。
核心能力
- 多模式统一调试：在一个页面内切换 Text-to-Video、Image-to-Video、R2V、Video Edit，快速比较效果。
- 参数可视化验证：围绕 prompt、时长、参考素材等关键参数做快速迭代，降低试错成本。
- 生产迁移友好：提供最小请求与响应结构，便于把验证过的参数直接迁移到正式 API。
适用场景
- 需要在多种视频生成模式之间快速做效果对比。
- 需要在接入前明确参数组合、输出稳定性和错误处理。
不适用场景
- 需要批量异步生产任务时，应直接使用服务端 API 工作流。
- 需要复杂权限与审计链路时，应优先走正式后端编排。
运行特性
- 当前模型解析页用于交互验证与参数预演。
- 运行结果区域显示示例结构，用于说明任务状态字段。
最小请求示例
{
"model": "sora-2",
"mode": "text-to-video",
"input": {
"prompt": "A cinematic city sunrise with soft fog and moving traffic.",
"duration": 5
}
}
最小响应示例
{
"task_id": "task_xxxxxxxx",
"model": "sora-2",
"mode": "text-to-video",
"status": "queued",
"created_at": "2026-04-15T00:00:00.000Z"
}
关键参数
| 参数 | 类型 | 必填 | 默认值 | 范围 | 说明 |
|---|
| model | string | 是 | gemini_omni | - | 模型标识，固定使用 gemini_omni。 |
| prompt | string | 是 | - | - | 描述目标视频的主体、动作、场景与风格。 |
| aspect_ratio | string | 否 | 16:9 | 16:9 | 9:16 |
| duration | integer | 否 | 6 | 6 | 10 |
| resolution | string | 否 | 720P | 720P | 输出分辨率，当前仅支持 720P；不传时按默认值处理。 |
常见错误
| HTTP | Code | 触发条件 | 修复建议 | 重试策略 |
|---|
| 400 | invalid_request_error | 请求体缺少必填字段或字段类型不匹配。 | 校验 model、mode、input 的字段完整性与类型。 | 修正参数后重试，不建议直接盲重试。 |
| 401 | authentication_error | 缺少 Authorization 头或 API Key 无效。 | 确认 Bearer Token 与密钥权限范围。 | 修复鉴权后重试；连续失败请轮换密钥。 |
| 429 | rate_limit_exceeded | 请求频率、并发或当前额度命中上游限流策略。 | 先做指数退避重试，并检查当前请求节奏、并发设置和额度使用情况。 | 建议指数退避（例如 1s/2s/4s）+ 抖动；连续触发时再收紧提交节奏。 |
| 500 | internal_error | 上游服务瞬时异常或内部处理失败。 | 记录 request id 并触发重试链路。 | 可短间隔重试 2-3 次，持续失败请升级人工排查。 |
FAQ
- Sora 2 适合哪些场景？
适合快速验证视频创意、多模式对比参数效果、以及在接入 API 前完成提示词与参数收敛。
- Text-to-Video 和 Image-to-Video 怎么选？
只有文字脚本时优先 Text-to-Video；已有构图或关键画面时优先 Image-to-Video。
- R2V 与 Video Edit 有什么区别？
R2V 更偏向参考素材驱动的新生成；Video Edit 更偏向在已有视频上做修改和增强。
- 图像视频模型报错：invalid apitype: -1
这类错误通常说明接口走错了。图像和视频模型一般不走 chat 接口，而是按对应文档发起 HTTP 任务请求，并通过任务状态接口轮询结果。排查时建议先看用户的实际请求代码、请求地址和请求体。
- 用户进行生成图片/视频的任务时出现任务失败，但是扣款
先让用户提供任务日志或截图，重点看是否出现了输入或输出 token 统计。如果有这类 token 记录，大概率是用户把图片/视频模型走成了 chat 接口；这不是正确用法。图片和视频模型通常是异步任务接口，需要通过 HTTP 请求先提交任务，再拿到任务 ID 轮询状态，详细以对应文档为准。
相关 API
