TokenLab

Video & tư liệu

Material Actions (Tương thích Volc)

Tài liệu tham khảo cho 10 Action về material và material-group tương thích với Volcengine.

POST
/api/v3

Các endpoint này hỗ trợ các Action và trường dữ liệu material được liệt kê dưới đây, sử dụng xác thực TokenLab Bearer và cấu trúc bao ResponseMetadata + Result.

Endpoint Và Xác Thực

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 cũng được hỗ trợ. Tất cả các Action về material chỉ hỗ trợ phương thức POST. Chữ ký Volcengine AK/SK không được chấp nhận; yêu cầu không có khóa TokenLab Bearer hợp lệ sẽ trả về 401 InvalidCredential.

ProjectName mặc định là default và là ranh giới cô lập thực tế bên trong tổ chức đã xác thực. Hãy sử dụng cùng một giá trị khi tạo, liệt kê, đọc, cập nhật hoặc xóa các nhóm và tài nguyên liên quan.

Các Action Cho Material-Group

ActionMục đíchBody yêu cầu
CreateAssetGroupTạo một nhóm material cho avatar ảoName; Description (tùy chọn); GroupType: "AIGC" (tùy chọn); ProjectName
ListAssetGroupsLiệt kê các nhóm trong một dự ánFilter.GroupIds, Filter.GroupType, Filter.Name (tùy chọn); PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroupĐọc một nhómId, ProjectName
UpdateAssetGroupThay đổi tên hoặc mô tả nhómId; Name và/hoặc Description; ProjectName
DeleteAssetGroupXóa một nhóm và các tài nguyên của nóId, ProjectName

CreateAssetGroup chỉ chấp nhận GroupType: "AIGC". Một nhóm LivenessFace được tạo thông qua xác minh người thật thành công, không phải bởi Action này. ListAssetGroups có thể lọc cả nhóm AIGC và LivenessFace. Name có độ dài 1–64 ký tự và Description tối đa 300 ký tự, ngắn hơn giới hạn của các endpoint REST /v1/videos/assets*.

Tạo Một Nhóm

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

Các Action Cho Material-Asset

ActionMục đíchBody yêu cầu
CreateAssetNhập một URL hình ảnh, video hoặc âm thanh công khaiGroupId, URL, Name, AssetType, ProjectName
ListAssetsLiệt kê các tài nguyên trong một dự ánFilter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name (tùy chọn); PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetĐọc một tài nguyên và URL tạm thời của nóId, ProjectName
UpdateAssetĐổi tên một tài nguyênId; Name (tùy chọn); ProjectName
DeleteAssetXóa một tài nguyênId, ProjectName

AssetType chấp nhận Image, Video hoặc Audio. Nhóm đích xác định liệu tài nguyên đó là material AIGC thông thường hay material LivenessFace đã được xác minh.

Tạo Một Tài Nguyên

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

Sử dụng các ID material của TokenLab. CreateAsset trả về Result.Id trước khi quá trình xử lý hoàn tất; hãy gọi GetAsset cho đến khi Result.Status là Active hoặc Failed. ListAssets cũng chấp nhận SortBy: "GroupId".

Hành Vi Liệt Kê

PageNumber mặc định là 1; PageSize mặc định là 10 và chấp nhận tối đa 100. SortBy chấp nhận CreateTime hoặc UpdateTime; SortOrder chấp nhận Desc hoặc Asc.

Các phản hồi liệt kê trả về:

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

Các giá trị trạng thái tài nguyên là Active, Processing và Failed. GetAsset và ListAssets trả về một URL tạm thời có hiệu lực trong 12 giờ; không lưu trữ nó làm định danh tài nguyên vĩnh viễn. Thay vào đó, hãy lưu trữ Id.

Kết Quả

ActionResult (các trường chính)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, GroupId, Name, AssetType, URL, Status, Error (Code và Message, trống trừ khi tài nguyên thất bại), ProjectName, CreateTime, UpdateTime

Thời gian là các chuỗi ISO 8601. ListAssetGroups và ListAssets trả về các đối tượng này trong Result.Items.

Material Người Thật

Trước khi nhập tài nguyên cho người thật:

  1. Gọi Tạo Phiên Xác thực Trực quan.
  2. Hoàn thành quy trình xác minh H5.
  3. Gọi Lấy Kết quả Xác thực Trực quan cho đến khi nó trả về Result.GroupId.
  4. Gọi CreateAsset với ID nhóm đã xác minh đó.

Các tệp tải lên nhóm LivenessFace được kiểm tra đối chiếu với khuôn mặt đã xác minh. DeleteAssetGroup không xóa nhóm người thật đã xác minh; nó sẽ trả về 409 OperationDenied.

Lỗi

Các lỗi giữ nguyên cấu trúc bao phản hồi của Volcengine và đặt mã lỗi cùng thông báo bên dưới ResponseMetadata.Error.

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

Các mã lỗi phổ biến bao gồm InvalidCredential, InvalidVersion, InvalidParameter, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded và InternalError. Trạng thái HTTP là 400 cho yêu cầu không hợp lệ, 404 cho nhóm hoặc tài nguyên bị thiếu, 409 cho xung đột và 405 cho phương thức không phải POST.

Giải Pháp Thay Thế REST

Các endpoint REST /v1/videos/assets* của TokenLab vẫn khả dụng. Các tích hợp gốc của TokenLab có thể ưu tiên các body dạng snake_case; các client Volcengine hiện tại có thể sử dụng các Action trên trang này mà không cần thay đổi cấu trúc yêu cầu. Xem Material Seedance và xác minh người thật để biết vòng đời đầy đủ của tài nguyên.

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

Xác thực

BearerAuth
AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Tham số truy vấn

Action?string

Giá trị hợp lệ

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
mặc định"2024-01-01"

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

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

Nội dung yêu cầu

application/json

Phản hồi

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json