Wan - Referensi-ke-Video - Referensi API - Alibaba Cloud Model Studio

Wan-R2V menerima input multimodal (gambar, video, dan audio) untuk menghasilkan video yang menampilkan satu atau beberapa karakter sekaligus mempertahankan penampilan dan suara mereka di berbagai adegan.

Referensi: Panduan pengguna

Ketersediaan

Untuk memastikan panggilan API berhasil, model, URL titik akhir, dan kunci API harus berada di wilayah yang sama. Panggilan lintas wilayah akan gagal.

Pilih model: Konfirmasi wilayah model tersebut.
Pilih URL: Gunakan URL titik akhir yang sesuai dengan wilayah tersebut. Protokol HTTP didukung.
Konfigurasikan kunci API: Pilih wilayah, dapatkan kunci API, dan konfigurasikan kunci API sebagai variabel lingkungan.

Catatan

Kode contoh dalam topik ini berlaku untuk wilayah Singapura.

Penting

Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:

China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapura: dari https://dashscope-intl.aliyuncs.com ke https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan pada halaman Detail Ruang Kerja di Konsol Alibaba Cloud Model Studio. Domain lama tetap berfungsi penuh.

HTTP

Penting

API ini menggunakan protokol baru dan mendukung model wan2.7.

Pembuatan video biasanya memakan waktu 1 hingga 5 menit, sehingga API menggunakan pemanggilan asinkron. Alur kerja terdiri dari dua langkah: membuat tugas, lalu melakukan polling untuk hasilnya.

Langkah 1: Buat tugas dan dapatkan ID tugas

Singapura

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Beijing

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Catatan

Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk mengkueri hasilnya. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.
Untuk panduan pemula, lihat Panggil API dengan Postman atau cURL.

Parameter permintaan	Referensi multi-subjek (gambar + video + suara) Anda dapat mengirimkan beberapa aset referensi (gambar dan video) serta menentukan suara untuk menghasilkan video. curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \ -H 'X-DashScope-Async: enable' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "wan2.7-r2v-2026-06-12", "input": { "prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, '\''The sunshine is so nice today.'\'' Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, '\''That sounds lovely. Can you sing it again?'\''", "media": [ { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg", "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3" }, { "type": "reference_video", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4", "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3" }, { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png" }, { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png" }, { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png" } ] }, "parameters": { "resolution": "720P", "ratio": "16:9", "duration": 10, "prompt_extend": false, "watermark": true } }' Referensi gambar tunggal (gambar multi-panel) Anda dapat memberikan gambar referensi sembilan panel untuk mengontrol alur cerita, komposisi kamera, dan desain karakter guna menghasilkan video. curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \ -H 'X-DashScope-Async: enable' \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "model": "wan2.7-r2v-2026-06-12", "input": { "prompt": "Based on the reference image, in the style of a 3D cartoon adventure movie. The characters are in a cute Q-style but with detailed textures, smooth movements, and vibrant colors. Keep the characters and the forest scene consistent. Do not add text. Atmosphere: Adventurous, light-hearted, mysterious, whimsical. Characters: A young boy explorer with a round hat, backpack, and short cloak. His sidekick: a small flying robot with a round body and glowing blue eyes. Scene: A magical forest with giant tree roots, mushrooms, vines, a treasure cave entrance, and sunbeams. Storyboard: 1. Wide shot: Tall trees and intersecting sunbeams in the magical forest, creating a mysterious and bright environment. 2. Medium shot: The little boy pushes aside vines to explore forward. 3. Medium shot: The little robot flies beside him, scanning ahead with its blue light. 4. Close-up: An old treasure map unfolds in his hands. 5. Close-up: His face lights up with excitement. 6. Action shot: The two jump over tree roots and a small stream, venturing deeper into the forest. 7. Medium shot: A moss-covered treasure chest is revealed behind the vines. 8. Close-up: A golden glow emanates from the edge of the chest. 9. Final shot: The boy and the robot stand before the chest, looking at each other in surprise, filled with a sense of adventure.", "media": [ { "type": "reference_image", "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260403/wgjaxy/banana_storyboard_00000020.png" } ] }, "parameters": { "resolution": "720P", "duration": 10, "prompt_extend": false, "watermark": true } }'
Header
Content-Type `string` (Wajib) Tipe konten permintaan. Harus berupa `application/json`.
Authorization `string` (Wajib) Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
X-DashScope-Async `string` (Wajib) Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus diatur ke `enable`. Penting Jika header permintaan ini tidak disertakan, kesalahan "current user api does not support synchronous calls" akan dikembalikan.
Body permintaan
model `string` (Wajib) Nama model. Untuk daftar model dan harga, lihat Harga model. Contoh: wan2.7-r2v, wan2.7-r2v-2026-06-12.
input `object` (Wajib) Informasi input dasar, seperti prompt. Properti prompt `string` (Wajib) Prompt teks yang menjelaskan elemen dan fitur visual yang diinginkan dalam video yang dihasilkan. Mendukung bahasa Tionghoa dan Inggris. Setiap karakter Tionghoa, huruf, dan tanda baca dihitung sebagai satu karakter. Teks yang melebihi batas akan dipotong secara otomatis. wan2.7-r2v, wan2.7-r2v-2026-06-12: Maksimal 5.000 karakter. Identifikasi referensi: Dalam prompt, gunakan identifikasi seperti "Image 1, Image 2" untuk gambar dan "Video 1, Video 2" untuk video. Sisipkan spasi antara kata dan angka, serta gunakan huruf kapital di awal. Urutan identifikasi harus sesuai dengan urutan aset dalam array `media`. Gambar dan video dihitung secara terpisah, sehingga "Image 1" dan "Video 1" dapat digunakan bersamaan. Jika hanya ada satu gambar atau video referensi, sederhanakan referensinya menjadi "the reference image" atau "the reference video". Deskripsi adegan: Misalnya, jika Image 1 adalah kucing dan Image 2 adalah ruangan, Anda dapat menggambarkan kucing tersebut sedang bermain di ruangan itu dengan dua metode. Pertama, gunakan identifier secara langsung, seperti “Image 1 sedang bermain di Image 2”. Kedua, lengkapi deskripsi dengan subjek dan adegan, seperti “Kucing dari Image 1 sedang bermain di ruangan dari Image 2”. Jika gambar referensi berupa storyboard multi-panel, gambarkan adegan dalam format multi-shot di prompt. Anda tidak perlu menggambarkan setiap panel — cukup berikan shot utama, dan model akan secara otomatis mengenali logika panel serta melengkapi adegan yang tersisa. Untuk hasil terbaik, gunakan hanya satu gambar multi-panel dalam satu waktu. Untuk tips penggunaan prompt, lihat Panduan prompt teks-ke-video/gambar-ke-video. negative_prompt `string` (Opsional) Prompt negatif yang menjelaskan konten yang harus dikecualikan dari video yang dihasilkan. Gunakan ini untuk membatasi output. Mendukung bahasa Tionghoa dan Inggris. Panjang maksimum: 500 karakter. Teks yang melebihi batas akan dipotong secara otomatis. Contoh: low resolution, error, worst quality, low quality, disfigured, extra fingers, bad proportions. media `array` (Wajib) Array aset media (gambar, video, dan audio) yang digunakan sebagai referensi visual dan audio. Gambar dapat mencakup beberapa sudut pandang, umumnya digunakan untuk mereferensikan karakter, properti, dan adegan. Setiap elemen dalam array adalah objek media yang berisi bidang `type` dan `url`. Urutan elemen dalam array sesuai dengan identifikasi referensi dalam `prompt`. Gambar dan video dihitung secara terpisah, sehingga "Image 1" dan "Video 1" dapat digunakan bersamaan. `reference_video` pertama dalam array sesuai dengan Video 1, yang kedua dengan Video 2, dan seterusnya. `reference_image` pertama dalam array sesuai dengan Image 1, yang kedua dengan Image 2, dan seterusnya. Properti type `string` (Wajib) Jenis aset media. Nilai yang valid: `reference_image`: Gambar referensi yang menyediakan referensi visual untuk karakter utama (orang, hewan, atau objek) atau adegan. `reference_video`: Video referensi yang menyediakan referensi visual dan suara untuk karakter utama (orang, hewan, atau objek). Hindari penggunaan video adegan kosong. `first_frame`: Frame pertama video. Video yang dihasilkan dimulai dari frame ini, yang biasanya berisi karakter utama (orang, hewan, atau objek). Anda dapat menggabungkan frame pertama dengan referensi subjek untuk kontrol bersama. Kasus penggunaan umum: Subjek sudah muncul di frame pertama: Gunakan referensi subjek untuk meningkatkan konsistensi atau menambahkan referensi suara. Subjek tidak muncul di frame pertama: Gunakan referensi subjek untuk menentukan fitur subjek baru yang muncul selama video. Batas aset: Maksimal 1 gambar frame pertama. Minimal 1 gambar referensi atau video referensi. Gambar referensi + Video referensi ≤ 5. Jika digunakan untuk karakter utama, aset referensi harus hanya berisi satu karakter. url `string` (Wajib) URL aset media. Setiap nilai dapat mengarah ke satu gambar atau satu video. Kirimkan gambar referensi (type=reference_image) URL atau data yang dienkode Base64 dari gambar referensi. Gambar dapat berupa subjek (orang, hewan, atau objek) atau latar belakang. Jika berisi subjek, gambar tersebut harus hanya berisi satu karakter. Batas gambar: Format: JPEG, JPG, PNG (saluran alpha tidak didukung), BMP, atau WEBP. Resolusi: Lebar dan tinggi harus antara 240 hingga 8.000 piksel. Rasio aspek: 1:8 hingga 8:1. Ukuran file: Maksimal 20 MB. Format input yang didukung: URL publik: Protokol HTTP atau HTTPS didukung. Contoh: https://xxx/xxx.png. String gambar yang dienkode Base64: Format data: `data:{MIME_type};base64,{base64_data}`. Contoh: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (String yang dienkode terlalu panjang dan hanya ditampilkan cuplikannya.) Untuk informasi lebih lanjut, lihat Kirimkan gambar. Kirimkan video referensi (type=reference_video) URL video referensi. Video harus mencakup subjek (orang, hewan, atau objek). Hindari penggunaan video latar belakang atau adegan kosong. Jika video mencakup subjek, video tersebut harus hanya berisi satu karakter. Jika video memiliki audio, suara tersebut juga dapat direferensikan. Batas video: Format: MP4 atau MOV. Durasi: 1 hingga 30 detik. Resolusi: Lebar dan tinggi harus antara 240 hingga 4.096 piksel. Rasio aspek: 1:8 hingga 8:1. Ukuran file: Maksimal 100 MB. Format input yang didukung: URL publik: Protokol HTTP dan HTTPS didukung. Contoh: https://xxx/xxx.mp4. reference_voice `string` (Opsional) URL audio yang menentukan suara untuk karakter utama dalam aset referensi (gambar atau video). Gunakan parameter ini dengan `reference_image` atau `reference_video`. Audio hanya berfungsi sebagai referensi suara dan tidak menentukan konten yang diucapkan. Untuk hasil terbaik, sesuaikan bahasa audio referensi dengan bahasa prompt. Logika audio: Perilaku default: Jika `reference_video` berisi audio tetapi `reference_voice` tidak ditentukan, audio asli video akan digunakan. Prioritas: Jika `reference_video` (dengan audio) dan `reference_voice` keduanya disediakan, `reference_voice` memiliki prioritas lebih tinggi dan menggantikan audio asli video. Batas audio: Format: WAV atau MP3. Durasi: 1 hingga 10 detik. Ukuran file: Maksimal 15 MB. Format input yang didukung: URL publik: Protokol HTTP dan HTTPS didukung. Contoh: https://xxx/xxx.mp3.
parameters `object` (Opsional) Parameter pemrosesan video, seperti resolusi video. Properti resolution `string` (Opsional) Penting `resolution` secara langsung memengaruhi biaya. Konfirmasi harga di Konsol Model Studio sebelum melakukan panggilan. Tingkat resolusi video yang dihasilkan. Mengontrol jumlah total piksel. wan2.7-r2v, wan2.7-r2v-2026-06-12: Nilai yang valid adalah 720P dan 1080P. Nilai default adalah `1080P`. ratio `string` (Opsional) Rasio aspek video yang dihasilkan. Perilaku: Tidak ada gambar frame pertama yang disediakan: Video menggunakan `ratio` yang ditentukan. Gambar frame pertama disediakan: Parameter `ratio` diabaikan. Video akan menyesuaikan rasio aspek gambar frame pertama. Nilai yang valid: `16:9` (default) `9:16` `1:1` `4:3` `3:4` duration `integer` (Opsional) Penting Durasi secara langsung memengaruhi biaya. Konfirmasi harga model sebelum memanggil API. Durasi video yang dihasilkan dalam satuan detik. wan2.7-r2v, wan2.7-r2v-2026-06-12: Nilai default adalah 5. Jika materi referensi mencakup video, nilainya harus bilangan bulat antara 2 hingga 10. Jika materi referensi tidak mencakup video, nilainya harus bilangan bulat antara 2 hingga 15. prompt_extend `boolean` (Opsional) Mengaktifkan penulisan ulang prompt. Saat diaktifkan, model akan menulis ulang prompt input sebelum generasi. Ini secara signifikan meningkatkan kualitas untuk prompt yang lebih pendek tetapi meningkatkan waktu pemrosesan. true (default) false watermark `boolean` (Opsional) Menambahkan watermark. Teks watermark adalah "AI Generated", ditempatkan di pojok kanan bawah video. `false` (default) `true` seed `integer` (Opsional) Bilangan acak seed harus berupa bilangan bulat dalam rentang `[0, 2147483647]`. Jika tidak ditentukan, seed acak akan dihasilkan. Seed tetap meningkatkan kemampuan reproduksi. Karena generasi model bersifat probabilistik, seed yang sama tidak menjamin hasil identik.

Parameter respons	Respons berhasil Simpan `task_id` untuk mengkueri status dan hasil tugas. `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }` Respons kesalahan Pembuatan tugas gagal. Lihat Kode kesalahan. `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` Informasi output tugas. Properti task_id `string` ID tugas. Berlaku untuk kueri selama 24 jam. task_status `string` Status tugas. Nilai enumerasi PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
request_id `string` Identifier permintaan unik untuk pelacakan dan troubleshooting.
code `string` Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.
message `string` Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

Langkah 2: Kueri hasil berdasarkan ID tugas

Singapura

GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Beijing

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Catatan

Rekomendasi polling: Pembuatan video memakan waktu beberapa menit. Gunakan mekanisme polling dengan interval yang wajar, misalnya 15 detik.
Transisi status tugas: PENDING → RUNNING → SUCCEEDED atau FAILED.
Tautan hasil: Setelah tugas berhasil, URL video yang berlaku selama 24 jam akan dikembalikan. Unduh dan simpan video ke penyimpanan permanen, seperti OSS.
task_id masa berlaku: 24 jam. Setelah periode ini, kueri akan mengembalikan status tugas sebagai UNKNOWN.

Parameter permintaan	Kueri hasil tugas Ganti `{task_id}` dengan nilai `task_id` yang dikembalikan oleh panggilan API sebelumnya. `task_id` berlaku untuk kueri selama 24 jam. `curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
Header
Authorization `string` (Wajib) Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
Parameter path
task_id `string` (Wajib) ID tugas.

Parameter respons	Tugas berhasil URL video hanya berlaku selama 24 jam, lalu secara otomatis dihapus. Segera simpan video yang dihasilkan. { "request_id": "52cade0d-905e-9b7d-a01e-xxxxxx", "output": { "task_id": "18814247-f944-4102-aa4a-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2026-04-02 22:53:19.537", "scheduled_time": "2026-04-02 22:53:30.427", "end_time": "2026-04-02 23:00:39.287", "orig_prompt": "Video 2 holds Image 3 and plays a soothing American country ballad in a coffee shop, while Video 1 smiles, watches Video 2, and slowly walks towards him", "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?xxxx" }, "usage": { "duration": 15, "input_video_duration": 5, "output_video_duration": 10, "video_count": 1, "SR": 720, "ratio": "16:9" } } Tugas gagal Saat tugas gagal, `task_status` bernilai FAILED dengan kode dan pesan kesalahan. Lihat Kode kesalahan. `{ "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d", "output": { "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010", "task_status": "FAILED", "code": "InvalidParameter", "message": "The size is not match xxxxxx" } }` Kueri tugas kedaluwarsa `task_id` berlaku selama 24 jam. Setelah periode ini, kueri akan mengembalikan kesalahan berikut. `{ "request_id": "a4de7c32-7057-9f82-8581-xxxxxx", "output": { "task_id": "502a00b1-19d9-4839-a82f-xxxxxx", "task_status": "UNKNOWN" } }`
output `object` Informasi output tugas. Properti task_id `string` (Wajib) ID tugas. task_status `string` Status tugas. Nilai enumerasi PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui. submit_time `string` Waktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS. scheduled_time `string` Waktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS. end_time `string` Waktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS. video_url `string` URL video yang dihasilkan. Hanya dikembalikan saat `task_status` bernilai SUCCEEDED. Berlaku selama 24 jam. Video dalam format MP4 dengan enkode H.264. orig_prompt `string` Prompt input asli, sesuai dengan parameter permintaan `prompt`. code `string` Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. message `string` Pesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.
usage `object` Statistik output. Diisi hanya untuk tugas yang berhasil. Properti input_video_duration `integer` Durasi video input, dalam satuan detik. output_video_duration `integer` Durasi video output, dalam satuan detik. duration `integer` Total durasi video. Biaya dihitung berdasarkan nilai ini. Rumus: `duration = input_video_duration + output_video_duration`. SR `integer` Tingkat resolusi video yang dihasilkan. Contoh: 720. ratio `string` Rasio aspek video yang dihasilkan. Contoh: 16:9. video_count `integer` Jumlah video yang dihasilkan. Nilainya selalu 1.
request_id `string` Identifier permintaan unik untuk pelacakan dan troubleshooting.

DashScope SDK

Nama parameter SDK sebagian besar konsisten dengan API HTTP. Struktur parameter dienkapsulasi berdasarkan fitur bahasa.

Tugas referensi-ke-video biasanya memakan waktu 1 hingga 5 menit. SDK membungkus alur asinkron HTTP dan mendukung panggilan sinkron maupun asinkron.

Waktu pemrosesan aktual bergantung pada panjang antrian dan status layanan.

Python SDK

Penting

Membutuhkan DashScope Python SDK versi 1.25.16 atau lebih baru.

Versi lama dapat memicu kesalahan seperti "url error, please check url!". Untuk instruksi pembaruan, lihat Instal SDK.

Atur base_http_api_url berdasarkan wilayah model:

Singapura

dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Beijing

dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Panggilan sinkron

Panggilan sinkron akan menunggu hingga pembuatan video selesai dan langsung mengembalikan hasilnya.

Contoh permintaan

from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# URL berikut untuk wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: api_key="sk-xxx"
# Kunci API berbeda-beda tergantung wilayah. Untuk mendapatkan kunci API, lihat https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_sync_call_r2v():
    # Panggilan sinkron, langsung mengembalikan hasil.
    print('please wait...')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model='wan2.7-r2v-2026-06-12',
        prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
        media=[
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        resolution='720P',
        ratio='16:9',
        duration=10,
        prompt_extend=False,
        watermark=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_sync_call_r2v()

Contoh respons

video_url berlaku selama 24 jam. Segera unduh video tersebut.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Panggilan asinkron

Panggilan asinkron langsung mengembalikan ID tugas. Lakukan polling atau tunggu hingga selesai secara terpisah.

Contoh permintaan

import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope

# URL berikut untuk wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: api_key="sk-xxx"
# Kunci API berbeda-beda tergantung wilayah. Untuk mendapatkan kunci API, lihat https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

def sample_async_call_r2v():
    # Panggilan asinkron, mengembalikan task_id.
    rsp = VideoSynthesis.async_call(
        api_key=api_key,
        model='wan2.7-r2v-2026-06-12',
        prompt='Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, "The sunshine is so nice today." Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, "That sounds lovely. Can you sing it again?"',
        media=[
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
                "reference_voice": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        resolution='720P',
        ratio='16:9',
        duration=10,
        prompt_extend=False,
        watermark=True)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print("task_id: %s" % rsp.output.task_id)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

    # Dapatkan informasi tugas asinkron.
    status = VideoSynthesis.fetch(task=rsp, api_key=api_key)
    if status.status_code == HTTPStatus.OK:
        print(status.output.task_status)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (status.status_code, status.code, status.message))

    # Tunggu hingga tugas asinkron selesai.
    rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
    print(rsp)
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_async_call_r2v()

Contoh respons

Contoh respons saat membuat tugas:

{
    "status_code": 200,
    "request_id": "6dc3bf6c-be18-9268-9c27-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
        "task_status": "PENDING",
        "video_url": ""
    },
    "usage": null
}

Contoh respons saat mengkueri hasil tugas:

video_url berlaku selama 24 jam. Segera unduh video tersebut.

{
    "status_code": 200,
    "request_id": "b040d446-f9b6-977f-b9ad-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "5dab3291-393e-424d-929b-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-17 17:12:49.076",
        "scheduled_time": "2026-04-17 17:13:00.384",
        "end_time": "2026-04-17 17:29:43.386",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\""
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720,
        "ratio": "16:9"
    }
}

Java SDK

Penting

Pastikan versi DashScope Java SDK minimal 2.22.14 sebelum menjalankan kode berikut.

Versi lama dapat memicu kesalahan seperti "url error, please check url!". Untuk instruksi pembaruan, lihat Instal SDK.

Atur baseHttpApiUrl berdasarkan wilayah model:

Singapura

Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Beijing

Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Panggilan sinkron

Panggilan sinkron akan menunggu hingga pembuatan video selesai dan langsung mengembalikan hasilnya.

Contoh permintaan

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2Video {

    static {
        // URL berikut untuk wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: apiKey="sk-xxx"
    // Kunci API berbeda-beda tergantung wilayah. Untuk mendapatkan kunci API, lihat https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void ref2video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            ref2video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Contoh respons

video_url berlaku selama 24 jam. Segera unduh video tersebut.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Panggilan asinkron

Panggilan asinkron langsung mengembalikan ID tugas. Lakukan polling atau tunggu hingga selesai secara terpisah.

Contoh permintaan

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisListResult;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class Ref2VideoAsync {

    static {
        // URL berikut untuk wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: apiKey="sk-xxx"
    // Kunci API berbeda-beda tergantung wilayah. Untuk mendapatkan kunci API, lihat https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void asyncRef2video() throws ApiException, NoApiKeyException, InputRequiredException, InterruptedException {
        VideoSynthesis vs = new VideoSynthesis();
        List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>(){{
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg")
                    .type("reference_image")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/gbqewz/wan-r2v-girl-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4")
                    .type("reference_video")
                    .referenceVoice("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/isllrq/wan-r2v-boy-voice.mp3")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/rtjeqf/wan-r2v-object3.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png")
                    .type("reference_image")
                    .build());
            add(VideoSynthesisParam.Media.builder()
                    .url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png")
                    .type("reference_image")
                    .build());
        }};
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("resolution", "720P");
        parameters.put("ratio", "16:9");
        parameters.put("prompt_extend", false);
        parameters.put("watermark", true);

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.7-r2v-2026-06-12")
                        .prompt("Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"")
                        .media(media)
                        .duration(10)
                        .parameters(parameters)
                        .build();
        // Kirim tugas asinkron.
        VideoSynthesisResult result = vs.asyncCall(param);
        System.out.println("task_id: " + result.getOutput().getTaskId());
        System.out.println(JsonUtils.toJson(result));

        // Tunggu hingga tugas selesai.
        result = vs.wait(result, null);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            asyncRef2video();
        } catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Contoh respons

Contoh respons saat membuat tugas:

{
    "request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
    "output": {
        "task_id": "7277e20e-aa01-4709-xxxxxxxx",
        "task_status": "PENDING"
    }
}

Contoh respons saat mengkueri hasil tugas:

video_url berlaku selama 24 jam. Segera unduh video tersebut.

{
    "request_id": "f6365287-336f-9f2b-ab59-xxxxxx",
    "output": {
        "task_id": "cb7f1da5-a987-41de-b0a4-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxxx",
        "orig_prompt": "Video 1 holds Image 3, plays a soothing country folk song on the chair from Image 4, and says, \"The sunshine is so nice today.\" Image 1, holding Image 2, walks past Video 1, places Image 2 on the table next to it, and says, \"That sounds lovely. Can you sing it again?\"",
        "submit_time": "2026-04-17 17:15:11.536",
        "scheduled_time": "2026-04-17 17:15:20.316",
        "end_time": "2026-04-17 17:29:44.277"
    },
    "usage": {
        "video_count": 1,
        "duration": 15,
        "input_video_duration": 5,
        "output_video_duration": 10,
        "SR": 720
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Kode kesalahan

Jika pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk solusinya.

FAQ

Bagaimana cara menambahkan suara ke subjek (referensi suara)?

Hanya wan2.7 yang mendukung referensi suara. Dalam objek media, Anda dapat mengirimkan URL audio dalam parameter reference_voice untuk menentukan referensi suara untuk gambar atau video referensi.

{
    "media": [
        {
            "type": "reference_image",
            "url": "<URL of the reference image>",
            "reference_voice": "<URL of the audio>"
        },
        {
            "type": "reference_video",
            "url": "<URL of the reference video>",
            "reference_voice": "<URL of the audio>"
        }
    ]
}

Ketersediaan

HTTP

Langkah 1: Buat tugas dan dapatkan ID tugas

Singapura

Beijing

Parameter permintaan

Referensi multi-subjek (gambar + video + suara)

Referensi gambar tunggal (gambar multi-panel)

Header

Body permintaan

Parameter respons

Respons berhasil

Respons kesalahan

Langkah 2: Kueri hasil berdasarkan ID tugas

Singapura

Beijing

Parameter permintaan

Kueri hasil tugas

Header

Parameter path

Parameter respons

Tugas berhasil

Tugas gagal

Kueri tugas kedaluwarsa

DashScope SDK

Python SDK

Singapura

Beijing

Panggilan sinkron

Contoh permintaan

Contoh respons

Panggilan asinkron

Contoh permintaan

Contoh respons

Java SDK

Singapura

Beijing

Panggilan sinkron

Contoh permintaan

Contoh respons

Panggilan asinkron

Contoh permintaan

Contoh respons

Kode kesalahan

FAQ

Bagaimana cara menambahkan suara ke subjek (referensi suara)?