Video & materi
Material Actions (Kompatibel dengan Volc)
Referensi untuk 10 Action material dan material-group yang kompatibel dengan Volcengine.
Endpoint ini mendukung Action dan field material yang tercantum di bawah ini, menggunakan autentikasi TokenLab Bearer dan envelope ResponseMetadata + Result.
Endpoint Dan Autentikasi
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 juga didukung. Semua Action material hanya mendukung POST. Tanda tangan AK/SK Volcengine tidak diterima; permintaan tanpa kunci TokenLab Bearer yang valid akan mengembalikan 401 InvalidCredential.
ProjectName secara default bernilai default dan merupakan batas isolasi nyata di dalam organisasi yang terautentikasi. Gunakan nilai yang sama saat membuat, mencantumkan, membaca, memperbarui, atau menghapus grup dan aset terkait.
Action Material-Group
| Action | Tujuan | Request body |
|---|---|---|
CreateAssetGroup | Membuat grup material avatar virtual | Name; opsional Description; opsional GroupType: "AIGC"; ProjectName |
ListAssetGroups | Mencantumkan grup dalam satu proyek | Opsional Filter.GroupIds, Filter.GroupType, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAssetGroup | Membaca satu grup | Id, ProjectName |
UpdateAssetGroup | Mengubah nama atau deskripsi grup | Id; Name dan/atau Description; ProjectName |
DeleteAssetGroup | Menghapus grup dan asetnya | Id, ProjectName |
CreateAssetGroup hanya menerima GroupType: "AIGC". Grup LivenessFace dibuat melalui verifikasi orang asli yang berhasil, bukan oleh Action ini. ListAssetGroups dapat memfilter grup AIGC maupun LivenessFace. Name terdiri dari 1–64 karakter dan Description maksimal 300 karakter, yang lebih pendek dari batas endpoint REST /v1/videos/assets*.
Membuat Grup
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 Material-Asset
| Action | Tujuan | Request body |
|---|---|---|
CreateAsset | Mengimpor satu URL gambar, video, atau audio publik | GroupId, URL, Name, AssetType, ProjectName |
ListAssets | Mencantumkan aset dalam satu proyek | Opsional Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName |
GetAsset | Membaca satu aset dan URL sementaranya | Id, ProjectName |
UpdateAsset | Mengubah nama aset | Id; opsional Name; ProjectName |
DeleteAsset | Menghapus satu aset | Id, ProjectName |
AssetType menerima Image, Video, atau Audio. Grup target menentukan apakah aset tersebut merupakan material AIGC biasa atau material LivenessFace yang terverifikasi.
Membuat Aset
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"
}'Gunakan ID material TokenLab. CreateAsset mengembalikan Result.Id sebelum pemrosesan selesai; lakukan polling GetAsset hingga Result.Status menjadi Active atau Failed. ListAssets juga menerima SortBy: "GroupId".
Perilaku List
PageNumber secara default bernilai 1; PageSize secara default bernilai 10 dan menerima hingga 100. SortBy menerima CreateTime atau UpdateTime; SortOrder menerima Desc atau Asc.
Respons list mengembalikan:
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "ListAssets",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing"
},
"Result": {
"Items": [],
"TotalCount": 0,
"PageNumber": 1,
"PageSize": 10
}
}Nilai status aset adalah Active, Processing, dan Failed. GetAsset dan ListAssets mengembalikan URL sementara yang berlaku selama 12 jam; jangan simpan URL tersebut sebagai identitas aset permanen. Simpanlah Id sebagai gantinya.
Hasil
| Action | Result (field utama) |
|---|---|
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset | { "Id": "..." } |
DeleteAssetGroup, DeleteAsset | {} |
GetAssetGroup | Id, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime |
GetAsset | Id, GroupId, Name, AssetType, URL, Status, Error (Code dan Message, kosong kecuali aset gagal), ProjectName, CreateTime, UpdateTime |
Waktu menggunakan string ISO 8601. ListAssetGroups dan ListAssets mengembalikan objek-objek ini di dalam Result.Items.
Material Orang Asli (Real-Person)
Sebelum mengimpor aset untuk orang asli:
- Panggil Membuat Sesi Validasi Visual.
- Selesaikan alur verifikasi H5.
- Panggil Mendapatkan Hasil Validasi Visual hingga mengembalikan
Result.GroupId. - Panggil
CreateAssetdengan ID grup yang telah terverifikasi tersebut.
Unggahan ke grup LivenessFace diperiksa terhadap wajah yang terverifikasi. DeleteAssetGroup tidak menghapus grup orang asli yang terverifikasi; tindakan ini akan mengembalikan 409 OperationDenied.
Error
Error tetap menggunakan envelope respons Volcengine dan menempatkan kode serta pesan di bawah ResponseMetadata.Error.
{
"ResponseMetadata": {
"RequestId": "req-id",
"Action": "CreateAsset",
"Version": "2024-01-01",
"Service": "ark",
"Region": "cn-beijing",
"Error": {
"Code": "InvalidParameter",
"Message": "GroupId is required"
}
}
}Kode umum meliputi InvalidCredential, InvalidVersion, InvalidParameter, ResourceNotFound, Conflict, OperationDenied, MethodNotAllowed, AccessDenied, FlowLimitExceeded, dan InternalError. Status HTTP adalah 400 untuk permintaan yang salah, 404 untuk grup atau aset yang tidak ditemukan, 409 untuk konflik, dan 405 untuk metode non-POST.
Alternatif REST
Endpoint REST /v1/videos/assets* milik TokenLab tetap tersedia. Integrasi asli TokenLab yang baru mungkin lebih menyukai body snake_case; klien Volcengine yang sudah ada dapat menggunakan Action di halaman ini tanpa perlu mengubah format permintaan. Lihat Material Seedance dan verifikasi orang asli untuk siklus hidup aset yang lengkap.
curl -X POST "https://example.com/api/v3" \ -H "Content-Type: application/json" \ -d '{ "CallbackURL": "http://example.com" }'{ "id": "string"}Otorisasi
BearerAuth Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.
Lokasi: header
Parameter query
Nilai yang tersedia
- "CreateContentsGenerationsTasks"
- "GetContentsGenerationsTask"
- "ListContentsGenerationsTasks"
- "DeleteContentsGenerationsTasks"
- "CreateVisualValidateSession"
- "GetVisualValidateResult"
- "CreateAssetGroup"
- "ListAssetGroups"
- "GetAssetGroup"
- "UpdateAssetGroup"
- "DeleteAssetGroup"
- "CreateAsset"
- "ListAssets"
- "GetAsset"
- "UpdateAsset"
- "DeleteAsset"
"2024-01-01"Header
Kebijakan Pengiriman per-permintaan. Menggantikan default API key dan Workspace. Secara otomatis mencoba TokenLab Verified terlebih dahulu dan dapat beralih satu kali ke Official saja sebelum output, penerimaan permintaan, atau pembuatan sumber daya persisten.
Nilai yang tersedia
- "auto"
- "verified"
- "official"
Body permintaan
application/json
Respons
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json