跳转到主要内容
异步端点: 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视频生成提示词
input_referencefile图片文件,支持 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 会自动生成从开始帧到结束帧的平滑过渡动画。

响应字段

字段类型说明
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
import os

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.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 示例

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"
  }
}

技术支持

需要帮助?

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

下一步