跳转到主要内容
异步端点: https://api.laozhang.ai/v1/videos调用方式: 三步骤(创建任务 → 查询状态 → 获取视频)优势: 更稳定 | 任务队列 | 支持长时任务
重要差异 - 图生视频方式不同异步API的图生视频与同步API有重大区别:
特性同步API异步API
图片上传支持URL或Base64仅支持本地文件
请求格式JSONmultipart/form-data
如果您有图片URL:需要先下载到本地,再用异步API上传。示例对比
{/* 同步API - 支持URL */}
"image_url": {"url": "https://example.com/image.png"}

{/* 异步API - 仅支持本地文件 */}
files = {'input_reference': open('/path/to/image.png', 'rb')}

为什么选择异步 API?

更高稳定性

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

失败不扣费 ⭐

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

灵活轮询

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

参数化控制

分辨率和时长通过参数指定,更灵活

同步 vs 异步对比

特性同步 API异步 API(推荐)
调用方式单次请求等待完成创建任务后轮询查询
端点/v1/chat/completions/v1/videos
分辨率控制模型名(sora_video2-landscape参数(size: "1280x720"
时长控制模型名(sora_video2-15s参数(seconds: "15"
图生视频支持图片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": "sora-2",
    "prompt": "一只可爱的猫咪在阳光明媚的花园里玩球",
    "size": "1280x720",
    "seconds": "15"
  }'

# 响应示例
{
  "id": "video_abc123",
  "object": "task",
  "model": "sora-2",
  "status": "submitted",
  "created_at": 1760945092,
  "expires_at": 1761031492
}

API 端点详解

1. 创建视频任务

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

请求参数

参数类型必需可选值说明
modelstring"sora-2"模型名称(固定值)
promptstring-视频生成提示词
sizestring"1280x720", "720x1280"视频分辨率(横屏/竖屏)
secondsstring"10", "15"视频时长(秒)
input_referencefile图生视频时必填-本地图片文件(仅支持本地上传)
支持格式:JPG, PNG, WebP
建议尺寸:1280x720
建议大小:< 5MB

响应字段

字段类型说明
idstring任务唯一标识,用于后续查询
objectstring固定为 "task"
modelstring使用的模型
statusstring任务状态:"submitted"
created_atinteger创建时间戳
expires_atinteger过期时间戳(24小时后)

2. 查询任务状态

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

路径参数

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

响应字段

字段类型说明
idstring任务 ID
objectstring固定为 "video"
modelstring使用的模型
statusstring任务状态(见下方说明)
progressinteger进度百分比(0-100)
urlstring视频下载路径(仅 completed 状态)
created_atinteger创建时间戳
completed_atinteger完成时间戳(仅 completed 状态)
errorobject错误信息(仅 failed 状态)

任务状态说明

状态说明进度
submitted已提交,等待处理0%
in_progress正在生成中1-99%
completed生成完成100%
failed生成失败-

3. 获取视频内容

GET https://api.laozhang.ai/v1/videos/{video_id}/content下载已完成的视频文件

路径参数

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

响应

返回视频文件的二进制流(MP4 格式)
重要提示视频文件存储有效期为 24 小时,请及时下载保存到本地!

完整代码示例

Python 示例(含轮询逻辑)

import requests
import time

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

# 步骤1: 创建视频任务(文生视频)
def create_video_task(prompt, size="1280x720", seconds="15"):
    """创建视频生成任务"""
    url = f"{BASE_URL}/videos"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "model": "sora-2",
        "prompt": prompt,
        "size": size,
        "seconds": seconds
    }

    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status()
    return response.json()

# 步骤1: 创建视频任务(图生视频)
def create_video_task_with_image(prompt, image_path, size="1280x720", seconds="10"):
    """创建图生视频任务"""
    url = f"{BASE_URL}/videos"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    # 确保文件在请求时保持打开状态
    with open(image_path, 'rb') as image_file:
        files = {
            # 指定filename和MIME类型确保正确上传
            'input_reference': ('image.png', image_file, 'image/png')
        }
        data = {
            'model': 'sora-2',
            'prompt': prompt,
            'size': size,
            'seconds': seconds
        }

        # 在with块内发送请求,确保文件句柄有效
        response = requests.post(url, headers=headers, files=files, data=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"]
        progress = task.get("progress", 0)

        print(f"状态: {status}, 进度: {progress}%")

        if status == "completed":
            return task
        elif status == "failed":
            error = task.get("error", {})
            raise Exception(f"生成失败: {error.get('message', '未知错误')}")

        # 等待后重试
        time.sleep(poll_interval)

# 步骤3: 下载视频
def download_video(video_id, save_path="video.mp4"):
    """下载生成的视频"""
    url = f"{BASE_URL}/videos/{video_id}/content"
    headers = {"Authorization": f"Bearer {API_KEY}"}

    response = requests.get(url, headers=headers, 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, size="1280x720", seconds="15"):
    """异步生成视频的完整流程"""
    print("1. 创建视频任务...")
    task = create_video_task(prompt, size, seconds)
    video_id = task["id"]
    print(f"   任务ID: {video_id}")

    print("\n2. 等待视频生成...")
    completed_task = wait_for_video(video_id)
    print(f"   生成完成!耗时: {completed_task['completed_at'] - completed_task['created_at']}秒")

    print("\n3. 下载视频...")
    download_video(video_id)
    print("\n✅ 完成!")

# 完整流程(图生视频)
def generate_video_from_image_async(image_path, prompt, size="1280x720", seconds="10"):
    """从本地图片生成视频的完整流程"""
    import os

    if not os.path.exists(image_path):
        print(f"错误:图片文件不存在 {image_path}")
        return None

    print(f"1. 上传图片并创建任务...({image_path})")
    task = create_video_task_with_image(prompt, image_path, size, seconds)
    video_id = task["id"]
    print(f"   任务ID: {video_id}")

    print("\n2. 等待视频生成...")
    completed_task = wait_for_video(video_id)
    print(f"   生成完成!耗时: {completed_task['completed_at'] - completed_task['created_at']}秒")

    print("\n3. 下载视频...")
    download_video(video_id, save_path=f"image_to_video_{video_id}.mp4")
    print("\n✅ 完成!")

    return video_id

# 使用示例
if __name__ == "__main__":
    # 文生视频
    generate_video_async(
        prompt="一只可爱的猫咪在阳光明媚的花园里玩球",
        size="1280x720",  # 横屏
        seconds="15"       # 15秒
    )

    # 图生视频
    generate_video_from_image_async(
        image_path="/path/to/your/image.png",
        prompt="让这张图片中的场景动起来,增加自然的动态效果",
        size="1280x720",  # 横屏
        seconds="10"       # 10秒
    )

JavaScript/Node.js 示例

const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.laozhang.ai/v1';

// 创建视频任务(文生视频)
async function createVideoTask(prompt, size = '1280x720', seconds = '15') {
  const response = await axios.post(`${BASE_URL}/videos`, {
    model: 'sora-2',
    prompt,
    size,
    seconds
  }, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });

  return response.data;
}

// 创建视频任务(图生视频)
async function createVideoTaskWithImage(prompt, imagePath, size = '1280x720', seconds = '10') {
  const formData = new FormData();
  formData.append('model', 'sora-2');
  formData.append('prompt', prompt);
  formData.append('size', size);
  formData.append('seconds', seconds);
  formData.append('input_reference', fs.createReadStream(imagePath));

  const response = await axios.post(`${BASE_URL}/videos`, formData, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      ...formData.getHeaders()
    }
  });

  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, progress = 0 } = task;

    console.log(`状态: ${status}, 进度: ${progress}%`);

    if (status === 'completed') {
      return task;
    } else if (status === 'failed') {
      const error = task.error || {};
      throw new Error(`生成失败: ${error.message || '未知错误'}`);
    }

    // 等待后重试
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
}

// 下载视频
async function downloadVideo(videoId, savePath = 'video.mp4') {
  const response = await axios.get(
    `${BASE_URL}/videos/${videoId}/content`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` },
      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, size = '1280x720', seconds = '15') {
  try {
    console.log('1. 创建视频任务...');
    const task = await createVideoTask(prompt, size, seconds);
    const videoId = task.id;
    console.log(`   任务ID: ${videoId}`);

    console.log('\n2. 等待视频生成...');
    const completedTask = await waitForVideo(videoId);
    const duration = completedTask.completed_at - completedTask.created_at;
    console.log(`   生成完成!耗时: ${duration}秒`);

    console.log('\n3. 下载视频...');
    await downloadVideo(videoId);
    console.log('\n✅ 完成!');

  } catch (error) {
    console.error('错误:', error.message);
  }
}

// 完整流程(图生视频)
async function generateVideoFromImageAsync(imagePath, prompt, size = '1280x720', seconds = '10') {
  try {
    if (!fs.existsSync(imagePath)) {
      console.error(`错误:图片文件不存在 ${imagePath}`);
      return null;
    }

    console.log(`1. 上传图片并创建任务...(${imagePath})`);
    const task = await createVideoTaskWithImage(prompt, imagePath, size, seconds);
    const videoId = task.id;
    console.log(`   任务ID: ${videoId}`);

    console.log('\n2. 等待视频生成...');
    const completedTask = await waitForVideo(videoId);
    const duration = completedTask.completed_at - completedTask.created_at;
    console.log(`   生成完成!耗时: ${duration}秒`);

    console.log('\n3. 下载视频...');
    await downloadVideo(videoId, `image_to_video_${videoId}.mp4`);
    console.log('\n✅ 完成!');

    return videoId;

  } catch (error) {
    console.error('错误:', error.message);
    return null;
  }
}

// 使用示例
// 文生视频
generateVideoAsync(
  '一只可爱的猫咪在阳光明媚的花园里玩球',
  '1280x720',  // 横屏
  '15'         // 15秒
);

// 图生视频
generateVideoFromImageAsync(
  '/path/to/your/image.png',
  '让这张图片中的场景动起来,增加自然的动态效果',
  '1280x720',  // 横屏
  '10'         // 10秒
);

最佳实践

推荐轮询间隔:3-5 秒
# 推荐
poll_interval = 5  # 每5秒查询一次

# 不推荐
poll_interval = 1  # 太频繁,浪费请求
poll_interval = 30 # 太慢,用户体验差
原因:
  • 视频生成通常需要 2-5 分钟
  • 3-5 秒可以及时反馈进度
  • 避免过于频繁的请求
推荐超时设置: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, max_retries=3):
    for i in range(max_retries):
        try:
            return create_video_task(prompt)
        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, max_workers=5):
    """批量生成视频,控制并发数"""
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
        # 创建所有任务
        future_to_prompt = {
            executor.submit(create_video_task, prompt): 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$优惠价
10秒视频(横屏/竖屏)$0.15/次≈ ¥1.0/次
15秒视频(横屏/竖屏)$0.15/次≈ ¥1.0/次
计费规则:
  • ✓ 仅在视频成功生成时收费(status = “completed”)
  • ✗ 失败、超时、取消不计费
  • ✗ 内容安全问题失败也不扣费(与同步API的重要区别⭐)
  • ✗ 查询状态不计费
异步API的重要优势:任何原因导致的失败都不会扣费,包括内容安全审核未通过。而同步API只要请求成功就会扣费,即使最终生成失败。

常见问题

任务有效期:24 小时
  • 创建任务后,expires_at 字段显示过期时间
  • 24 小时内可随时查询任务状态
  • 视频生成完成后,文件保存 24 小时
  • 超过 24 小时后,任务和视频将被自动清理
建议:
  • 视频生成完成后立即下载
  • 不要依赖服务器长期存储
当前不支持手动取消任务
  • 任务一旦创建,会自动排队执行
  • 如果不再需要,直接忽略即可
  • 未完成的任务不会扣费
替代方案:
  • 等待任务自然完成或失败
  • 24 小时后任务自动过期
可能的原因:
  1. video_id 错误 - 检查是否复制完整
  2. 任务已过期 - 超过 24 小时
  3. 网络问题 - 重试请求
解决方法:
try:
    response = client.get(f"/videos/{video_id}")
    task = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("任务不存在或已过期")
    else:
        raise
可以混用,完全独立两个 API 系统完全独立:
  • 不同的端点
  • 不同的调用方式
  • 相同的定价
  • 共享同一个 API Key 和余额
使用建议:
  • 快速测试 → 使用同步 API
  • 生产环境 → 使用异步 API(更稳定)
  • 批量生成 → 使用异步 API
可能的原因:
  1. 正常现象 - 某些处理阶段进度更新较慢
  2. 队列等待 - 高峰期可能在排队
  3. 生成卡住 - 极少数情况下任务可能卡住
处理方法:
  • 继续等待 5-10 分钟
  • 如果超过 10 分钟无变化,联系技术支持
  • 提供 video_id 以便排查
不支持!仅支持本地图片文件上传。正确做法:
# ✓ 正确:上传本地文件
with open('/path/to/image.png', 'rb') as f:
    files = {'input_reference': f}
    response = requests.post(url, files=files, data=data)
不支持:
  • ✗ 图片URL
  • ✗ Base64编码
  • ✗ 在线图片链接
原因: 异步API通过 multipart/form-data 格式上传,仅支持本地文件流。
支持的图片格式:
  • ✓ JPG / JPEG
  • ✓ PNG
  • ✓ WebP
图片要求:
  • 文件大小: < 5MB(推荐)
  • 分辨率: 建议 1280x720 或相近比例
  • 来源: 必须是本地文件
自动识别MIME类型:
import os

def get_mime_type(path):
    ext = os.path.splitext(path)[1].lower()
    types = {
        '.jpg': 'image/jpeg',
        '.jpeg': 'image/jpeg',
        '.png': 'image/png',
        '.webp': 'image/webp'
    }
    return types.get(ext, 'image/jpeg')
是的,prompt 参数必填!即使你只是想让图片”自然地动起来”,也需要提供描述:推荐的简单prompt:
"让图片中的场景自然地动起来"
"保持原有风格,增加动态效果"
"让这个场景动起来,加入微风效果"
更具体的prompt效果更好:
"让湖面泛起涟漪,树叶随风摇曳,云层缓慢移动"
"让小猫从左侧跳到右侧,尾巴摇动"
"360度缓慢旋转展示产品,加上光影效果"
价格完全相同!
视频时长价格
10秒(横屏/竖屏)$0.15/次 ≈ ¥1.0/次
15秒(横屏/竖屏)$0.15/次 ≈ ¥1.0/次
计费说明:
  • 图生视频和文生视频价格一样
  • 仅成功生成时收费
  • 失败不扣费(包括图片格式错误、内容违规等)
几乎没有影响。图生视频和文生视频的生成时间基本相同:
  • 通常时间: 2-5 分钟
  • 影响因素: 视频时长、队列长度、复杂度
图片大小影响:
  • 建议 < 5MB:上传快,处理快
  • 过大图片:仅影响上传时间(几秒),对生成时间无明显影响

错误处理

常见错误码

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

错误响应格式

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

技术支持

需要帮助?

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

下一步

I