Model video berbasis referensi Vidu menggunakan gambar referensi dan prompt teks. Model menggabungkan subjek dari gambar ke dalam adegan yang dijelaskan prompt untuk menghasilkan video yang mulus.
Catatan penggunaan
Agar panggilan API berhasil, gunakan model, URL endpoint, dan API key dari wilayah yang sama. Panggilan lintas wilayah akan gagal.
- Pilih model: Pastikan wilayah tempat model Anda berada.
- Pilih URL: Pilih URL endpoint yang sesuai. URL HTTP maupun DashScope SDK didukung.
- Konfigurasikan API key: Pilih wilayah, dapatkan API key, lalu konfigurasikan API key sebagai variabel lingkungan.
Contoh kode dalam topik ini berlaku untuk wilayah Singapura.
Panggilan HTTP
Karena tugas video berbasis referensi biasanya memerlukan 1 hingga 5 menit, API menggunakan panggilan asinkron. Prosesnya terdiri dari dua langkah utama: "Buat tugas -> Lakukan polling hasil".
Langkah 1: Buat tugas
Wilayah Singapura: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
- Setelah tugas dibuat, gunakan
task_idyang dikembalikan untuk mengueri hasil.task_idberlaku selama 24 jam. Jangan membuat tugas duplikat. Gunakan polling untuk mengambil hasilnya. - Untuk panduan pemula, lihat Memanggil API dengan Postman atau cURL.
Parameter permintaanHeader permintaanContent-Typestring (Wajib)Jenis konten permintaan. Harus application/json.Authorization string (Wajib)Mengautentikasi permintaan dengan API key Model Studio. Contoh: Bearer sk-xxxx.X-DashScope-Async string (Wajib)Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus enable.Isi permintaanmodelstring (wajib)Model yang digunakan. Nilai yang valid:
Panduan pemilihan model
object (wajib)Input dasar yang mencakup gambar referensi dan prompt.
Properti prompt string (wajib)Prompt teks yang menjelaskan elemen dan karakteristik visual yang diinginkan dalam video.Bahasa Mandarin dan Inggris didukung. Panjang maksimum adalah 5.000 karakter. Teks yang melebihi batas otomatis dipotong.Contoh: Seorang pria duduk di kursi dekat jendela sebuah kafe, memegang gitar dan memainkan lagu folk country Amerika yang menenangkan.media array (wajib)Daftar aset media yang menentukan materi referensi untuk pembuatan video.Setiap elemen array adalah objek media yang berisi field type dan url.
Properti elemen type string (wajib)Jenis aset media. Nilai yang valid bergantung pada model yang dipilih.
Sediakan hanya gambar referensi Model yang didukung: vidu/viduq3-ad_reference2video, vidu/viduq3-drama_reference2video, vidu/viduq3-mix_reference2videoNilainya tetap sebagai berikut:
string (wajib)URL aset media.
Sediakan gambar (type=image) URL gambar referensi. URL harus dapat diakses publik.
object (wajib)Parameter pembuatan video, seperti resolusi dan durasi video.
Properti resolution string (opsional)Resolusi video yang dihasilkan. Nilai yang valid bergantung pada model yang dipilih:
string (opsional)Resolusi video yang dihasilkan, dalam piksel, dengan format width*height.Nilai default bergantung pada resolution:
integer (wajib)Durasi video yang dihasilkan, dalam detik.
boolean (opsional)Model yang didukung: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video.Menentukan apakah video dengan audio dihasilkan. Jika diaktifkan, model otomatis menghasilkan musik latar atau efek suara yang sesuai dengan konten video.
vidu/viduq3-drama_reference2video tidak mendukung parameter ini. Secara default, model ini menghasilkan video dengan audio. boolean (opsional)Menentukan apakah watermark ditambahkan di sudut kanan bawah video. Teks watermark ditetapkan sebagai "Content generated by AI".
integer(opsional)Seed. Rentang nilainya adalah [0, 2147483647].Jika seed tidak ditentukan, sistem membuatnya secara acak. Untuk meningkatkan reproduktibilitas hasil, sebaiknya tetapkan nilai seed tetap.Karena sifat probabilistik model, penggunaan seed yang sama tidak menjamin hasil identik pada setiap eksekusi.Contoh: 12345 |
Model yang didukung: vidu/viduq3-ad_reference2video. |
Parameter respons |
Simpan task_id untuk mengueri status dan hasil tugas. |
output objectData output tugas.
Properti task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.
Nilai enumerasi
| |
request_id stringPengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah. | |
message stringPesan kesalahan terperinci. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. |
Langkah 2: Kueri hasil tugas
Wilayah Singapura: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
- Rekomendasi polling: Pembuatan video dapat memerlukan beberapa menit. Sebaiknya gunakan mekanisme polling dengan interval kueri yang wajar (misalnya 15 detik) untuk mengambil hasil.
- Transisi status tugas: PENDING (dalam antrean) → RUNNING (diproses) → SUCCEEDED (berhasil) / FAILED (gagal).
- Masa berlaku task_id: 24 jam. Setelah masa berlaku berakhir, hasil tidak dapat dikueri lagi dan API mengembalikan status tugas
UNKNOWN. - Batas RPS: API kueri memiliki batas RPS default 20. Untuk kueri lebih sering atau notifikasi peristiwa, sebaiknya konfigurasikan callback tugas asinkron.
- Operasi lainnya: Untuk operasi seperti kueri tugas batch atau pembatalan tugas, lihat Mengelola tugas asinkron.
Parameter permintaanHeader permintaanAuthorizationstring (Wajib)Mengautentikasi permintaan dengan API key Model Studio. Contoh: Bearer sk-xxxx.Parameter jalurtask_idstring (Wajib)ID tugas. |
Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam |
Parameter responsoutputobjectData output tugas.
Properti task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.
Nilai enumerasi
stringWaktu tugas dikirim. Format: YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu tugas dijalankan. Format: YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu tugas selesai. Format: YYYY-MM-DD HH:mm:ss.SSS.video_urlstringURL video. Parameter ini hanya dikembalikan saat task_status adalah SUCCEEDED.Video berformat MP4 (pengodean H.264). URL video berlaku selama 24 jam. Segera unduh video.orig_prompt stringPrompt input asli, sesuai parameter permintaan prompt.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan terperinci. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.objectStatistik penggunaan (hanya dihitung untuk tugas yang berhasil).
Properti duration integerTotal durasi video yang dihasilkan, digunakan untuk penagihan.size stringMenentukan resolusi video yang dihasilkan.fps integerMenentukan frame rate video yang dihasilkan. Nilainya tetap 24.SR stringMenentukan tingkat resolusi video yang dihasilkan.audio booleanMenunjukkan apakah video yang dihasilkan menyertakan audio.video_count integerMenentukan jumlah video yang dihasilkan. Nilainya tetap 1.reference_type stringMenentukan jenis materi referensi yang digunakan.stringPengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah. |
URL video hanya berlaku 24 jam lalu otomatis dihapus. Segera simpan video yang dihasilkan. |
Kode kesalahan
Jika panggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk solusinya.
FAQ
T: Apakah size dan resolution harus diberikan bersamaan?
J: Tidak. Keduanya opsional, tetapi kami menyarankan untuk memberikan keduanya agar rasio aspek video dapat dikontrol secara presisi. Lihat Nilai size yang valid.
Jika keduanya tidak diberikan, sistem menangani permintaan sebagai berikut:
-
Hanya size yang diberikan: Parameter
sizediabaikan, dan sistem menggunakanresolution=720Pdefault serta nilaisizedefault yang sesuai (1280*720).Contoh: API mengembalikan
size="1280*720"danSR=720. -
Jika hanya
resolutionyang diberikan: Output menggunakan tingkat resolusi yang ditentukan.Misalnya, jika
resolution=540P, API mengembalikansize="960*528"danSR=540. Jikaresolution=1080P, API mengembalikansize="1920*1080"danSR=1080.