TokenLab
取得 API Key
文件API 參考整合

視頻與素材

素材 Action（火山相容）

10 個火山相容素材與素材群組 Action 的介面參考。

POST
/api/v3

這些介面支援下列素材 Action 和欄位，使用 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。所有素材 Action 僅接受 POST。只有 AK/SK 簽名的請求會回傳 401 InvalidCredential。

ProjectName 預設為 default，並在目前組織內形成真正的隔離邊界。相關建立、列表、讀取、更新和刪除請求必須使用相同值。

素材群組 Action

Action目標JSON
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 只能建立 AIGC 群組。LivenessFace 群組必須在真人驗證成功後建立；ListAssetGroups 可篩選兩種群組。

建立素材群組

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"}
}

素材 Action

Action目標JSON
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。

請使用 TokenLab 素材 ID。CreateAsset 在處理完成前回傳 Result.Id；輪詢 GetAsset，直到 Result.Status 為 Active 或 Failed。ListAssets 也支援 SortBy: "GroupId"。

建立素材

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"}'

列表行為

PageNumber 預設為 1，PageSize 預設為 10 且最大為 100。SortBy 支援 CreateTime 或 UpdateTime；SortOrder 支援 Desc 或 Asc。

素材狀態為 Active、Processing 或 Failed。GetAsset 和 ListAssets 回傳有效 12 小時的暫時 URL；請儲存 Id，不要把 URL 當作永久識別。

ListAssetGroups 和 ListAssets 透過 Result.Items 回傳資源，並同時回傳 TotalCount、PageNumber 和 PageSize。

{
  "ResponseMetadata": {
    "RequestId": "req-id",
    "Action": "ListAssets",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {"Items":[],"TotalCount":0,"PageNumber":1,"PageSize":10}
}

真人素材

先建立視覺驗證工作階段並完成 H5 驗證，再取得驗證結果回傳的 GroupId，最後以該群組呼叫 CreateAsset。上傳內容會與已驗證人臉比對。

  1. 建立視覺驗證工作階段
  2. 取得視覺驗證結果
  3. 使用回傳的 GroupId 呼叫 CreateAsset

錯誤

錯誤沿用火山回應信封，錯誤碼與訊息位於 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, NotFound, Conflict, OperationDenied, MethodNotAllowed, InternalError.

REST 替代介面

TokenLab 的 /v1/videos/assets* REST 介面仍然可用。新整合可選擇 snake_case REST；既有火山用戶端無須改造請求內容。 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

取得視覺驗證結果

上一頁

建立素材資產群組

下一頁