Wan - referensi-ke-video Referensi API - Alibaba Cloud Model Studio

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.

Kode contoh dalam topik ini berlaku untuk wilayah Singapura.

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

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
Beijing

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

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

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

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.

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)

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)

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_extendboolean (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.

Referensi multi-subjek (gambar + video + suara)
Referensi gambar tunggal (gambar multi-panel)

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
        }
    }'

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
        }
    }'

Parameter respons

output objectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

request_id stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

Respons berhasil
Respons kesalahan

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"
}

Langkah 2: Kueri hasil berdasarkan ID tugas

Singapura
Beijing

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

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

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_idmasa berlaku: 24 jam. Setelah periode ini, kueri akan mengembalikan status tugas sebagai UNKNOWN.

Parameter permintaan

Header

Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.

Parameter path

task_id string (Wajib)ID tugas.

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"

Parameter respons

outputobjectInformasi output tugas.

Properti

task_id string (Wajib)ID tugas.task_status stringStatus tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

submit_time stringWaktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL video yang dihasilkan. Hanya dikembalikan saat task_status bernilai SUCCEEDED.Berlaku selama 24 jam. Video dalam format MP4 dengan enkode H.264.orig_prompt stringPrompt input asli, sesuai dengan parameter permintaan prompt.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

usage objectStatistik output. Diisi hanya untuk tugas yang berhasil.

Properti

input_video_duration integerDurasi video input, dalam satuan detik.output_video_duration integerDurasi video output, dalam satuan detik.duration integerTotal durasi video. Biaya dihitung berdasarkan nilai ini.Rumus: duration = input_video_duration + output_video_duration.SR integerTingkat resolusi video yang dihasilkan. Contoh: 720.ratio stringRasio aspek video yang dihasilkan. Contoh: 16:9.video_count integerJumlah video yang dihasilkan. Nilainya selalu 1.

request_id stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.

Tugas berhasil
Tugas gagal
Kueri tugas kedaluwarsa

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"
    }
}

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"
    }
}

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"
    }
}

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

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
Beijing

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

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Panggilan sinkron
Panggilan asinkron

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

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
Beijing

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

Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Panggilan sinkron
Panggilan asinkron

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

Parameter permintaan

Header

Body permintaan

Parameter respons

​Langkah 2: Kueri hasil berdasarkan ID tugas

Parameter permintaan

Header

Parameter path

Parameter respons

​DashScope SDK

​Python SDK

Contoh permintaan

Contoh respons

​Java SDK

Contoh permintaan

Contoh respons

​Kode kesalahan

​FAQ

​Bagaimana cara menambahkan suara ke subjek (referensi suara)?

Ketersediaan

HTTP

Langkah 1: Buat tugas dan dapatkan ID tugas

Langkah 2: Kueri hasil berdasarkan ID tugas

DashScope SDK

Python SDK

Java SDK

Kode kesalahan

FAQ

Bagaimana cara menambahkan suara ke subjek (referensi suara)?