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

當可重複使用的影片參考作為具有生命週期狀態的資產，而非每次生成請求都複製一次性 URL 時，管理起來會更加容易。如果您曾經維護過一張包含圖片連結的試算表、將同一個參考影片重新上傳了五次，或是將同一個換臉 URL 重複輸入到三個不同的 API 呼叫中，那麼您已經理解 Seedance 素材旨在解決的問題。

TokenLab 的 Seedance 素材庫為影片團隊提供了一種組織級的儲存、驗證及重複使用生成請求參考的方式。本文將說明什麼是素材資產、素材群組與個別資產之間的關聯、自動準備功能的運作方式，以及真人驗證在工作流程中的定位。

重點摘要

• 素材資產 (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 2.0、Seedance 2.0 Fast 和 Seedance 2.0 Mini 是此素材系統目前支援的公開模型。在建立特定層級的依賴關係之前，請務必在文件中確認各模型的詳細能力細節。

什麼是 Seedance 素材

Seedance 素材是一種可重複使用的參考（圖片、影片或音訊），TokenLab 將其儲存為組織級資產，而非請求級 URL。您無需將原始檔案連結傳入每次的 create-video 呼叫，而是上傳或匯入參考一次，等待其準備就緒，然後在後續所需的任意多次呼叫中透過 ID 引用它。

這在實務上有三個重要原因。

首先，重複上傳會浪費頻寬並增加每次請求的延遲，特別是對於大型參考影片而言。

其次，原始 URL 可能會過期、輪替或被原始託管的儲存系統撤銷。由 TokenLab 管理的素材資產則沒有這種脆弱性。

第三，對於建立角色一致性或品牌一致性影片管線的團隊來說，素材提供了一個穩定的識別碼，您可以對其進行版本控制、稽核和替換，而無需每次都更動生成邏輯。

素材資產與素材群組

此系統中的兩個核心物件是素材資產與素材資產群組，如果您沒有仔細閱讀 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」的含義：行動網頁驗證介面）。
3. 回呼 (Callback) — 當驗證工作階段結束時，TokenLab 會通知您的系統。
4. 綁定結果 (Bind result) — 將驗證過的身分綁定到素材群組。
5. 群組級上傳 — 只有在綁定成功後，才能將素材資產上傳到該特定群組。

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

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

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

請勿假設每個生成模型或每個請求類型都以相同方式支援這兩種庫類型——在投入架構之前，請在 Seedance 2.0 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 繼續進行生成。

實際上，這意味著您的生成管線需要一個小的重試迴圈，而不僅僅是一個 try/catch。建立自動化影片管線的團隊應將此狀態視為與處理速率限制 (rate-limit) 退避相同的方式——這是預期內、暫時性的，應在程式碼中處理，而不是回報為使用者可見的錯誤。

如何在生成中使用素材

一旦素材資產（無論是手動上傳還是自動準備）達到 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 模型，例如 seedance-2.0、seedance-2.0-fast 或 seedance-2.0-mini。
7. 在未來的生成呼叫中重複使用同一個資產 ID，而不是重新上傳參考。

這也是任務管理重要的地方。如果基於重複使用素材的生成呼叫需要在執行中途停止——為了成本控制、創意簡報變更或提示詞錯誤——請參閱我們關於 Seedance task cancellation 的配套文章，了解取消操作如何與執行中的影片工作互動。

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

實務上的後續步驟

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

您可以直接在 Seedance assets dashboard 中瀏覽素材庫，查看您已建立資產的狀態、庫類型與群組關係。

在投入生產工作流程之前，值得檢閱我們 AI video API pricing 2026 概覽中的目前費率，以了解成本如何隨使用量擴展。您也可以使用 TokenLab dashboard usage exports 中的指引來追蹤並匯出您自己的使用數據。

常見問題

什麼是 Seedance 素材資產？ 素材資產是一種可重複使用的影片生成參考——圖片、影片或音訊——儲存為具有自身生命週期狀態的組織級物件。一旦達到 ACTIVE，您就可以透過 ID 在多次生成呼叫中引用它，而無需每次都重新提供原始 URL。

group_id 與 material_asset_id 有什麼區別？ group_id 識別素材資產群組，這是一個主要用於組織真人 (liveness_face) 資產並在群組層級管理驗證的容器。material_asset_id 識別單一可重複使用參考——即建立素材資產時回傳的 id——這正是您傳入影片生成呼叫的內容。

我什麼時候應該使用真人驗證？ 當參考素材涉及實際可識別的人臉或肖像時，請使用 liveness_face 類型及其驗證流程。該流程需要工作階段建立、H5 活體檢查、回呼以及綁定步驟，之後才能將任何資產上傳到該群組。非真人參考（如插畫或合成頭像）使用 aigc_avatar，且不需要此驗證路徑。

seedance_material_preparing 是什麼意思？ 這是一個 409 回應，當自動素材準備（由生成請求中的相容圖片欄位如 image_url 或 start_image 觸發）完成時間超過 60 秒時會回傳。回應包含 auto_material_asset_ids，以便您可以輪詢這些 ID，並在它們變為 ACTIVE 後重試生成。它代表的是暫時性的進行中狀態，而非失敗。

來源與時效性

• Seedance 2.0 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 — https://tokenlab.sh/en/dashboard/seedance-assets — 觀察日期 2026-07-09

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

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