TokenLab

視頻與素材

素材操作 (Volc 相容)

10 個 Volcengine 相容素材與素材群組操作的參考指南。

POST
/api/v3

這些端點支援下方列出的素材操作與欄位,並使用 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匯入公開的圖片、影片或音訊 URLGroupId, URL, Name, AssetType, ProjectName
ListAssets列出專案中的資產選填 Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name;PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAsset讀取單一資產及其暫時 URLId, 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{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code 與 Message,除非資產失敗否則為空), ProjectName, CreateTime, UpdateTime

時間為 ISO 8601 字串。ListAssetGroups 與 ListAssets 會在 Result.Items 中回傳這些物件。

真人素材 (Real-Person Materials)

在匯入真人素材前:

  1. 呼叫 建立視覺驗證工作階段。
  2. 完成 H5 驗證流程。
  3. 呼叫 取得視覺驗證結果 直到其回傳 Result.GroupId。
  4. 使用該已驗證的群組 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
AuthorizationBearer <token>

API Key 驗證。請在 Dashboard > API > API Keys 建立或管理 API 金鑰。

位置: header

查詢參數

Action?string

可選值

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
預設值"2024-01-01"

請求標頭

X-TokenLab-Delivery-Policy?string

單次請求傳遞策略。會覆寫 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