Material Actions (Volc Compatible)

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

Endpoint And AuthenticationCopy Anchor Link

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 ActionsCopy Anchor Link

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.

Create A GroupCopy Anchor Link

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 ActionsCopy Anchor Link

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 AssetCopy Anchor Link

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 BehaviorCopy Anchor Link

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.

Real-Person MaterialsCopy Anchor Link

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. Active verified groups can also have stricter deletion rules than ordinary AIGC groups.

ErrorsCopy Anchor Link

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, NotFound, Conflict, OperationDenied, MethodNotAllowed, and InternalError.

REST AlternativeCopy Anchor Link

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