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.
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/jsonPOST /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
| Action | Mục đích | Body yêu cầu |
|---|---|---|
CreateAssetGroup | Tạo một nhóm material cho avatar ảo | Name; Description (tùy chọn); GroupType: "AIGC" (tùy chọn); ProjectName |
ListAssetGroups | Liệt kê các nhóm trong một dự án | Filter.GroupIds, Filter.GroupType, Filter.Name (tùy chọn); PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAssetGroup | Đọc một nhóm | Id, ProjectName |
UpdateAssetGroup | Thay đổi tên hoặc mô tả nhóm | Id; Name và/hoặc Description; ProjectName |
DeleteAssetGroup | Xó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
| Action | Mục đích | Body yêu cầu |
|---|---|---|
CreateAsset | Nhập một URL hình ảnh, video hoặc âm thanh công khai | GroupId, URL, Name, AssetType, ProjectName |
ListAssets | Liệt kê các tài nguyên trong một dự án | Filter.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ên | Id; Name (tùy chọn); ProjectName |
DeleteAsset | Xóa một tài nguyên | Id, 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ả
| Action | Result (các trường chính) |
|---|---|
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset | { "Id": "..." } |
DeleteAssetGroup, DeleteAsset | {} |
GetAssetGroup | Id, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime |
GetAsset | Id, 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:
- Gọi Tạo Phiên Xác thực Trực quan.
- Hoàn thành quy trình xác minh H5.
- Gọi Lấy Kết quả Xác thực Trực quan cho đến khi nó trả về
Result.GroupId. - Gọi
CreateAssetvớ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 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
Giá trị hợp lệ
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"Header
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