Video & materi

Material Actions (Kompatibel dengan Volc)

Referensi untuk 10 Action material dan material-group yang kompatibel dengan Volcengine.

POST
/api/v3

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/json

POST /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

ActionTujuanRequest body
CreateAssetGroupMembuat grup material avatar virtualName; opsional Description; opsional GroupType: "AIGC"; ProjectName
ListAssetGroupsMencantumkan grup dalam satu proyekOpsional Filter.GroupIds, Filter.GroupType, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetGroupMembaca satu grupId, ProjectName
UpdateAssetGroupMengubah nama atau deskripsi grupId; Name dan/atau Description; ProjectName
DeleteAssetGroupMenghapus grup dan asetnyaId, 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

ActionTujuanRequest body
CreateAssetMengimpor satu URL gambar, video, atau audio publikGroupId, URL, Name, AssetType, ProjectName
ListAssetsMencantumkan aset dalam satu proyekOpsional Filter.GroupIds, Filter.GroupType, Filter.Statuses, Filter.Name; PageNumber, PageSize, SortBy, SortOrder, ProjectName
GetAssetMembaca satu aset dan URL sementaranyaId, ProjectName
UpdateAssetMengubah nama asetId; opsional Name; ProjectName
DeleteAssetMenghapus satu asetId, 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

ActionResult (field utama)
CreateAssetGroup, CreateAsset, UpdateAssetGroup, UpdateAsset{ "Id": "..." }
DeleteAssetGroup, DeleteAsset{}
GetAssetGroupId, Name, Description, GroupType, ProjectName, CreateTime, UpdateTime
GetAssetId, 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:

  1. Panggil Membuat Sesi Validasi Visual.
  2. Selesaikan alur verifikasi H5.
  3. Panggil Mendapatkan Hasil Validasi Visual hingga mengembalikan Result.GroupId.
  4. Panggil CreateAsset dengan 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
AuthorizationBearer <token>

Autentikasi API Key. Buat atau kelola API key di Dashboard > API > API Keys.

Lokasi: header

Parameter query

Action?string

Nilai yang tersedia

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

Header

X-TokenLab-Delivery-Policy?string

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