概述
Sora 2 异步 API 采用标准的异步处理机制,适合需要更精细控制视频生成流程的场景。与同步流式 API 不同,异步 API 将视频生成分为三个独立步骤,让您可以更灵活地管理任务状态和下载时机。异步 API 特别适合批量处理、后台任务、以及需要长时间等待的场景。如果您需要实时进度反馈,建议使用同步流式 API。
核心特性
独立的任务管理
提交后获得任务 ID,可随时查询状态
灵活的轮询策略
自定义轮询间隔,避免不必要的请求
可靠的视频下载
生成完成后独立下载,支持断点续传
批量处理支持
同时提交多个任务,并发处理更高效
完整流程
异步 API 采用三步流程:典型生成时间:3-5 分钟。建议轮询间隔设置为 30 秒,最长等待时间设置为 10 分钟。
端点地址
第一步:提交视频生成请求
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | ✅ | 视频生成的文本描述,建议详细描述场景、动作、风格 |
model | string | ✅ | 固定值:sora-2 |
size | string | ✅ | 1280x720(横屏)或 720x1280(竖屏) |
seconds | string | ✅ | 视频时长,可选值:10 或 15 |
input_reference | file | ❌ | 参考图片文件(PNG/JPG/JPEG),可选,用于图生视频 |
文生视频示例
图生视频示例
支持上传参考图片,生成基于图片的视频。响应格式
第二步:轮询查询视频状态
提交请求后,需要定期轮询查询视频生成状态。请求方式
查询示例
状态说明
| 状态 | 说明 | 下一步操作 |
|---|---|---|
submitted | 请求已提交,等待处理 | 继续轮询查询 |
in_progress | 视频生成中 | 继续轮询查询,可查看进度百分比 |
completed | 视频生成完成 | 可以下载视频 |
failed | 视频生成失败 | 检查错误信息,重新提交 |
生成中的响应示例
完成后的响应示例
第三步:下载生成的视频
视频生成完成后(status 为 completed),可以下载视频文件。
请求方式
下载示例
视频文件可能在一段时间后过期,建议生成完成后立即下载并保存到本地。
完整流程示例
以下是完整的三步流程集成示例:最佳实践
Prompt 编写建议
好的 Prompt 应该包含:场景描述、主体动作、镜头风格、艺术风格。
参考图片建议
- 分辨率:建议 1280x720 或更高
- 格式:PNG 或 JPG
- 文件大小:< 10MB
- 内容:清晰、主体明确、光线良好
- 匹配度:图片内容应与 prompt 描述相关
轮询策略建议
推荐设置
- 轮询间隔:30 秒
- 最长等待:10 分钟(600 秒)
- 典型耗时:3-5 分钟
避免设置
- 轮询间隔:< 30 秒(可能触发限流)
- 最长等待:< 5 分钟(可能提前放弃)
错误重试策略
配额和限制
| 限制项 | 值 | 说明 |
|---|---|---|
| 请求速率 | 10 次/分钟 | 超过会返回 429 错误 |
| 并发任务 | 5 个 | 同时处理的视频数量 |
| 视频时长 | 10 或 15 秒 | 不支持其他时长 |
| 图片大小 | < 10MB | 建议 < 5MB |
| Prompt 长度 | < 1000 字符 | 建议 100-300 字符 |
错误处理
常见错误码
| 状态码 | 说明 | 解决方案 |
|---|---|---|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 检查必填参数是否完整 |
| 401 | 认证失败 | 检查 API Key 是否正确 |
| 403 | 无权限 | 检查 API Key 是否有效或余额不足 |
| 404 | 资源不存在 | 检查 video_id 是否正确 |
| 429 | 请求过于频繁 | 增加轮询间隔 |
| 500 | 服务器错误 | 稍后重试 |
常见问题
视频生成需要多长时间?
视频生成需要多长时间?
通常需要 3-5 分钟,具体时间取决于服务器负载和视频复杂度。建议设置轮询间隔为 30 秒,最长等待时间为 10 分钟。
异步 API 和同步 API 有什么区别?
异步 API 和同步 API 有什么区别?
- 异步 API:三步流程(提交→轮询→下载),适合批量处理和后台任务,需要自己管理轮询逻辑
- 同步 API:流式输出,实时返回进度,适合需要即时反馈的场景
可以同时提交多个视频生成任务吗?
可以同时提交多个视频生成任务吗?
可以,支持最多 50 个并发任务(不够用可以联系技术客服加)。您可以同时提交多个请求,分别轮询它们的状态。注意不要超过请求速率限制(10 次/分钟)。
视频文件会保存多久?
视频文件会保存多久?
建议视频生成完成后立即下载,避免文件过期。具体保存时长请咨询技术支持。
生成失败如何处理?
生成失败如何处理?
检查响应中的错误信息,常见原因:
- 内容违规(修改 prompt 或更换图片)
- 配额不足(充值或升级套餐)
- 参数错误(检查参数格式和值)
- 服务器负载过高(稍后重试)
如何控制视频的横竖屏?
如何控制视频的横竖屏?
通过
size 参数控制:1280x720:横屏720x1280:竖屏