媒體指南
Seedance 素材與真人驗證
在 Seedance 中重複使用圖片、影片、音訊或已驗證的真人
Seedance 素材讓您可以重複使用圖片、影片或音訊檔案,而無需在每次生成時重新匯入。引用真人需要取得同意並進行視覺驗證;虛擬人物、產品和風格則無需此步驟。
選擇素材類型
| 您想要重複使用的內容 | 處理方式 |
|---|---|
| 單次使用的單張圖片 | 在支援的圖片欄位中傳送其 URL;這不會建立可重複使用的素材 ID |
| 重複使用虛擬人物、產品或風格 | 建立一個 aigc_avatar 群組,建立資產,等待狀態變為 ACTIVE,然後使用該資產 ID |
| 重複使用真人 | 完成視覺驗證,取得其 GroupId,在該群組中建立資產,等待狀態變為 ACTIVE,然後使用該資產 ID |
| 遷移現有的 Volcengine 素材客戶端 | 保留 Action 請求格式並使用 Volc 相容素材參考 |
群組與素材
| 項目 | REST 欄位 | Action 欄位 | 含義 |
|---|---|---|---|
| 素材群組 | group_id | GroupId | 將相關素材歸類在一起 |
| 素材 | id | Id | 單一匯入的圖片、影片或音訊檔案;在狀態變為 active 後使用此 ID |
| 虛擬人物群組 | library_type: "aigc_avatar" | GroupType: "AIGC" | 不需要真人驗證 |
| 真人群組 | library_type: "liveness_face" | GroupType: "LivenessFace" | 僅透過成功的視覺驗證流程建立 |
| 專案名稱 | project_name | ProjectName | 將不同專案的素材分開;預設為 default |
請將群組 ID 與資產 ID 分開。群組用於組織上傳內容;資產 ID 是影片生成時使用的參考。公開 ID 的格式範例如 group-20260720123456-vrt01 和 asset-20260720123457-def45。
素材保留
TokenLab 會保留每個素材資產,直到您刪除該資產或其所屬群組為止。系統不會因閒置而自動清理。
- 如果資產在使用時需要重新準備,第一次生成可能需要較長時間。如果資產尚未準備就緒,請求將回傳
409 seedance_material_preparing;請稍後重試。 - 刪除資產或群組的操作是永久性的,無法復原。
圖片 URL 與可重複使用素材
在您所選模型支援的圖片欄位中,傳送公開的 HTTP(S) URL 或支援的資料 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 並在重試前修正或重新匯入。使用失敗資產的生成請求會回傳 422 seedance_material_failed 以及 failed_asset_ids。
虛擬人物素材
使用 建立素材資產群組 來建立 aigc_avatar 群組。對於 REST 資產建立,僅當 project_name 為 default 時,group_id 才是選填的;此時 TokenLab 會使用或建立組織預設的虛擬人物群組。若 project_name 非預設值,或涉及任何真人資產,則必須提供 group_id。
群組建立後,可透過以下方式管理:
刪除群組也會刪除其中包含的 TokenLab 素材,且無法復原。
真人驗證
當您的產品需要在重複使用真人作為 Seedance 參考前收集同意並驗證臉部時,請使用此流程。
- 呼叫 建立視覺驗證工作階段 並傳入
CallbackURL;儲存Result.BytedToken並為受驗證者開啟Result.H5Link。 - 在 H5 流程重新導向至回呼網址後,使用相同的
BytedToken和ProjectName輪詢 取得視覺驗證結果。 - 儲存回傳的
Result.GroupId。TokenLab 會在此步驟中建立並綁定LivenessFace群組。 - 使用該群組 ID 建立資產,然後輪詢該資產直到狀態變為
ACTIVE。
BytedToken 的有效期為 30 分鐘。客戶端無法使用 CreateAssetGroup 建立 LivenessFace 群組;這可防止未經驗證的群組被呈現為已驗證狀態。
請在建立後立即開啟回傳的 H5Link。Token的有效期並不代表驗證頁面可以在該時間窗口內的任何時間點首次開啟。
對於真人群組,上傳的內容會與已驗證的臉部進行比對。如果資產包含多張臉孔或臉部不符,資產可能會失敗。為獲得最佳效果,請上傳一張全身正面參考圖以及一張清晰的正面特寫照。
建立並準備資產
使用 建立素材資產 每次匯入一個可公開存取的 URL。
| 類型 | 支援的輸入 |
|---|---|
| 圖片 | jpeg, png, webp, bmp, tiff, gif, heic, heif;≤ 30 MiB;寬度和高度 [300, 6000] px;長寬比 [0.4, 2.5] |
| 影片 | mp4, mov;≤ 200 MiB |
| 音訊 | aac, wav, mp3;≤ 15 MiB |
以上為檔案匯入限制。成功的匯入請求並不保證媒體或真人驗證會通過。請等待狀態變為 ACTIVE;如果資產狀態變為 FAILED,請使用 error_message 修正來源後再重新匯入。
素材擷取是非同步的。請輪詢 取得素材資產 直到 status 變為 ACTIVE。HTTP 成功僅代表匯入請求已被接受,並不代表資產已準備就緒。如果資產狀態變為 FAILED,請檢查 error_message,修正來源並建立新資產。
來源 URL 僅用於匯入。TokenLab 會回傳其專屬的資產 ID,並將資產保留在您組織的素材庫中,直到您刪除該資產或其群組為止。
在影片生成中使用資產
當資產狀態為 ACTIVE 後,在呼叫 建立影片 時選擇以下其中一種形式:
material_asset_id:用於單一通用素材參考material_asset_ids:用於多個通用參考asset://<asset-id>:用於image_url、start_image、end_image或reference_images,當媒體角色必須明確指定時
素材參考會計入所選模型的 Seedance 參考限制。如果 API 回傳 Seedance material asset not found or not accessible,請確認該值為資產 ID 而非群組 ID,且該資產屬於同一個組織與專案、未被刪除,且狀態為 ACTIVE。
REST 或 Volcengine Action
TokenLab 原生整合可繼續使用 snake_case 的 /v1/videos/assets* REST 端點。現有的 Volcengine 客戶端可透過 素材 Action (Volc 相容) 保留 PascalCase 請求主體。兩種介面皆操作相同的組織與專案範圍素材資料。
REST 範例:虛擬人物資產
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","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
-H "Authorization: Bearer $TOKENLAB_API_KEY"Action 範例:已驗證的真人資產
首先建立並完成視覺驗證:
curl 'https://api.tokenlab.sh/?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/?Action=GetVisualValidateResult&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'然後將回傳的 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 傳遞給影片生成。關於所有 10 個 Action 操作、篩選器、分頁、回應格式與錯誤,請參閱 素材 Action (Volc 相容)。