Seedance 素材與真人驗證

Seedance 素材是組織範圍內可重用的圖片、影片或音訊參考。請先選擇工作流程：一般虛擬人素材和已驗證真人素材的建立路徑不同。

選擇素材工作流程Copy Anchor Link

素材概念Copy Anchor Link

Seedance 素材是可重複使用、以組織為範圍的參考資料，可在影片生成過程中選取。

請區分 group_id 與素材資產 id。group_id 用於組織上傳內容；素材資產 id 用於影片生成。若影片請求回傳 Seedance material asset not found or not accessible，請確認您傳入的是素材資產 id 而非 group_id，且該資產屬於同一組織、未被刪除，且狀態為 status: "ACTIVE"。

素材有效期Copy Anchor Link

TokenLab 會保留每個素材，直到您刪除該素材或其所在素材群組。TokenLab 這一側不會因為長期未使用而清理素材。

上游 Seedance 服務方可能在素材 30 天未被使用後，清理其自身的工作副本。這不會刪除您的素材，也不會改變素材 ID：下次在生成請求中使用時，TokenLab 會自動根據已儲存的原始檔案重新準備一份上游副本。

• 清理後的首次生成可能稍慢，因為需要準備新的副本。若副本尚未就緒，請求會回傳 seedance_material_preparing，請稍後重試。
• 刪除素材或素材群組是永久操作，無法復原。

圖片 URL 與可重用素材Copy Anchor Link

可在所選模型支援的圖片欄位中傳入公開 HTTP(S) URL 或支援的 data URL。這些輸入沿一般媒體路徑處理，不會自動建立可重用的素材 ID。

需要重用時，先透過素材 API 建立素材，等待 ACTIVE，再使用 material_asset_id、material_asset_ids 或支援媒體欄位中的 asset://<id>。保留首幀、尾幀或參考圖的原本用途。

明確指定的素材仍在準備時，POST /v1/videos/generations 回傳 409 seedance_material_preparing，並以 inactive_asset_ids 列出相關素材。查詢直到 ACTIVE，再用相同素材 ID 重試。若為 FAILED，先依 error_message 修正或重新匯入。

真人素材驗證Copy Anchor Link

當您的產品在將真人作為可重複使用的 Seedance 參考資料前，需要取得同意並進行人臉驗證時，請使用真人素材驗證。

1. 呼叫 建立視覺驗證會話，傳入 CallbackURL，並儲存回傳的 Result.BytedToken。
2. 為待驗證人員開啟 Result.H5Link。若需要特定語言，請在 H5 連結後附加 lng。
3. H5 流程完成後，瀏覽器會開啟 Result.CallbackURL，並帶有 bytedToken、resultCode 等官方查詢參數。
4. 使用 BytedToken 輪詢 取得視覺驗證結果，直到回傳 Result.GroupId。
5. 儲存 GroupId；建立 liveness_face 素材時將其作為 group_id。

BytedToken 的有效期限為 30 分鐘。兩個 Action 請求必須使用相同的 ProjectName。驗證使用 Authorization: Bearer <TOKENLAB_API_KEY>；不接受火山引擎 AK/SK 簽名。

建立後立即開啟回傳的 H5Link。Token 有效期不代表可在這段期間的任意時間首次開啟驗證頁面。

選用：使用 測試控制台 來驗證您的請求與回呼流程、檢查素材群組並查看驗證紀錄。正式環境整合應直接呼叫 API。

建立素材群組Copy Anchor Link

針對 aigc_avatar 群組，請使用 建立素材資產群組。新的真人素材群組是透過驗證流程建立的，以確保已驗證的人物與素材群組保持連結。

使用 列出素材資源群組、取得素材資源群組、更新素材資產群組 和 刪除素材資源群組 來管理現有的群組。

刪除素材群組會同時刪除其中的 TokenLab 素材，且無法復原。若 TokenLab 素材庫因目前的授權狀態不允許而無法完成刪除，TokenLab 將回傳中性的素材庫錯誤。

上傳素材Copy Anchor Link

使用 建立素材資產 每次匯入一個可公開存取的來源 URL。

對於 aigc_avatar，group_id 為選填；TokenLab 會使用或建立組織預設的虛擬人像群組。對於 liveness_face，group_id 為必填，且必須是 取得視覺驗證結果 所回傳的群組。

上表是檔案匯入限制。匯入請求成功不代表媒體或真人驗證已通過。請等待 ACTIVE；若變為 FAILED，依 error_message 修正來源後再匯入。

素材擷取為非同步處理。請輪詢 取得素材資源 (Get Material Asset) 直到 status 變為 ACTIVE。成功的 HTTP 回應僅代表請求已被接受；請務必讀取業務狀態。若狀態為 FAILED，請檢查 error_message，修正來源素材並建立新資產。

在建立素材請求中，asset_url 只表示匯入來源。TokenLab 會回傳素材資產 id；產生影片時請使用這個 id，不要繼續使用原始 URL。

TokenLab 會將素材保留在您的組織素材庫中，直到您刪除該素材或其所在素材群組；上游副本被清理後會自動重建，詳見上方素材有效期說明。

對於真人素材群組，一個群組對應一位真人。上傳內容會與已驗證的人臉進行比對。包含多張人臉或人臉與已驗證人物不符的資產可能會失敗。為獲得最佳效果，請同時上傳全身正面參考圖與臉部清晰的正面特寫照。

在影片生成中使用素材Copy Anchor Link

當資產狀態為 ACTIVE 後，在呼叫 建立影片 時，將回傳的 TokenLab 資產 id 作為 material_asset_id 傳入，或包含在 material_asset_ids 中。素材資產會計入 Seedance 參考限制。

REST 或火山 ActionCopy Anchor Link

TokenLab 原生整合可繼續使用 snake_case 的 /v1/videos/assets* REST 介面。既有火山用戶端可保留 PascalCase 請求內容並使用火山相容素材 Action。兩套介面操作同一份組織與專案範圍內的素材資料。

API 範例Copy Anchor Link

建立一個虛擬人像群組、上傳圖片、輪詢直到其啟用，然後在影片請求中使用該素材資產 ID。

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_type":"Image"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

對於真人素材群組，請先建立視覺驗證會話並取得結果，再上傳素材。

curl 'https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/api/v3?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"ZXhhbXBsZS10b2tlbg","ProjectName":"default"}'

完整的真人 Action 流程Copy Anchor Link

取得驗證結果回傳的 GroupId 後，將它傳給 CreateAsset：

curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260720123456-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

輪詢 GetAsset 直到狀態變成 Active，再於影片生成中使用回傳的素材 ID。