TokenLab Seedance Materials：適用於製作工作流程的可重複使用影片參考素材

如果您的團隊曾經將同一個換臉 URL 貼到三個不同的 API 呼叫中，您就已經知道為什麼需要 Seedance 素材庫了。可重複使用的影片參考作為具有生命週期狀態的資產，比從試算表中複製並貼上到每個生成請求中的一次性 URL 更有效。TokenLab 將這些資產限定在您的組織範圍內，因此您可以在不同的呼叫中儲存、驗證並重複使用參考資料。我們測試了工作流程的結構：群組用於組織真人素材，資產用於保存實際參考，而生成呼叫僅在狀態達到 ACTIVE 後才使用 ID。例如，一個曾經維護著包含圖片連結的試算表並將同一個參考影片重複上傳五次的團隊，現在可以用一個素材資產 ID 來取代這種習慣。

重點摘要

• 素材資產 (material asset) 是可供生成的參考物件；素材群組 (material group) 是組織相關資產的容器，特別適用於真人工作流程。
• 僅在素材資產的狀態達到 ACTIVE 後，才將其 id 用作 material_asset_id（或放入 material_asset_ids 中）。
• 存在兩種庫類型：用於虛擬化身和其他非真人可重複使用參考的 aigc_avatar，以及用於需要驗證的真人素材群組的 liveness_face。
• TokenLab 可以自動將相容的圖片輸入（image、image_url、image_urls、reference_images、start_image、end_image）準備為素材資產，無需額外的上傳步驟。
• 如果準備時間超過 60 秒，API 會回傳 409 seedance_material_preparing 以及您可以輪詢並重試的 auto_material_asset_ids。
• Seedance 是此素材系統目前支援的公開模型系列。在建立對特定層級的依賴之前，請先在文件中確認每個模型的確切功能細節。

Seedance 素材庫：資產與群組

Seedance 素材是一種可重複使用的參考資料（圖片、影片或音訊），TokenLab 將其儲存為組織範圍內的資產，而非請求範圍內的 URL。與其在每個 create-video 呼叫中傳遞原始檔案連結，不如將參考資料上傳或匯入一次，等待其準備就緒，然後根據需要多次透過 ID 進行引用。

這在三個實際層面上很重要。首先，重複上傳會浪費頻寬並增加每個請求的延遲，特別是對於大型參考影片。其次，原始 URL 會過期、被輪替或被最初託管它們的儲存系統撤銷。由 TokenLab 管理的素材資產則沒有這種脆弱性。第三，對於建立角色一致或品牌一致的影片管線的團隊來說，素材提供了一個穩定的識別碼，您可以對其進行版本控制、審核和替換，而無需每次都更動您的生成邏輯。

素材資產 vs. 素材群組

此系統中的兩個核心物件是素材資產和素材資產群組。如果您沒有仔細閱讀 API 參考文件，很容易將它們混淆。

素材資產 (material asset) 是單一參考物件——一個化身圖片、一個經過真人活體驗證的臉部、一個參考影片剪輯。當您建立它時，API 會回傳一個 id。一旦資產達到 ACTIVE 狀態，您最終就會將該 id 傳遞到影片生成呼叫中。

素材資產群組 (material asset group) 是由 group_id 識別的容器。群組將相關資產組織在一起。它們在真人 (liveness_face) 工作流程中是結構上必需的，在這種流程中，必須先在群組層級進行驗證，然後才能將個別資產上傳到其中。

簡而言之：group_id 用於組織；material_asset_id 用於生成。您會在 API 的不同部分看到這兩個欄位。在錯誤的地方使用錯誤的欄位是團隊在使用此系統時最常見的整合錯誤。

欄位	識別內容	使用位置
group_id	素材資產群組（容器）	建立或引用群組，特別是用於真人驗證流程
id (在素材資產上)	單一可重複使用參考	一旦 ACTIVE 即成為 material_asset_id
material_asset_id	單一資產參考	傳遞至 create-video 以進行一個參考插槽
material_asset_ids	資產參考陣列	當需要多個可重複使用參考時傳遞至 create-video

完整的欄位定義和必要參數記錄在 create material asset 和 create material asset group API 參考中。在將其寫入生產程式碼之前，請先閱讀這些文件。文件涵蓋了工作流程的結構，而非每個請求參數。

虛擬化身與真人工作流程

Seedance 素材支援兩種庫類型。這種區別並非僅是表面上的——它反映了兩種不同的安全和同意立場。

aigc_avatar：虛擬化身與非真人參考

aigc_avatar 類型涵蓋了未與經過驗證的真人綁定的可重複使用參考：插畫角色、合成化身、風格化人物、產品吉祥物和類似資產。您可以直接透過素材資產建立流程來建立這些資產，而無需驗證步驟。

如果您的產品圍繞虛構角色或品牌化身生成影片，這幾乎肯定就是您需要的庫類型。它的建立路徑更簡單，因為沒有附加身分驗證要求。

liveness_face：真人素材群組

liveness_face 類型適用於圍繞真人肖像建立的素材群組。這是一種用於包含實際個人的臉部一致性影片生成的參考資料。由於這涉及身分和同意，TokenLab 要求在將資產上傳到群組之前進行驗證流程。

驗證序列有幾個不同的步驟：

1. 建立工作階段 (Session creation) — 您的後端請求為該群組建立驗證工作階段。
2. H5 流程 (H5 flow) — 被驗證者透過託管的 Web 流程完成活體檢測。H5 指的是行動網頁驗證介面。
3. 回呼 (Callback) — 當驗證工作階段結束時，TokenLab 會通知您的系統。
4. 綁定結果 (Bind result) — 驗證後的身分被綁定到素材群組。
5. 群組範圍上傳 (Group-scoped uploads) — 只有在綁定成功後，才能將素材資產上傳到該特定群組。

這意味著真人素材本質上是「群組優先」的。您不能像使用 aigc_avatar 那樣直接跳到建立資產。群組必須存在並通過驗證，之後上傳到其中的任何資產才有效。

檢查清單：選擇正確的庫類型

• 該參考資料是真實、可識別的人臉或肖像嗎？→ 使用 liveness_face 並規劃驗證流程。
• 該參考資料是合成的、插畫的或非真人化身嗎？→ 使用 aigc_avatar 並跳過驗證。
• 您的產品是否需要在同一個真人的多次生成中保持身分一致？→ 建立一次群組，驗證一次，並為未來的資產重複使用該群組。
• 您不確定客戶提供的參考資料屬於哪種類型嗎？→ 在確認之前將其視為 liveness_face；請查閱文件，不要假設。

不要假設每個生成模型或每個請求類型都以相同方式支援這兩種庫類型。在提交架構之前，請在 Seedance Video Models guide 中確認目前的支援情況。

自動素材準備的工作原理

並非每個參考資料都需要手動上傳步驟。TokenLab 可以自動將相容的圖片輸入準備為素材資產，作為生成請求的一部分。這減少了簡單情況下的往返次數。

它識別的自動準備欄位包括：

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

如果您將其中任何一個直接傳遞到生成呼叫中，TokenLab 會在後台處理匯入和準備工作。您無需先單獨呼叫素材資產端點。

當準備時間超過 60 秒時會發生什麼

準備工作通常很快。較大或較複雜的參考圖片可能需要較長時間才能處理為可供生成的資產。如果準備時間超過 60 秒，API 會回應：

409 seedance_material_preparing

以及包含仍在準備中的資產 ID 的 auto_material_asset_ids 欄位。

這在傳統意義上並非錯誤。這是一個重試的訊號。您的整合應將 409 seedance_material_preparing 視為「稍後再檢查」的回應，而不是呈現給終端使用者的失敗。輪詢回傳的資產 ID，等待 ACTIVE 狀態，然後使用這些 ID 繼續進行生成。

在我們的管線中，我們將此狀態視為速率限制退避 (rate-limit backoff)：它是預期的、暫時的，並在程式碼中處理，而不是作為面向使用者的錯誤報告。我們建議使用一個小的重試迴圈，而不僅僅是單一的 try/catch。

在生成中使用 Seedance 素材庫

一旦素材資產（無論是手動上傳還是自動準備）達到 ACTIVE 狀態，其 id 即可在 create video 呼叫中用作 material_asset_id 或作為 material_asset_ids 中的一個項目。

核心工作流程如下：

1. 決定參考資料是否為真人。據此選擇 liveness_face（需驗證）或 aigc_avatar。
2. 如果是真人：建立素材群組，執行驗證工作階段和 H5 流程，接收回呼，並綁定結果。
3. 建立或匯入素材資產 — 透過直接上傳呼叫，或讓自動準備處理生成請求中的相容圖片欄位。
4. 檢查狀態。在資產回報 ACTIVE 之前，請勿將其 ID 傳遞到生成中。
5. 如果您收到 409 seedance_material_preparing，請輪詢回傳的 auto_material_asset_ids，並在它們解析為 ACTIVE 後重試。
6. 在您的 create-video 呼叫中將 id 用作 material_asset_id 或放入 material_asset_ids 中，並根據您的延遲和品質需求鎖定目前的 Seedance 模型。
7. 在未來的生成呼叫中重複使用相同的資產 ID，而不是重新上傳參考資料。

這也是任務管理很重要的原因。建立在重複使用素材資產上的生成呼叫可能需要在執行中途停止。這可能是出於成本控制、創意簡報變更或提示詞不佳的原因。請參閱我們關於 Seedance task cancellation 的配套文章，了解取消操作如何與執行中的影片作業互動。

如需更廣泛地比較 TokenLab 上目前可用的影片生成模型，影片模型分類頁面並列了目前的選項。

實際後續步驟

• 如果您正在進行原型設計，請從 aigc_avatar 素材開始。建立路徑更簡單，且沒有需要先建立的驗證依賴項。
• 如果您的產品需要真人一致性，請將驗證流程（工作階段 → H5 → 回呼 → 綁定）建構為您入職流程的一等公民，而不是外掛功能。
• 在將任何內容發佈到生產環境之前，請為 409 seedance_material_preparing 新增重試迴圈。將其視為預期行為，而非邊緣情況。
• 將素材資產 ID 與您自己的內部參考記錄一起儲存。這樣您就不會重新推導哪個資產對應哪個角色或產品。
• 直接查閱 material asset 和 material asset group API 參考。文件描述了工作流程的結構，在編寫整合程式碼之前，應根據目前的文件確認確切的請求/回應欄位。

Seedance 資產儀表板顯示了您已建立資產的狀態、庫類型和群組關係。

我們 AI video API pricing 2026 概覽中的目前費率可協助您了解成本如何隨使用量擴展。您也可以使用 TokenLab dashboard usage exports 中的指南來追蹤和匯出您自己的使用數據。

常見問題解答

素材資產和素材群組有何不同？

素材資產是單一可重複使用的參考物件——一個化身圖片、一個經過真人活體驗證的臉部、一個參考影片剪輯。一旦 ACTIVE，其 id 即成為 material_asset_id。素材群組是由 group_id 識別的容器。群組用於組織相關資產，並且是 liveness_face 工作流程所必需的。簡而言之：group_id 用於組織；material_asset_id 用於生成。

為什麼生成呼叫會回傳 409 seedance_material_preparing？

由相容圖片欄位（如 image_url 或 start_image）觸發的自動素材準備可能需要超過 60 秒的時間。發生這種情況時，API 會回傳 409 seedance_material_preparing 以及 auto_material_asset_ids。輪詢這些 ID，等待 ACTIVE，然後重試生成。這表示暫時的處理中狀態，而非失敗。

真人參考資料是否總是需要驗證？

是的。每當參考資料涉及實際可識別的人臉或肖像時，請使用 liveness_face 類型及其驗證流程。該流程需要在將任何資產上傳到該群組之前，進行工作階段建立、H5 活體檢測、回呼和綁定步驟。非真人參考資料（例如插畫或合成化身）使用 aigc_avatar，不需要此路徑。

我可以在多個 Seedance 影片作業中重複使用同一個素材資產嗎？

可以，一旦資產達到 ACTIVE 狀態即可。在 create-video 呼叫中將其 id 用作 material_asset_id 或放入 material_asset_ids 中。在未來的生成呼叫中重複使用相同的資產 ID，而不是重新上傳參考資料。如果您需要停止執行中的作業，請參閱 Seedance task cancellation。

來源與時效性

• Seedance Video Models guide — https://docs.tokenlab.sh/guides/seedance-2-video — 觀察日期 2026-07-09
• Create Seedance material asset (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — 觀察日期 2026-07-09
• Create Seedance material asset group (API reference) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — 觀察日期 2026-07-09
• Create video (API reference) — https://docs.tokenlab.sh/api-reference/video/create-video — 觀察日期 2026-07-09
• TokenLab Seedance assets dashboard — /dashboard/seedance-assets — 觀察日期 2026-07-09

此處描述的 API 行為、欄位名稱和狀態語義反映了截至觀察日期的公開文件和儀表板內容。TokenLab 的 Seedance 素材系統正在積極開發中——在最終確定生產整合程式碼之前，請在連結的文件中確認目前的參數名稱、狀態值和模型特定支援。

如果您正在建立依賴於穩定、可重複使用參考資料的影片管線，請從 Seedance Video Models guide 開始。這是查看目前參數名稱並確認您的目標模型層級實際支援哪些功能的捷徑。