跳转到主要内容
异步端点: https://api.laozhang.ai/v1/videos调用方式: 三步骤(创建任务 → 查询状态 → 获取视频)优势: 更稳定 | 任务队列 | 支持长时任务 | 失败不扣费

为什么选择异步 API?

更高稳定性

基于任务队列,避免长连接超时问题

失败不扣费 ⭐

重大优势:任何原因失败都不扣费
  • ✓ 内容违规 → 不扣费
  • ✓ 队列超时 → 不扣费
  • ✓ 生成失败 → 不扣费
同步API只要请求成功(HTTP 200)就扣费,即使最终生成失败!

灵活轮询

可随时查询任务状态和进度

批量处理

适合批量生成、后台任务处理

同步 vs 异步对比

特性同步 API异步 API(推荐)
调用方式单次请求等待完成创建任务后轮询查询
端点/v1/chat/completions/v1/videos
模型选择通过 model 参数指定画幅通过 model 参数指定画幅
图生视频支持图片URL和Base64支持图片URL
失败扣费请求成功但生成失败会扣费⭐ 失败不扣费
稳定性依赖长连接⭐⭐⭐⭐⭐ 更稳定
进度查看流式输出轮询查询进度百分比
超时处理需要设置长超时任务独立运行,无超时限制
适用场景快速测试、实时反馈生产环境、批量生成
推荐使用异步 API,特别是在生产环境或需要批量生成视频时,稳定性更有保障。

快速开始

异步调用分为三个步骤:
1

创建视频任务

POST 请求创建任务,获取任务 ID
2

查询任务状态

定期轮询查询生成进度
3

下载视频

任务完成后获取视频文件

完整示例

curl -X POST "https://api.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"
}

API 端点详解

1. 创建视频任务

POST https://api.laozhang.ai/v1/videos创建一个新的视频生成任务

请求参数

参数类型必需说明
modelstring模型名称(见下方模型列表)
promptstring视频生成提示词

可用模型

模型名称画幅速度图生视频价格
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 = 支持帧转视频(图生视频)

响应字段

字段类型说明
idstring任务唯一标识,用于后续查询
objectstring固定为 "video"
modelstring使用的模型
statusstring任务状态:"queued"
createdinteger创建时间戳

2. 查询任务状态

GET https://api.laozhang.ai/v1/videos/{video_id}查询视频生成任务的当前状态

路径参数

参数类型必需说明
video_idstring创建任务时返回的任务 ID

响应字段

字段类型说明
idstring任务 ID
objectstring固定为 "video"
modelstring使用的模型
statusstring任务状态(见下方说明)
promptstring原始提示词
createdinteger创建时间戳

任务状态说明

状态说明下一步操作
queued任务排队中继续轮询状态
processing正在生成中继续轮询状态
completed生成完成调用获取内容接口
failed生成失败检查错误信息

3. 获取视频内容

GET https://api.laozhang.ai/v1/videos/{video_id}/content获取已完成视频的实际内容

路径参数

参数类型必需说明
video_idstring任务 ID

响应字段

字段类型说明
idstring任务 ID
objectstring固定为 "video"
statusstring任务状态
modelstring使用的模型
promptstring原始提示词
urlstring视频下载 URL
durationinteger视频时长(秒)
resolutionstring视频分辨率
createdinteger创建时间戳
重要提示视频 URL 有效期通常为 24 小时,请及时下载保存到本地!

完整代码示例

Python 示例(含轮询逻辑)

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.laozhang.ai/v1"

# 步骤1: 创建视频任务
def create_video_task(prompt, model="veo-3.1"):
    """创建视频生成任务"""
    url = f"{BASE_URL}/videos"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "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"
    )

    # 文生视频 - 横屏快速版
    # generate_video_async(
    #     prompt="日落时分,海浪轻轻拍打沙滩",
    #     model="veo-3.1-landscape-fast"
    # )

JavaScript/Node.js 示例

const axios = require('axios');
const fs = require('fs');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.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 秒
# 推荐
poll_interval = 5  # 每5秒查询一次

# 不推荐
poll_interval = 1  # 太频繁,浪费请求
poll_interval = 30 # 太慢,用户体验差
原因:
  • 视频生成通常需要 2-5 分钟
  • 5-10 秒可以及时反馈进度
  • 避免过于频繁的请求
推荐超时设置:10 分钟(600秒)
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 小时
建议重试逻辑:
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) → 重试
  • ✗ 内容违规 → 不要重试,修改提示词
  • ✗ 余额不足 → 不要重试,充值后再试
并发控制建议:
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 价格完全相同,按次计费。
模型类型价格充值100$优惠价
标准版(veo-3.1 等)$0.25/次≈ ¥1.7/次
快速版(veo-3.1-fast 等)$0.15/次≈ ¥1.0/次
计费规则:
  • ✓ 仅在视频成功生成时收费(status = “completed”)
  • ✗ 失败、超时、取消不计费
  • ✗ 内容安全问题失败也不扣费(与同步API的重要区别⭐)
  • ✗ 查询状态不计费
异步API的重要优势:任何原因导致的失败都不会扣费,包括内容安全审核未通过。而同步API只要请求成功就会扣费,即使最终生成失败。

常见问题

任务有效期:24 小时
  • 创建任务后,24 小时内可随时查询任务状态
  • 视频生成完成后,文件保存 24 小时
  • 超过 24 小时后,任务和视频将被自动清理
建议:
  • 视频生成完成后立即下载
  • 不要依赖服务器长期存储
可能的原因:
  1. video_id 错误 - 检查是否复制完整
  2. 任务已过期 - 超过 24 小时
  3. 网络问题 - 重试请求
解决方法:
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-fastveo-3.1-landscape-fast

错误处理

常见错误码

HTTP 状态码错误类型说明处理建议
400Bad Request请求参数错误检查参数格式和值
401UnauthorizedAPI Key 无效检查 Authorization 头
402Payment Required余额不足充值后重试
404Not Found任务不存在检查 video_id 或任务已过期
429Too Many Requests请求过于频繁降低轮询频率
500Internal Server Error服务器错误稍后重试
503Service Unavailable服务暂时不可用等待后重试

错误响应格式

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "type": "authentication_error"
  }
}

技术支持

需要帮助?

如有问题,欢迎联系我们:

下一步