Skip to main content
GET
  • 查詢異步視頻生成任務的執行狀態和結果
  • 實時狀態更新和進度跟蹤
  • 任務完成時獲取生成的視頻
  • 支持多語言返回(zh/en/ko/ja)
所有視頻生成任務都是異步執行的。提交任務後,您需要通過查詢接口獲取任務狀態和結果。

創建任務時傳入業務 ID

創建視頻任務時,可以在請求體頂層傳入 client_business_id。該字段用於保存您系統內的訂單號、流水號或業務任務 ID,方便後續按業務 ID 查詢生成結果。
也兼容放在 metadata.client_business_id 中,但推薦使用頂層字段。

Authorizations

string
必填
所有接口均需要使用 Bearer Token 進行認證獲取 API Key:訪問 API Key 管理頁面 獲取您的 API Key使用時在請求頭中添加:

Path Parameters

string
必填
視頻生成 API 返回的任務 ID。也可以傳創建任務時提交的 client_business_id,用於按客戶側業務 ID 查詢任務狀態和結果。
如果創建視頻任務時傳入 client_business_id,可直接使用同一個狀態查詢接口: GET /v1/videos/generations/{client_business_id}。業務 ID 會限定在當前 API Key 所屬用戶下查詢。

Response

string
任務唯一標識符
string
客戶側業務 ID。僅當創建任務時傳入 client_business_id 時返回。
string
對象類型,固定爲 generation.task
string
使用的視頻生成模型
string
任務狀態
  • queued - 排隊等待處理
  • in_progress - 處理中
  • completed - 成功完成
  • failed - 失敗
integer
任務進度百分比(0-100)
integer
任務創建時間(Unix 時間戳)
integer
任務完成時間(Unix 時間戳,僅完成時返回)
integer
視頻 URL 過期時間(Unix 時間戳,僅完成時返回)
object
任務結果(僅成功時返回)
object
模型工具用量。Seedance 2 啓用 tools: [{ "type": "web_search" }] 時,usage.tool_usage.web_search 表示實際聯網搜索次數;0 表示未搜索。
object
錯誤信息(僅失敗時返回)

任務狀態說明

輪詢策略建議

Python 輪詢示例

視頻資源有效期

生成的視頻 URL 有效期爲 24 小時
  • 請在有效期內下載保存視頻
  • expires_at 字段標識視頻過期時間(Unix 時間戳)
  • 視頻過期後無法訪問,如需重新獲取,需要重新提交生成任務
  • 縮略圖與視頻同步過期

常見錯誤

性能建議

視頻生成耗時較長,建議:
  1. 使用 ToAPIs 統一任務 Webhook:以 Webhook 為主,輪詢為後備
  2. 合理設置輪詢間隔:至少5~10秒並加入抖動;429 時讀取 Retry-After 後指數退避
  3. 設置超時時間:長視頻生成可能需要5-10分鐘,請設置合理的超時
  4. 及時下載保存:視頻24小時後過期,請務必及時保存到自己的存儲
限流詳見 非同步任務速率限制。批次查詢最多 100 個任務。