​
Documentation Index

Fetch the complete documentation index at: https://docs.toapis.com/llms.txt Use this file to discover all available pages before exploring further.

​
获取视频任务状态

查询视频生成任务的状态和结果
  • 查询异步视频生成任务的执行状态和结果
  • 实时状态更新和进度跟踪
  • 任务完成时获取生成的视频
  • 支持多语言返回（zh/en/ko/ja）
所有视频生成任务都是异步执行的。提交任务后，您需要通过查询接口获取任务状态和结果。

​
创建任务时传入业务 ID

创建视频任务时，可以在请求体顶层传入 client_business_id。该字段用于保存您系统内的订单号、流水号或业务任务 ID，方便后续按业务 ID 查询生成结果。 
{
  "model": "sora-2",
  "client_business_id": "order_20260428_002",
  "prompt": "海浪拍打着海岸",
  "duration": 15,
  "aspect_ratio": "16:9"
}
也兼容放在 metadata.client_business_id 中，但推荐使用顶层字段。

​
Authorizations

​
Authorization
string
required
所有接口均需要使用 Bearer Token 进行认证获取 API Key：访问 API Key 管理页面 获取您的 API Key使用时在请求头中添加：
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
task_id
string
required
视频生成 API 返回的任务 ID。也可以传创建任务时提交的 client_business_id，用于按客户侧业务 ID 查询任务状态和结果。
如果创建视频任务时传入 client_business_id，可直接使用同一个状态查询接口： GET /v1/videos/generations/{client_business_id}。业务 ID 会限定在当前 API Key 所属用户下查询。
curl --request GET \
  --url 'https://toapis.com/v1/videos/generations/task_01K9S419324DREZFBWNSVXYR6H' \
  --header 'Authorization: Bearer <token>'

{
  "id": "video_7497f4d5-3a88-44c7-923a-967fa7d941a0",
  "object": "generation.task",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380222
}

​
Response

​
id
string
任务唯一标识符
​
client_business_id
string
客户侧业务 ID。仅当创建任务时传入 client_business_id 时返回。
​
object
string
对象类型，固定为 generation.task
​
model
string
使用的视频生成模型
​
status
string
任务状态
  • queued - 排队等待处理
  • in_progress - 处理中
  • completed - 成功完成
  • failed - 失败
​
progress
integer
任务进度百分比（0-100）
​
created_at
integer
任务创建时间（Unix 时间戳）
​
completed_at
integer
任务完成时间（Unix 时间戳，仅完成时返回）
​
expires_at
integer
视频 URL 过期时间（Unix 时间戳，仅完成时返回）
​
video_url
string
生成的视频 URL（仅成功时返回）
​
error
object
错误信息（仅失败时返回）

​
任务状态说明

状态说明是否终态建议操作
queued任务排队等待处理❌等待 5-10 秒后重试查询
in_progress任务正在处理中❌等待 10-15 秒后重试查询
completed任务成功完成✅从 video_url 获取视频
failed任务处理失败✅检查 error 信息

​
轮询策略建议

初始等待: 5 秒
轮询间隔: 10 秒
最大等待: 600 秒（10分钟）
典型耗时: 1-5 分钟

​
Python 轮询示例

import time
import requests

def poll_video_task(task_id, api_key, max_wait=600):
    """轮询视频生成任务直到完成或超时"""
    start_time = time.time()
    interval = 10  # 10秒间隔
    
    # 首次等待5秒
    time.sleep(5)
    
    while time.time() - start_time < max_wait:
        response = requests.get(
            f'https://toapis.com/v1/videos/generations/{task_id}',
            headers={'Authorization': f'Bearer {api_key}'}
        )
        data = response.json()
        
        print(f"状态: {data['status']}, 进度: {data.get('progress', 0)}%")
        
        if data['status'] == 'completed':
            return {
                'video_url': data['video_url'],
                'expires_at': data.get('expires_at')
            }
        elif data['status'] == 'failed':
            raise Exception(f"生成失败: {data['error']['message']}")
        
        time.sleep(interval)
    
    raise TimeoutError("任务超时")

​
视频资源有效期

生成的视频 URL 有效期为 24 小时
  • 请在有效期内下载保存视频
  • expires_at 字段标识视频过期时间（Unix 时间戳）
  • 视频过期后无法访问，如需重新获取，需要重新提交生成任务
  • 缩略图与视频同步过期

​
常见错误

错误码错误类型说明
400invalid_request请求参数无效
401unauthorized认证失败，检查 API Key
402insufficient_quota余额不足
404task_not_found任务不存在
422content_policy_violation内容违规
429rate_limit_exceeded请求频率超限
500internal_error服务器内部错误

​
性能建议

视频生成耗时较长，建议：
  1. 使用 Webhook 回调：如果平台支持，配置回调URL可以避免频繁轮询
  2. 合理设置轮询间隔：建议10秒，过于频繁会浪费请求配额
  3. 设置超时时间：长视频生成可能需要5-10分钟，请设置合理的超时
  4. 及时下载保存：视频24小时后过期，请务必及时保存到自己的存储