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 kembaliApa yang harus dilakukan
Satu gambar yang digunakan sekaliKirim URL-nya di kolom gambar yang didukung; ini tidak membuat ID materi yang dapat digunakan kembali
Menggunakan kembali orang virtual, produk, atau gayaBuat grup aigc_avatar, buat aset, tunggu hingga statusnya ACTIVE, lalu gunakan ID aset tersebut
Menggunakan kembali orang asliSelesaikan validasi visual, terima GroupId-nya, buat aset di grup tersebut, tunggu hingga ACTIVE, lalu gunakan ID aset tersebut
Migrasi klien materi Volcengine yang adaPertahankan bentuk permintaan Action dan gunakan referensi materi yang kompatibel dengan Volc

Grup dan materi

ItemKolom RESTKolom ActionApa artinya
Grup materigroup_idGroupIdMengelompokkan materi yang saling terkait
MateriidIdSatu file gambar, video, atau audio yang diimpor; gunakan ID ini setelah statusnya aktif
Grup avatar virtuallibrary_type: "aigc_avatar"GroupType: "AIGC"Tidak memerlukan verifikasi orang asli
Grup orang aslilibrary_type: "liveness_face"GroupType: "LivenessFace"Hanya dibuat melalui alur validasi visual yang berhasil
Nama proyekproject_nameProjectNameMemisahkan 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:

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.

  1. Panggil Membuat Sesi Validasi Visual dengan CallbackURL; simpan Result.BytedToken dan buka Result.H5Link untuk orang yang diverifikasi.
  2. Setelah alur H5 mengalihkan ke callback, lakukan polling pada Mendapatkan Hasil Validasi Visual dengan BytedToken dan ProjectName yang sama.
  3. Simpan Result.GroupId yang dikembalikan. TokenLab membuat dan mengikat grup LivenessFace selama langkah ini.
  4. 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.

JenisInput yang didukung
Gambarjpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; lebar dan tinggi [300, 6000] px; rasio aspek [0.4, 2.5]
Videomp4, mov; ≤ 200 MiB
Audioaac, 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_id untuk satu referensi materi generik
  • material_asset_ids untuk beberapa referensi generik
  • asset://<asset-id> di image_url, start_image, end_image, atau reference_images ketika 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).

Di halaman ini