Skip to main content
GET
中國大陸用戶請注意: 中國大陸用戶請使用 https://toapis.cn 作為接口地址(Base URL)。文檔示例中的 https://toapis.com 請替換為 https://toapis.cn。
  • 查詢異步視頻生成任務的執行狀態和結果
  • 實時狀態更新和進度跟蹤
  • 任務完成時獲取生成的視頻
  • 支持多語言返回(zh/en/ko/ja)
所有視頻生成任務都是異步執行的。提交任務後,您需要通過查詢接口獲取任務狀態和結果。
Seedance 影片任務需要素材審核時也透過本接口查詢. queued 可能包含素材準備與審核等待, 返回任務不表示影片已開始生成. 預設每輪準備期限為 20 分鐘, 後續影片生成時間另計; 失敗原因請查看 error.message.
一般圖片和影片任務也可透過 GET /v1/tasks/{task_id} 查詢, usage 和 billing 採用相同口徑. 本頁描述的是頁首生成任務查詢路徑的回應. 以下範例用於展示欄位, 不代表模型目前的價格或固定計費方式. 實際欄位與金額以本次任務回傳為準.

Seedance 原始位址與備用位址

啟用原始位址交付的 Seedance 任務, result.data[].url 保留上游原始影片 URL. 用戶端應優先使用 url, 只有該位址無法存取時才切換到同一結果項目的 fallback_url. 平台不會根據用戶端所在地區自動切換位址. 備用欄位皆為可選: 只有副本準備成功時才回傳. 未啟用原始位址交付, 備用副本不可用或歷史任務沒有副本時, 欄位可能省略; 省略不表示生成失敗. 尾幀同樣優先使用 last_frame_url, 無法存取時再使用 fallback_last_frame_url. 備用位址不會延長原始 URL 的有效期, 需要長期保存時請及時下載.

創建任務時傳入業務 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 時間戳. 目前用於 Seedance Global; generation.updated_at 是上游更新時間.
integer
任務創建時間(Unix 時間戳)
integer
任務結束時間, Unix 時間戳. 本頁查詢路徑在任務成功或失敗且已儲存結束時間時回傳.
integer
任務完成時間(Unix 時間戳,僅完成時返回)
integer
視頻 URL 過期時間(Unix 時間戳,僅完成時返回)
object
任務結果(僅成功時返回)
object
可選的 Seedance 生成中繼資料. 僅回傳已儲存且可公開的欄位, 不補預設值. 這些參數描述生成任務, 不取代頂層 usage 的計費量.generation.usage 是保留相容性的舊欄位, 可包含 completion_tokens 和 total_tokens. 它可能缺少或與最終計費量不同, 不與頂層 usage 相加; 讀取計費量時使用頂層 usage.
object
可選的計費量, 影片 token 明細及工具次數. 各欄位的單位及省略規則見任務用量欄位.charge_type 到 input_images 是計費量, 只與 billing.status=settled 同時回傳. 固定價影片按提交時確認的數量回傳, 按實際時長或 token 結算的影片按最終結算數量回傳. 未回傳的欄位直接省略, 不補零.
object
選填的平台計費狀態和已確認費用. 計費狀態獨立於任務生成狀態, completed 不保證已經結算. 缺少此物件不代表任務免費. 詳見價格與實際費用.任務 Webhook 的 data.billing 使用相同的確認條件和取值.
object
錯誤信息(僅失敗時返回)一般錯誤碼和訊息為字串. Seedance Global 的 error.code 和 error.message 保留上游原始 JSON 值, 包括數字或 null; 上游缺少時不補平台預設值.

任務狀態說明

輪詢策略建議

Python 輪詢示例

視頻資源有效期

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

錯誤碼與失敗原因

請求錯誤與任務失敗的差異, 具體原因及處理方式, 請見錯誤碼速查. 查詢成功仍需檢查任務狀態, HTTP 狀態不是業務錯誤碼.

性能建議

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