> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 异步调用 API（暂不可用）
> Veo-3.1 异步视频生成 API 自 2026 年 5 月 14 日起暂时无法使用；本文仅供历史任务队列示例和恢复前排查参考。
**Veo-3.1 旧接入方案故障通知**
`veo-3.1` 系列旧接入方案自 2026 年 5 月 14 日起出现故障，当前暂时无法使用。请暂停按本文示例创建新的异步视频任务，恢复时间以网站公告和控制台通知为准。
**异步端点：** `https://api2.laozhang.ai/v1/videos`
**调用方式：** 三步骤（创建任务 → 查询状态 → 获取视频）
**优势：** 更稳定 | 任务队列 | 支持长时任务 | 失败计费以控制台记录为准
## 为什么选择异步 API？
基于任务队列，避免长连接超时问题
**重大优势**：任何原因失败都计费以控制台记录为准
* ✓ 内容违规 → 计费以控制台记录为准
* ✓ 队列超时 → 计费以控制台记录为准
* ✓ 生成失败 → 计费以控制台记录为准
同步 API 的异常计费以控制台订单状态为准。
可随时查询任务状态和进度
适合批量生成、后台任务处理
## 同步 vs 异步对比
| 特性 | 同步 API | 异步 API（推荐） |
| -------- | ---------------------- | --------------- |
| **调用方式** | 单次请求等待完成 | 创建任务后轮询查询 |
| **端点** | `/v1/chat/completions` | `/v1/videos` |
| **模型选择** | 通过 model 参数指定画幅 | 通过 model 参数指定画幅 |
| **图生视频** | 支持图片URL和Base64 | 支持图片URL |
| **异常计费** | 异常状态以控制台记录为准 | ⭐ 失败计费以控制台记录为准 |
| **稳定性** | 依赖长连接 | ⭐⭐⭐⭐⭐ 更稳定 |
| **进度查看** | 流式输出 | 轮询查询进度百分比 |
| **超时处理** | 需要设置长超时 | 任务独立运行，无超时限制 |
| **适用场景** | 快速测试、实时反馈 | 生产环境、批量生成 |
**推荐使用异步 API**，特别是在生产环境或需要批量生成视频时，稳定性更有保障。
## 快速开始
异步调用分为三个步骤：
POST 请求创建任务，获取任务 ID
定期轮询查询生成进度
任务完成后获取视频文件
### 完整示例
```bash 步骤1: 创建任务（文生视频） theme={null}
curl -X POST "https://api2.laozhang.ai/v1/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1",
"prompt": "一只可爱的猫咪在阳光明媚的花园里玩球"
}'
# 响应示例
{
"id": "video_abc123",
"object": "video",
"created": 1762181811,
"status": "queued",
"model": "veo-3.1"
}
```
```bash 步骤1: 创建任务（图生视频 - 单图） theme={null}
# 注意：需要使用 multipart/form-data 格式上传图片
curl -X POST "https://api2.laozhang.ai/v1/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "model=veo-3.1-fl" \
-F "prompt=让这只猫咪慢慢眨眼睛" \
-F "input_reference=@original_image.jpg"
# 响应示例
{
"id": "video_def456",
"object": "video",
"created": 1762181822,
"status": "queued",
"model": "veo-3.1-fl"
}
```
```bash 步骤1: 创建任务（图生视频 - 首尾帧） theme={null}
# 使用两张图片作为首帧和尾帧，生成平滑过渡的视频
curl -X POST "https://api2.laozhang.ai/v1/videos" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: multipart/form-data" \
-F "model=veo-3.1-landscape-fl" \
-F "prompt=让这个画面动起来，加点未来科技感" \
-F "input_reference=@start_frame.jpg" \
-F "input_reference=@end_frame.jpg"
# 响应示例
{
"id": "video_xyz789",
"object": "video",
"created": 1762181833,
"status": "queued",
"model": "veo-3.1-landscape-fl"
}
```
```bash 步骤2: 查询状态 theme={null}
curl -X GET "https://api2.laozhang.ai/v1/videos/video_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
# 进行中响应
{
"id": "video_abc123",
"object": "video",
"model": "veo-3.1",
"status": "processing",
"created": 1762181811
}
# 完成响应
{
"id": "video_abc123",
"object": "video",
"model": "veo-3.1",
"status": "completed",
"prompt": "一只可爱的猫咪在阳光明媚的花园里玩球",
"created": 1762181811
}
```
```bash 步骤3: 获取视频 theme={null}
curl -X GET "https://api2.laozhang.ai/v1/videos/video_abc123/content" \
-H "Authorization: Bearer YOUR_API_KEY"
# 响应示例
{
"id": "video_abc123",
"object": "video",
"created": 1762181811,
"status": "completed",
"model": "veo-3.1",
"prompt": "一只可爱的猫咪在阳光明媚的花园里玩球",
"url": "https://veo-video.example.com/assets/xxx.mp4",
"duration": 8,
"resolution": "720x1280"
}
```
## API 端点详解
### 1. 创建视频任务
**POST** `https://api2.laozhang.ai/v1/videos`
创建一个新的视频生成任务
#### 请求参数
| 参数 | 类型 | 必需 | 说明 |
| ----------------- | ------ | -- | ----------------------------------------------- |
| `model` | string | ✓ | 模型名称（见下方模型列表） |
| `prompt` | string | ✓ | 视频生成提示词 |
| `input_reference` | file | ❌ | 图片文件，支持 1-2 张（2张时为首尾帧模式，multipart/form-data 格式） |
#### 可用模型
| 模型名称 | 画幅 | 速度 | 图生视频 | 价格 |
| --------------------------- | -- | -- | ---- | -------- |
| `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` = 支持帧转视频（图生视频）
**首尾帧功能**
图生视频模型（带 `-fl` 后缀）支持传入 2 张图片：
* **第一张**：视频开始帧
* **第二张**：视频结束帧
API 会自动生成从开始帧到结束帧的平滑过渡动画。
#### 响应字段
| 字段 | 类型 | 说明 |
| --------- | ------- | --------------- |
| `id` | string | 任务唯一标识，用于后续查询 |
| `object` | string | 固定为 `"video"` |
| `model` | string | 使用的模型 |
| `status` | string | 任务状态：`"queued"` |
| `created` | integer | 创建时间戳 |
### 2. 查询任务状态
**GET** `https://api2.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://api2.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 | 创建时间戳 |
**重要提示**
视频 URL 有效期通常为 **24 小时**，请及时下载保存到本地！
## 完整代码示例
### Python 示例（含轮询逻辑）
```python theme={null}
import requests
import time
import os
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api2.laozhang.ai/v1"
# 步骤1: 创建视频任务
def create_video_task(prompt, model="veo-3.1", image_paths=None):
"""创建视频生成任务
Args:
prompt: 视频生成提示词
model: 模型名称
image_paths: 图片路径，可以是：
- None: 文生视频
- str: 单张图片路径
- list: 多张图片路径（首尾帧模式，最多2张）
"""
url = f"{BASE_URL}/videos"
headers = {"Authorization": f"Bearer {API_KEY}"}
if image_paths:
# 统一转为列表处理
if isinstance(image_paths, str):
image_paths = [image_paths]
# 图生视频：使用 multipart/form-data 上传图片
files = []
for path in image_paths:
if not os.path.exists(path):
raise FileNotFoundError(f"图片文件不存在: {path}")
files.append(("input_reference", (os.path.basename(path), open(path, 'rb'), "image/jpeg")))
data = {"model": model, "prompt": prompt}
response = requests.post(url, headers=headers, files=files, data=data)
# 关闭文件句柄
for _, (_, f, _) in files:
f.close()
else:
# 文生视频：使用 JSON 格式
headers["Content-Type"] = "application/json"
data = {"model": model, "prompt": prompt}
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
# 步骤2: 轮询查询状态
def wait_for_video(video_id, poll_interval=5, timeout=600):
"""等待视频生成完成"""
url = f"{BASE_URL}/videos/{video_id}"
headers = {"Authorization": f"Bearer {API_KEY}"}
start_time = time.time()
while True:
# 检查超时
if time.time() - start_time > timeout:
raise TimeoutError(f"视频生成超时（{timeout}秒）")
# 查询状态
response = requests.get(url, headers=headers)
response.raise_for_status()
task = response.json()
status = task["status"]
print(f"状态: {status}")
if status == "completed":
return task
elif status == "failed":
raise Exception(f"生成失败")
# 等待后重试
time.sleep(poll_interval)
# 步骤3: 获取视频内容
def get_video_content(video_id):
"""获取视频内容和URL"""
url = f"{BASE_URL}/videos/{video_id}/content"
headers = {"Authorization": f"Bearer {API_KEY}"}
response = requests.get(url, headers=headers)
response.raise_for_status()
return response.json()
# 步骤4: 下载视频
def download_video(video_url, save_path="video.mp4"):
"""下载视频文件"""
response = requests.get(video_url, stream=True)
response.raise_for_status()
with open(save_path, 'wb') as f:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
f.write(chunk)
print(f"视频已保存到: {save_path}")
# 完整流程
def generate_video_async(prompt, model="veo-3.1"):
"""异步生成视频的完整流程"""
print("1. 创建视频任务...")
task = create_video_task(prompt, model)
video_id = task["id"]
print(f" 任务ID: {video_id}")
print("\n2. 等待视频生成...")
completed_task = wait_for_video(video_id)
print(" 生成完成！")
print("\n3. 获取视频内容...")
content = get_video_content(video_id)
video_url = content["url"]
print(f" 视频URL: {video_url}")
print("\n4. 下载视频...")
download_video(video_url)
print("\n✅ 完成！")
# 使用示例
if __name__ == "__main__":
# 文生视频 - 竖屏标准版
# 文生视频 - 竖屏标准版
generate_video_async(
prompt="一只可爱的猫咪在阳光明媚的花园里玩球",
model="veo-3.1"
)
# 图生视频 - 单图模式
# task = create_video_task(
# prompt="让这只猫咪慢慢眨眼睛",
# model="veo-3.1-fl",
# image_paths="test.jpg"
# )
# 图生视频 - 首尾帧模式（传入2张图片）
# 第一张图作为开始帧，第二张图作为结束帧
# task = create_video_task(
# prompt="让画面从开始帧平滑过渡到结束帧，加入动态效果",
# model="veo-3.1-landscape-fl",
# image_paths=["start_frame.jpg", "end_frame.jpg"]
# )
# 文生视频 - 横屏快速版
# generate_video_async(
# prompt="日落时分，海浪轻轻拍打沙滩",
# model="veo-3.1-landscape-fast"
# )
```
### JavaScript/Node.js 示例
```javascript theme={null}
const axios = require('axios');
const fs = require('fs');
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api2.laozhang.ai/v1';
// 创建视频任务
async function createVideoTask(prompt, model = 'veo-3.1') {
const response = await axios.post(`${BASE_URL}/videos`, {
model,
prompt
}, {
headers: { 'Authorization': `Bearer ${API_KEY}` }
});
return response.data;
}
// 轮询查询状态
async function waitForVideo(videoId, pollInterval = 5000, timeout = 600000) {
const startTime = Date.now();
while (true) {
// 检查超时
if (Date.now() - startTime > timeout) {
throw new Error(`视频生成超时（${timeout/1000}秒）`);
}
// 查询状态
const response = await axios.get(`${BASE_URL}/videos/${videoId}`, {
headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const task = response.data;
const { status } = task;
console.log(`状态: ${status}`);
if (status === 'completed') {
return task;
} else if (status === 'failed') {
throw new Error('生成失败');
}
// 等待后重试
await new Promise(resolve => setTimeout(resolve, pollInterval));
}
}
// 获取视频内容
async function getVideoContent(videoId) {
const response = await axios.get(`${BASE_URL}/videos/${videoId}/content`, {
headers: { 'Authorization': `Bearer ${API_KEY}` }
});
return response.data;
}
// 下载视频
async function downloadVideo(videoUrl, savePath = 'video.mp4') {
const response = await axios.get(videoUrl, { responseType: 'stream' });
const writer = fs.createWriteStream(savePath);
response.data.pipe(writer);
return new Promise((resolve, reject) => {
writer.on('finish', () => {
console.log(`视频已保存到: ${savePath}`);
resolve();
});
writer.on('error', reject);
});
}
// 完整流程
async function generateVideoAsync(prompt, model = 'veo-3.1') {
try {
console.log('1. 创建视频任务...');
const task = await createVideoTask(prompt, model);
const videoId = task.id;
console.log(` 任务ID: ${videoId}`);
console.log('\n2. 等待视频生成...');
await waitForVideo(videoId);
console.log(' 生成完成！');
console.log('\n3. 获取视频内容...');
const content = await getVideoContent(videoId);
const videoUrl = content.url;
console.log(` 视频URL: ${videoUrl}`);
console.log('\n4. 下载视频...');
await downloadVideo(videoUrl);
console.log('\n✅ 完成！');
} catch (error) {
console.error('错误:', error.message);
}
}
// 使用示例
generateVideoAsync(
'一只可爱的猫咪在阳光明媚的花园里玩球',
'veo-3.1'
);
```
## 最佳实践
**推荐轮询间隔：5-10 秒**
```python theme={null}
# 推荐
poll_interval = 5 # 每5秒查询一次
# 不推荐
poll_interval = 1 # 太频繁，浪费请求
poll_interval = 30 # 太慢，用户体验差
```
**原因：**
* 视频生成通常需要 2-5 分钟
* 5-10 秒可以及时反馈进度
* 避免过于频繁的请求
**推荐超时设置：10 分钟（600秒）**
```python theme={null}
def wait_for_video(video_id, timeout=600):
start_time = time.time()
while True:
if time.time() - start_time > timeout:
# 超时后的处理
print(f"任务 {video_id} 超时，稍后可继续查询")
break
# 查询逻辑...
```
**注意：**
* 任务超时不会自动取消
* 可以稍后继续查询同一个 video\_id
* 任务有效期为 24 小时
**建议重试逻辑：**
```python theme={null}
def create_video_with_retry(prompt, model, max_retries=3):
for i in range(max_retries):
try:
return create_video_task(prompt, model)
except Exception as e:
if i < max_retries - 1:
print(f"创建失败，{5}秒后重试... ({i+1}/{max_retries})")
time.sleep(5)
else:
raise
```
**重试场景：**
* ✓ 网络错误 → 重试
* ✓ 服务繁忙 (503) → 重试
* ✗ 内容违规 → 不要重试，修改提示词
* ✗ 余额不足 → 不要重试，确认账户额度后再试
**并发控制建议：**
```python theme={null}
import concurrent.futures
def batch_generate_videos(prompts, model="veo-3.1", max_workers=5):
"""批量生成视频，控制并发数"""
with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
# 创建所有任务
future_to_prompt = {
executor.submit(create_video_task, prompt, model): prompt
for prompt in prompts
}
video_ids = []
for future in concurrent.futures.as_completed(future_to_prompt):
task = future.result()
video_ids.append(task['id'])
# 并发等待所有任务完成
futures = [executor.submit(wait_for_video, vid) for vid in video_ids]
results = [f.result() for f in concurrent.futures.as_completed(futures)]
return results
```
**建议：**
* 创建任务：可以高并发（10-30个）
* 查询状态：建议并发数 ≤ 10
* 下载视频：建议并发数 ≤ 5
## 定价说明
异步 API 与同步 API **价格完全相同**，按次计费。
| 模型类型 | 价格 |
| ------------------- | -------- |
| 标准版（veo-3.1 等） | \$0.25/次 |
| 快速版（veo-3.1-fast 等） | \$0.15/次 |
**计费规则：**
* ✓ 计费以控制台订单状态为准
* 异常、超时、取消、内容安全问题均以控制台记录为准
* 查询状态是否计费以控制台记录为准
**异步API计费提示**：任何异常状态都应回到控制台订单和账单记录确认；如记录异常，请联系客服复核。
## 常见问题
**任务有效期：24 小时**
* 创建任务后，24 小时内可随时查询任务状态
* 视频生成完成后，文件保存 24 小时
* 超过 24 小时后，任务和视频将被自动清理
**建议：**
* 视频生成完成后立即下载
* 不要依赖服务器长期存储
**可能的原因：**
1. **video\_id 错误** - 检查是否复制完整
2. **任务已过期** - 超过 24 小时
3. **网络问题** - 重试请求
**解决方法：**
```python theme={null}
try:
response = requests.get(f"{BASE_URL}/videos/{video_id}", headers=headers)
task = response.json()
except requests.exceptions.HTTPError as e:
if e.response.status_code == 404:
print("任务不存在或已过期")
else:
raise
```
**可以混用，完全独立**
两个 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 | 服务暂时不可用 | 等待后重试 |
### 错误响应格式
```json theme={null}
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key provided",
"type": "authentication_error"
}
}
```
## 技术支持
如有问题，欢迎联系我们：
* **邮箱：** [hi@laozhang.ai](mailto:hi@laozhang.ai)
* **Telegram：** [https://t.me/laozhang\_cn](https://t.me/laozhang_cn)
* **文档：** [https://docs.laozhang.ai](https://docs.laozhang.ai)
## 下一步
查看同步调用方式（OpenAI 兼容）
查看更多应用示例
了解 Veo-3.1 模型详情
查看更多问题解答