异步端点:
https://api2.laozhang.ai/v1/videos调用方式: 三步骤(创建任务 → 查询状态 → 获取视频)优势: 更稳定 | 任务队列 | 支持长时任务为什么选择异步 API?
更高稳定性
基于任务队列,避免长连接超时问题
失败计费以控制台记录为准 ⭐
重大优势:任何原因失败都计费以控制台记录为准
- ✓ 内容违规 → 计费以控制台记录为准
- ✓ 队列超时 → 计费以控制台记录为准
- ✓ 生成失败 → 计费以控制台记录为准
灵活轮询
可随时查询任务状态和进度
参数化控制
分辨率和时长通过参数指定,更灵活
同步 vs 异步对比
快速开始
异步调用分为三个步骤:1
创建视频任务
POST 请求创建任务,获取任务 ID
2
查询任务状态
定期轮询查询生成进度
3
下载视频
任务完成后获取视频文件
完整示例
API 端点详解
1. 创建视频任务
POST
https://api2.laozhang.ai/v1/videos创建一个新的视频生成任务请求参数
模型选择
sora-2:基础模型,720P分辨率,稳定性极高,$0.15/次sora-2-pro:高清HD模型,1080P分辨率,生成时间约10分钟,$0.8/次
响应字段
2. 查询任务状态
GET
https://api2.laozhang.ai/v1/videos/{video_id}查询视频生成任务的当前状态和进度路径参数
响应字段
任务状态说明
3. 获取视频内容
GET
https://api2.laozhang.ai/v1/videos/{video_id}/content下载已完成的视频文件路径参数
响应
返回视频文件的二进制流(MP4 格式)完整代码示例
Python 示例(含轮询逻辑)
JavaScript/Node.js 示例
最佳实践
轮询间隔设置
轮询间隔设置
推荐轮询间隔:3-5 秒原因:
- 视频生成通常需要 2-5 分钟
- 3-5 秒可以及时反馈进度
- 避免过于频繁的请求
超时处理
超时处理
推荐超时设置:10 分钟(600秒)注意:
- 任务超时不会自动取消
- 可以稍后继续查询同一个 video_id
- 任务有效期为 24 小时
错误重试策略
错误重试策略
建议重试逻辑:重试场景:
- ✓ 网络错误 → 重试
- ✓ 服务繁忙 (503) → 重试
- ✗ 内容违规 → 不要重试,修改提示词
- ✗ 余额不足 → 不要重试,确认账户额度后再试
批量生成优化
批量生成优化
并发控制建议:建议:
- 创建任务:可以高并发(10-30个)
- 查询状态:建议并发数 ≤ 10
- 下载视频:建议并发数 ≤ 5
定价说明
异步 API 与同步 API 价格完全相同,按次计费。
计费规则:
- ✓ 计费以控制台订单状态为准
- 异常、超时、取消、内容安全问题均以控制台记录为准
- 查询状态是否计费以控制台记录为准
常见问题
任务的有效期是多久?
任务的有效期是多久?
任务有效期:24 小时
- 创建任务后,
expires_at字段显示过期时间 - 24 小时内可随时查询任务状态
- 视频生成完成后,文件保存 24 小时
- 超过 24 小时后,任务和视频将被自动清理
- 视频生成完成后立即下载
- 不要依赖服务器长期存储
如何取消正在生成的任务?
如何取消正在生成的任务?
当前不支持手动取消任务
- 任务一旦创建,会自动排队执行
- 如果不再需要,直接忽略即可
- 未完成的任务计费以控制台记录为准
- 等待任务自然完成或失败
- 24 小时后任务自动过期
查询时返回 404 是什么原因?
查询时返回 404 是什么原因?
可能的原因:
- video_id 错误 - 检查是否复制完整
- 任务已过期 - 超过 24 小时
- 网络问题 - 重试请求
异步和同步 API 可以混用吗?
异步和同步 API 可以混用吗?
可以混用,完全独立两个 API 系统完全独立:
- 不同的端点
- 不同的调用方式
- 相同的定价
- 共享同一个 API Key 和余额
- 快速测试 → 使用同步 API
- 生产环境 → 使用异步 API(更稳定)
- 批量生成 → 使用异步 API
为什么 progress 字段突然不变了?
为什么 progress 字段突然不变了?
可能的原因:
- 正常现象 - 某些处理阶段进度更新较慢
- 队列等待 - 高峰期可能在排队
- 生成卡住 - 极少数情况下任务可能卡住
- 继续等待 5-10 分钟
- 如果超过 10 分钟无变化,联系技术支持
- 提供 video_id 以便排查
图生视频支持图片URL吗?
图生视频支持图片URL吗?
不支持!仅支持本地图片文件上传。正确做法:不支持:
- ✗ 图片URL
- ✗ Base64编码
- ✗ 在线图片链接
multipart/form-data 格式上传,仅支持本地文件流。图生视频支持哪些格式?
图生视频支持哪些格式?
支持的图片格式:
- ✓ JPG / JPEG
- ✓ PNG
- ✓ WebP
- 文件大小: < 5MB(推荐)
- 分辨率: 建议 1280x720 或相近比例
- 来源: 必须是本地文件
图生视频时prompt是必填的吗?
图生视频时prompt是必填的吗?
是的,prompt 参数必填!即使你只是想让图片”自然地动起来”,也需要提供描述:推荐的简单prompt:更具体的prompt效果更好:
图生视频比文生视频贵吗?
图生视频比文生视频贵吗?
价格完全相同!
计费说明:
- 图生视频和文生视频价格一样
- 计费以控制台订单状态为准
- 失败计费以控制台记录为准(包括图片格式错误、内容违规等)
图片会影响视频生成时间吗?
图片会影响视频生成时间吗?
几乎没有影响。图生视频和文生视频的生成时间基本相同:
- 通常时间: 2-5 分钟
- 影响因素: 视频时长、队列长度、复杂度
- 建议 < 5MB:上传快,处理快
- 过大图片:仅影响上传时间(几秒),对生成时间无明显影响
错误处理
常见错误码
错误响应格式
技术支持
需要帮助?
如有问题,欢迎联系我们:
- 邮箱: hi@laozhang.ai
- Telegram: https://t.me/laozhang_cn
- 文档: https://docs.laozhang.ai
下一步
同步 API
查看同步调用方式
使用示例
查看更多应用示例
模型定价
了解详细定价信息
常见问题
查看更多问题解答