Panduan media
Materi Seedance dan Verifikasi Orang Asli
Gunakan kembali gambar, video, audio, atau orang yang telah diverifikasi di Seedance
Materi Seedance memungkinkan Anda menggunakan kembali file gambar, video, atau audio tanpa harus mengimpornya setiap kali melakukan generasi. Referensi ke orang asli memerlukan persetujuan dan verifikasi visual; sedangkan untuk orang virtual, produk, dan gaya tidak memerlukannya.
Pilih jenis materi
| Apa yang ingin Anda gunakan kembali | Apa yang harus dilakukan |
|---|---|
| Satu gambar yang digunakan sekali | Kirim URL-nya di kolom gambar yang didukung; ini tidak membuat ID materi yang dapat digunakan kembali |
| Menggunakan kembali orang virtual, produk, atau gaya | Buat grup aigc_avatar, buat aset, tunggu hingga statusnya ACTIVE, lalu gunakan ID aset tersebut |
| Menggunakan kembali orang asli | Selesaikan validasi visual, terima GroupId-nya, buat aset di grup tersebut, tunggu hingga ACTIVE, lalu gunakan ID aset tersebut |
| Migrasi klien materi Volcengine yang ada | Pertahankan bentuk permintaan Action dan gunakan referensi materi yang kompatibel dengan Volc |
Grup dan materi
| Item | Kolom REST | Kolom Action | Apa artinya |
|---|---|---|---|
| Grup materi | group_id | GroupId | Mengelompokkan materi yang saling terkait |
| Materi | id | Id | Satu file gambar, video, atau audio yang diimpor; gunakan ID ini setelah statusnya aktif |
| Grup avatar virtual | library_type: "aigc_avatar" | GroupType: "AIGC" | Tidak memerlukan verifikasi orang asli |
| Grup orang asli | library_type: "liveness_face" | GroupType: "LivenessFace" | Hanya dibuat melalui alur validasi visual yang berhasil |
| Nama proyek | project_name | ProjectName | Memisahkan materi dari proyek yang berbeda; default-nya adalah default |
Pisahkan ID grup dan ID aset. Grup berfungsi untuk mengatur unggahan; ID aset adalah referensi yang digunakan oleh pembuatan video. ID publik terlihat seperti group-20260720123456-vrt01 dan asset-20260720123457-def45.
Retensi Materi
TokenLab menyimpan setiap aset materi sampai Anda menghapus aset atau grupnya. Materi tidak akan dihapus karena tidak aktif.
- Jika aset perlu disiapkan kembali saat Anda menggunakannya, generasi pertama mungkin memakan waktu sedikit lebih lama. Jika belum siap, permintaan akan mengembalikan
409 seedance_material_preparing; coba lagi dalam waktu singkat. - Menghapus aset atau grup bersifat permanen dan tidak dapat dibatalkan.
URL Gambar dan materi yang dapat digunakan kembali
Kirim URL HTTP(S) publik atau URL data yang didukung di kolom gambar yang diterima oleh model pilihan Anda. Input ini mengikuti jalur media normal dan tidak secara otomatis membuat ID materi yang dapat digunakan kembali.
Untuk materi yang dapat digunakan kembali, buat aset melalui API materi, tunggu hingga ACTIVE, lalu gunakan material_asset_id, material_asset_ids, atau asset://<id> di kolom media yang didukung. Pertahankan peran first-frame, last-frame, atau reference-image yang diinginkan.
Ketika materi eksplisit masih dalam persiapan, POST /v1/videos/generations akan mengembalikan 409 seedance_material_preparing dengan inactive_asset_ids. Lakukan polling pada aset tersebut hingga statusnya ACTIVE, lalu coba lagi dengan ID materi yang sama. Jika aset berstatus FAILED, periksa error_message dan perbaiki atau impor ulang sebelum mencoba lagi. Permintaan generasi yang menggunakan aset yang gagal akan mengembalikan 422 seedance_material_failed dengan failed_asset_ids.
Materi Avatar Virtual
Gunakan Membuat Grup Aset Material untuk membuat grup aigc_avatar. Untuk pembuatan aset REST, group_id bersifat opsional hanya jika project_name adalah default; TokenLab kemudian akan menggunakan atau membuat grup avatar virtual default organisasi. project_name non-default, dan setiap aset orang asli, memerlukan group_id.
Setelah grup ada, kelola dengan:
- Mencantumkan Grup Aset Material
- Mendapatkan Grup Aset Material
- Memperbarui Grup Aset Material
- Menghapus Grup Aset Material
Menghapus grup juga akan menghapus materi TokenLab yang ada di dalamnya dan tidak dapat dibatalkan.
Verifikasi Orang Asli
Gunakan alur ini ketika produk Anda harus mengumpulkan persetujuan dan memverifikasi wajah sebelum menggunakan kembali orang asli sebagai referensi Seedance.
- Panggil Membuat Sesi Validasi Visual dengan
CallbackURL; simpanResult.BytedTokendan bukaResult.H5Linkuntuk orang yang diverifikasi. - Setelah alur H5 mengalihkan ke callback, lakukan polling pada Mendapatkan Hasil Validasi Visual dengan
BytedTokendanProjectNameyang sama. - Simpan
Result.GroupIdyang dikembalikan. TokenLab membuat dan mengikat grupLivenessFaceselama langkah ini. - Buat aset dengan ID grup tersebut, lalu lakukan polling pada aset hingga statusnya menjadi
ACTIVE.
BytedToken berlaku selama 30 menit. Klien tidak dapat membuat grup LivenessFace dengan CreateAssetGroup; ini mencegah grup yang belum diverifikasi disajikan sebagai grup yang terverifikasi.
Buka H5Link yang dikembalikan segera setelah pembuatan. Validitas token tidak berarti halaman verifikasi dapat dibuka untuk pertama kalinya kapan saja dalam jendela waktu tersebut.
Untuk grup orang asli, unggahan diperiksa terhadap wajah yang terverifikasi. Aset bisa gagal jika berisi banyak wajah atau wajah tidak cocok. Untuk hasil terbaik, unggah referensi depan seluruh tubuh dan foto jarak dekat yang menghadap ke depan dengan jelas.
Membuat Dan Menyiapkan Aset
Gunakan Membuat Material Asset untuk mengimpor satu URL yang dapat diakses publik dalam satu waktu.
| Jenis | Input yang didukung |
|---|---|
| Gambar | jpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; lebar dan tinggi [300, 6000] px; rasio aspek [0.4, 2.5] |
| Video | mp4, mov; ≤ 200 MiB |
| Audio | aac, wav, mp3; ≤ 15 MiB |
Ini adalah batas impor file. Permintaan impor yang berhasil tidak menjamin bahwa validasi media atau orang asli akan lulus. Tunggu hingga ACTIVE; jika aset menjadi FAILED, gunakan error_message untuk memperbaiki sumber sebelum mengimpor lagi.
Penyerapan materi bersifat asinkron. Lakukan polling pada Mendapatkan Aset Material hingga status menjadi ACTIVE. Keberhasilan HTTP berarti impor diterima, bukan berarti aset sudah siap. Jika aset menjadi FAILED, periksa error_message, perbaiki sumbernya, dan buat aset baru.
URL sumber hanya digunakan untuk impor. TokenLab mengembalikan ID asetnya sendiri dan menyimpan aset di pustaka materi organisasi Anda sampai Anda menghapus aset atau grupnya.
Menggunakan Aset Dalam Pembuatan Video
Setelah aset berstatus ACTIVE, pilih salah satu bentuk ini saat memanggil Create Video:
material_asset_iduntuk satu referensi materi generikmaterial_asset_idsuntuk beberapa referensi generikasset://<asset-id>diimage_url,start_image,end_image, ataureference_imagesketika peran media harus eksplisit
Referensi materi dihitung terhadap batas referensi Seedance model yang dipilih. Jika API mengembalikan Seedance material asset not found or not accessible, pastikan nilainya adalah ID aset dan bukan ID grup, milik organisasi dan proyek yang sama, tidak dihapus, dan berstatus ACTIVE.
REST Atau Volcengine Action
Integrasi asli TokenLab dapat terus menggunakan endpoint REST /v1/videos/assets* dengan format snake_case. Klien Volcengine yang ada dapat mempertahankan body PascalCase dengan Material Actions (Kompatibel dengan Volc). Kedua antarmuka beroperasi pada data materi yang sama yang dicakup oleh organisasi dan proyek.
Contoh REST: Aset Avatar Virtual
curl https://api.tokenlab.sh/v1/videos/assets/groups \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"library_type":"aigc_avatar","group_name":"Product references","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
-H "Authorization: Bearer $TOKENLAB_API_KEY"Contoh Action: Aset Orang Asli Terverifikasi
Pertama, buat dan selesaikan validasi visual:
curl 'https://api.tokenlab.sh/?Action=CreateVisualValidateSession&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'
curl 'https://api.tokenlab.sh/?Action=GetVisualValidateResult&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'Kemudian teruskan GroupId yang dikembalikan ke CreateAsset:
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-real1",
"URL":"https://example.com/person-front.png",
"Name":"Verified front view",
"AssetType":"Image",
"ProjectName":"default"
}'Lakukan polling dengan GetAsset hingga statusnya Active, lalu teruskan ID aset yang dikembalikan ke pembuatan video. Untuk semua 10 operasi Action, filter, penomoran halaman, bentuk respons, dan kesalahan, lihat Material Actions (Kompatibel dengan Volc).