視頻與素材
素材操作 (Volc 相容)
10 個 Volcengine 相容素材與素材群組操作的參考指南。
這些端點支援下方列出的素材操作與欄位,並使用 TokenLab Bearer 驗證以及 ResponseMetadata + Result 封裝格式。
端點與驗證
POST https://api.tokenlab.sh/?Action=<ACTION>&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/json亦支援 POST /api/v3?Action=<ACTION>&Version=2024-01-01。所有素材操作僅限使用 POST。不接受 Volcengine AK/SK 簽章;若請求未包含有效的 TokenLab Bearer 金鑰,將回傳 401 InvalidCredential。
ProjectName 預設為 default,是已驗證組織內部的實際隔離邊界。在建立、列出、讀取、更新或刪除相關群組與資產時,請使用相同的值。
素材群組操作 (Material-Group Actions)
| 操作 (Action) | 用途 | 請求主體 (Request body) |
|---|---|---|
CreateAssetGroup | 建立虛擬人素材群組 | Name;選填 Description;選填 GroupType: "AIGC";ProjectName |
ListAssetGroups | 列出專案中的群組 | 選填 Filter.GroupIds, Filter.GroupType, Filter.Name;PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAssetGroup | 讀取單一群組 | Id, ProjectName |
UpdateAssetGroup | 修改群組名稱或描述 | Id;Name 及/或 Description;ProjectName |
DeleteAssetGroup | 刪除群組及其資產 | Id, ProjectName |
CreateAssetGroup 僅接受 GroupType: "AIGC"。LivenessFace 群組是透過成功的真人驗證所建立,而非透過此操作。ListAssetGroups 可同時篩選 AIGC 與 LivenessFace 群組。Name 長度為 1–64 個字元,Description 最長為 300 個字元,這比 /v1/videos/assets* REST 端點的限制更短。
建立群組
curl 'https://api.tokenlab.sh/?Action=CreateAssetGroup&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"Name":"Product references",
"Description":"Reusable product shots",
"GroupType":"AIGC",
"ProjectName":"default"
}'{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAssetGroup",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": { "Id": "group-20260720123456-abc12" }
}素材操作 (Material-Asset Actions)
| 操作 (Action) | 用途 | 請求主體 (Request body) |
|---|---|---|
CreateAsset | 匯入公開的圖片、影片或音訊 URL | GroupId, URL, Name, AssetType, ProjectName |
ListAssets | 列出專案中的資產 | 選填 Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name;PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAsset | 讀取單一資產及其暫時 URL | Id, ProjectName |
UpdateAsset | 重新命名資產 | Id;選填 Name;ProjectName |
DeleteAsset | 刪除單一資產 | Id, ProjectName |
AssetType 接受 Image、Video 或 Audio。目標群組決定了該資產是普通的 AIGC 素材還是已驗證的 LivenessFace 素材。
建立資產
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-abc12",
"URL":"https://example.com/reference.png",
"Name":"Front view",
"AssetType":"Image",
"ProjectName":"default"
}'請使用 TokenLab 素材 ID。CreateAsset 會在處理完成前先回傳 Result.Id;請輪詢 GetAsset 直到 Result.Status 變為 Active 或 Failed。ListAssets 也支援 SortBy: "GroupId"。
列表行為
PageNumber 預設為 1;PageSize 預設為 10,最大接受 100。SortBy 接受 CreateTime 或 UpdateTime;SortOrder 接受 Desc 或 Asc。
列表回應會回傳:
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [],
"TotalCount": 0,
"PageNumber": 1,
"PageSize": 10
}
}資產狀態值為 Active、Processing 與 Failed。GetAsset 與 ListAssets 會回傳一個有效期為 12 小時的暫時 URL;請勿將其儲存為永久的資產識別碼,應儲存 Id。
結果 (Results)
| 操作 (Action) | Result (主要欄位) |
|---|---|
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset | { "Id": "..." } |
DeleteAssetGroup, DeleteAsset | {} |
GetAssetGroup | Id, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime |
GetAsset | Id, GroupId, Name, AssetType, URL, Status, Error (Code 與 Message,除非資產失敗否則為空), ProjectName, CreateTime, UpdateTime |
時間為 ISO 8601 字串。ListAssetGroups 與 ListAssets 會在 Result.Items 中回傳這些物件。
真人素材 (Real-Person Materials)
在匯入真人素材前:
- 呼叫 建立視覺驗證工作階段。
- 完成 H5 驗證流程。
- 呼叫 取得視覺驗證結果 直到其回傳
Result.GroupId。 - 使用該已驗證的群組 ID 呼叫
CreateAsset。
上傳至 LivenessFace 群組的內容會與已驗證的人臉進行比對。DeleteAssetGroup 無法刪除已驗證的真人群組;若嘗試刪除,將回傳 409 OperationDenied。
錯誤 (Errors)
錯誤會保留 Volcengine 的回應封裝格式,並將代碼與訊息置於 ResponseMetadata.Error 下。
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing",
"Error": {
"Code": "InvalidParameter",
"Message": "GroupId is required"
}
}
}常見代碼包括 InvalidCredential、InvalidVersion、InvalidParameter、ResourceNotFound、Conflict、OperationDenied、MethodNotAllowed、AccessDenied、FlowLimitExceeded 與 InternalError。HTTP 狀態碼:錯誤請求為 400,群組或資產缺失為 404,衝突為 409,非 POST 方法為 405。
REST 替代方案
TokenLab 的 /v1/videos/assets* REST 端點仍然可用。新的 TokenLab 原生整合可能更偏好其 snake_case 格式的主體;現有的 Volcengine 客戶端可以使用本頁面的操作,而無需調整請求格式。請參閱 Seedance 素材與真人驗證 以了解完整的資產生命週期。
curl -X POST "https://example.com/api/v3" \ -H "Content-Type: application/json" \ -d '{ "CallbackURL": "http://example.com" }'{ "id": "string"}授權
BearerAuth API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。
位置: header
查詢參數
可選值
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"請求標頭
單次請求傳遞策略。會覆寫 API key 與 Workspace 的預設值。系統會自動優先嘗試 TokenLab Verified,並可能在輸出、請求接受或建立持久性資源前切換至 Official 模式一次。
可選值
- "auto"
- "verified"
- "official"
請求主體
application/json
回應
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json