异步端点:
https://api.laozhang.ai/v1/videos调用方式: 三步骤(创建任务 → 查询状态 → 获取视频)优势: 更稳定 | 任务队列 | 支持长时任务 | 失败不扣费为什么选择异步 API?
更高稳定性
基于任务队列,避免长连接超时问题
失败不扣费 ⭐
重大优势:任何原因失败都不扣费
- ✓ 内容违规 → 不扣费
- ✓ 队列超时 → 不扣费
- ✓ 生成失败 → 不扣费
灵活轮询
可随时查询任务状态和进度
批量处理
适合批量生成、后台任务处理
同步 vs 异步对比
| 特性 | 同步 API | 异步 API(推荐) |
|---|---|---|
| 调用方式 | 单次请求等待完成 | 创建任务后轮询查询 |
| 端点 | /v1/chat/completions | /v1/videos |
| 模型选择 | 通过 model 参数指定画幅 | 通过 model 参数指定画幅 |
| 图生视频 | 支持图片URL和Base64 | 支持图片URL |
| 失败扣费 | 请求成功但生成失败会扣费 | ⭐ 失败不扣费 |
| 稳定性 | 依赖长连接 | ⭐⭐⭐⭐⭐ 更稳定 |
| 进度查看 | 流式输出 | 轮询查询进度百分比 |
| 超时处理 | 需要设置长超时 | 任务独立运行,无超时限制 |
| 适用场景 | 快速测试、实时反馈 | 生产环境、批量生成 |
快速开始
异步调用分为三个步骤:1
创建视频任务
POST 请求创建任务,获取任务 ID
2
查询任务状态
定期轮询查询生成进度
3
下载视频
任务完成后获取视频文件
完整示例
API 端点详解
1. 创建视频任务
POST
https://api.laozhang.ai/v1/videos创建一个新的视频生成任务请求参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
model | string | ✓ | 模型名称(见下方模型列表) |
prompt | string | ✓ | 视频生成提示词 |
可用模型
| 模型名称 | 画幅 | 速度 | 图生视频 | 价格 |
|---|---|---|---|---|
veo-3.1 | 竖屏 | 标准 | ❌ | $0.25/次 |
veo-3.1-fl | 竖屏 | 标准 | ✅ | $0.25/次 |
veo-3.1-fast | 竖屏 | 快速 | ❌ | $0.15/次 |
veo-3.1-fast-fl | 竖屏 | 快速 | ✅ | $0.15/次 |
veo-3.1-landscape | 横屏 | 标准 | ❌ | $0.25/次 |
veo-3.1-landscape-fl | 横屏 | 标准 | ✅ | $0.25/次 |
veo-3.1-landscape-fast | 横屏 | 快速 | ❌ | $0.15/次 |
veo-3.1-landscape-fast-fl | 横屏 | 快速 | ✅ | $0.15/次 |
模型命名规则:
landscape= 横屏(16:9)fast= 快速版(更便宜)fl= 支持帧转视频(图生视频)
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务唯一标识,用于后续查询 |
object | string | 固定为 "video" |
model | string | 使用的模型 |
status | string | 任务状态:"queued" |
created | integer | 创建时间戳 |
2. 查询任务状态
GET
https://api.laozhang.ai/v1/videos/{video_id}查询视频生成任务的当前状态路径参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
video_id | string | ✓ | 创建任务时返回的任务 ID |
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID |
object | string | 固定为 "video" |
model | string | 使用的模型 |
status | string | 任务状态(见下方说明) |
prompt | string | 原始提示词 |
created | integer | 创建时间戳 |
任务状态说明
| 状态 | 说明 | 下一步操作 |
|---|---|---|
queued | 任务排队中 | 继续轮询状态 |
processing | 正在生成中 | 继续轮询状态 |
completed | 生成完成 | 调用获取内容接口 |
failed | 生成失败 | 检查错误信息 |
3. 获取视频内容
GET
https://api.laozhang.ai/v1/videos/{video_id}/content获取已完成视频的实际内容路径参数
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
video_id | string | ✓ | 任务 ID |
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID |
object | string | 固定为 "video" |
status | string | 任务状态 |
model | string | 使用的模型 |
prompt | string | 原始提示词 |
url | string | 视频下载 URL |
duration | integer | 视频时长(秒) |
resolution | string | 视频分辨率 |
created | integer | 创建时间戳 |
完整代码示例
Python 示例(含轮询逻辑)
JavaScript/Node.js 示例
最佳实践
轮询间隔设置
轮询间隔设置
推荐轮询间隔:5-10 秒原因:
- 视频生成通常需要 2-5 分钟
- 5-10 秒可以及时反馈进度
- 避免过于频繁的请求
超时处理
超时处理
推荐超时设置:10 分钟(600秒)注意:
- 任务超时不会自动取消
- 可以稍后继续查询同一个 video_id
- 任务有效期为 24 小时
错误重试策略
错误重试策略
建议重试逻辑:重试场景:
- ✓ 网络错误 → 重试
- ✓ 服务繁忙 (503) → 重试
- ✗ 内容违规 → 不要重试,修改提示词
- ✗ 余额不足 → 不要重试,充值后再试
批量生成优化
批量生成优化
并发控制建议:建议:
- 创建任务:可以高并发(10-30个)
- 查询状态:建议并发数 ≤ 10
- 下载视频:建议并发数 ≤ 5
定价说明
异步 API 与同步 API 价格完全相同,按次计费。
| 模型类型 | 价格 | 充值100$优惠价 |
|---|---|---|
| 标准版(veo-3.1 等) | $0.25/次 | ≈ ¥1.7/次 |
| 快速版(veo-3.1-fast 等) | $0.15/次 | ≈ ¥1.0/次 |
- ✓ 仅在视频成功生成时收费(status = “completed”)
- ✗ 失败、超时、取消不计费
- ✗ 内容安全问题失败也不扣费(与同步API的重要区别⭐)
- ✗ 查询状态不计费
常见问题
任务的有效期是多久?
任务的有效期是多久?
任务有效期:24 小时
- 创建任务后,24 小时内可随时查询任务状态
- 视频生成完成后,文件保存 24 小时
- 超过 24 小时后,任务和视频将被自动清理
- 视频生成完成后立即下载
- 不要依赖服务器长期存储
查询时返回 404 是什么原因?
查询时返回 404 是什么原因?
可能的原因:
- video_id 错误 - 检查是否复制完整
- 任务已过期 - 超过 24 小时
- 网络问题 - 重试请求
异步和同步 API 可以混用吗?
异步和同步 API 可以混用吗?
可以混用,完全独立两个 API 系统完全独立:
- 不同的端点
- 不同的调用方式
- 相同的定价
- 共享同一个 API Key 和余额
- 快速测试 → 使用同步 API
- 生产环境 → 使用异步 API(更稳定)
- 批量生成 → 使用异步 API
如何选择合适的模型?
如何选择合适的模型?
根据需求选择:
| 需求 | 推荐模型 |
|---|---|
| 快速测试 | veo-3.1-fast |
| 标准竖屏视频 | veo-3.1 |
| 标准横屏视频 | veo-3.1-landscape |
| 图生视频(竖屏) | veo-3.1-fl |
| 图生视频(横屏) | veo-3.1-landscape-fl |
| 批量生成(省钱) | veo-3.1-fast 或 veo-3.1-landscape-fast |
错误处理
常见错误码
| HTTP 状态码 | 错误类型 | 说明 | 处理建议 |
|---|---|---|---|
| 400 | Bad Request | 请求参数错误 | 检查参数格式和值 |
| 401 | Unauthorized | API Key 无效 | 检查 Authorization 头 |
| 402 | Payment Required | 余额不足 | 充值后重试 |
| 404 | Not Found | 任务不存在 | 检查 video_id 或任务已过期 |
| 429 | Too Many Requests | 请求过于频繁 | 降低轮询频率 |
| 500 | Internal Server Error | 服务器错误 | 稍后重试 |
| 503 | Service Unavailable | 服务暂时不可用 | 等待后重试 |
错误响应格式
技术支持
需要帮助?
如有问题,欢迎联系我们:
- 邮箱: threezhang.cn@gmail.com
- 微信: laozhangdaichong
- Telegram: https://t.me/laozhang_cn
- 文档: https://docs.laozhang.ai