TokenLab

Video & Materials

Material Actions (Volc Compatible)

Reference for the 10 Volcengine-compatible material and material-group Actions.

POST
/api/v3

These endpoints support the material Actions and fields listed below, using TokenLab Bearer authentication and the ResponseMetadata + Result envelope.

Endpoint And Authentication

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 is also supported. All material Actions are POST-only. Volcengine AK/SK signatures are not accepted; a request with no valid TokenLab Bearer key returns 401 InvalidCredential.

ProjectName defaults to default and is a real isolation boundary inside the authenticated organization. Use the same value when creating, listing, reading, updating, or deleting related groups and assets.

Material-Group Actions

ActionPurposeRequest body
CreateAssetGroupCreate a virtual-avatar material groupName; optional Description; optional GroupType: "AIGC"; ProjectName
ListAssetGroupsList groups in one projectOptional Filter.GroupIds, Filter.GroupType, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroupRead one groupId, ProjectName
UpdateAssetGroupChange group name or descriptionId; Name and/or Description; ProjectName
DeleteAssetGroupDelete a group and its assetsId, ProjectName

CreateAssetGroup accepts only GroupType: "AIGC". A LivenessFace group is created by successful real-person verification, not by this Action. ListAssetGroups can filter both AIGC and LivenessFace groups. Name is 1–64 characters and Description is up to 300, which is shorter than the limits of the /v1/videos/assets* REST endpoints.

Create A Group

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

ActionPurposeRequest body
CreateAssetImport one public image, video, or audio URLGroupId, URL, Name, AssetType, ProjectName
ListAssetsList assets in one projectOptional Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetRead one asset and its temporary URLId, ProjectName
UpdateAssetRename an assetId; optional Name; ProjectName
DeleteAssetDelete one assetId, ProjectName

AssetType accepts Image, Video, or Audio. The target group determines whether the asset is a normal AIGC material or a verified LivenessFace material.

Create An Asset

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

Use TokenLab material IDs. CreateAsset returns Result.Id before processing finishes; poll GetAsset until Result.Status is Active or Failed. ListAssets also accepts SortBy: "GroupId".

List Behavior

PageNumber defaults to 1; PageSize defaults to 10 and accepts up to 100. SortBy accepts CreateTime or UpdateTime; SortOrder accepts Desc or Asc.

List responses return:

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

Asset status values are Active, Processing, and Failed. GetAsset and ListAssets return a temporary URL valid for 12 hours; do not store it as the permanent asset identity. Store Id instead.

Results

ActionResult (main fields)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code and Message, empty unless the asset failed), ProjectName, CreateTime, UpdateTime

Times are ISO 8601 strings. ListAssetGroups and ListAssets return these objects in Result.Items.

Real-Person Materials

Before importing an asset for a real person:

  1. Call Create Visual Validation Session.
  2. Complete the H5 verification flow.
  3. Call Get Visual Validation Result until it returns Result.GroupId.
  4. Call CreateAsset with that verified group ID.

Uploads to a LivenessFace group are checked against the verified face. DeleteAssetGroup does not delete a verified real-person group; it returns 409 OperationDenied.

Errors

Errors keep the Volcengine response envelope and place the code and message under ResponseMetadata.Error.

{
  "ResponseMetadata": {
    "RequestId": "req-id",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing",
    "Error": {
      "Code": "InvalidParameter",
      "Message": "GroupId is required"
    }
  }
}

Common codes include InvalidCredential, InvalidVersion, InvalidParameter, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded, and InternalError. The HTTP status is 400 for bad requests, 404 for a missing group or asset, 409 for conflicts, and 405 for a non-POST method.

REST Alternative

TokenLab's /v1/videos/assets* REST endpoints remain available. New TokenLab-native integrations may prefer their snake_case bodies; existing Volcengine clients can use the Actions on this page without reshaping requests. See Seedance Materials and Real-Person Verification for the complete asset lifecycle.

curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Query Parameters

Action?string

Value in

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

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

  • "auto"
  • "verified"
  • "official"

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json