跳轉到主要內容
GET
/
v1
/
videos
/
generations
/
{task_id}
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
}
  • 查詢異步視頻生成任務的執行狀態和結果
  • 實時狀態更新和進度跟蹤
  • 任務完成時獲取生成的視頻
  • 支持多語言返回（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
必填
所有接口均需要使用 Bearer Token 進行認證獲取 API Key：訪問 API Key 管理頁面 獲取您的 API Key使用時在請求頭中添加：
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
task_id
string
必填
視頻生成 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 時間戳，僅完成時返回）
​
result
object
任務結果（僅成功時返回）
​
error
object
錯誤信息（僅失敗時返回）

​
任務狀態說明

狀態說明是否終態建議操作
queued任務排隊等待處理❌等待 5-10 秒後重試查詢
in_progress任務正在處理中❌等待 10-15 秒後重試查詢
completed任務成功完成✅從 result.data[0].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 {
                'url': data['result']['data'][0]['url'],
                'format': data['result']['data'][0].get('format'),
                '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小時後過期，請務必及時保存到自己的存儲