All Products
Search
Document Center

Alibaba Cloud Model Studio:Referensi Wanxiang-ke-Video Referensi API

Last Updated:Mar 28, 2026

Model Wanxiang-Reference-to-Video mendukung multimodal input, seperti teks, gambar, dan video. Model ini dapat menghasilkan pertunjukan karakter tunggal atau interaksi multi-karakter dengan manusia atau objek sebagai subjek utama, serta mendukung segmentasi adegan cerdas untuk membuat video multi-shot.

Referensi: Panduan Pengguna

Cakupan Penggunaan

Untuk memastikan pemanggilan berhasil, pastikan model, URL endpoint, dan Kunci API berada di wilayah yang sama. Pemanggilan lintas-wilayah akan gagal.

Catatan

Kode contoh dalam topik ini berlaku untuk wilayah Singapura.

Pemanggilan HTTP

Karena tugas reference-to-video memakan waktu lama (biasanya 1 hingga 5 menit), API menggunakan pemanggilan asinkron. Alur kerja lengkap terdiri dari dua langkah inti: Buat tugas → Polling hasil.

Langkah 1: Buat Tugas dan Dapatkan ID Tugas

Singapura

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

AS (Virginia)

POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Beijing

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Catatan

Parameter Permintaan

Interaksi Multi-Karakter (Menggunakan Gambar dan Video Referensi)

Teruskan URL gambar dan video dalam reference_urls. Atur shot_type ke multi untuk menghasilkan video multi-shot.

curl --location 'https://dashscope-intl.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.6-r2v-flash",
    "input": {
        "prompt": "Character2 sits on a chair by the window, holding character3, and plays a soothing American country folk song beside character4. Character1 says to Character2, “that sounds great“",
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
        ]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "audio": true,
        "shot_type": "multi",
        "watermark": true
    }
}'

Interaksi Multi-Karakter (Menggunakan Hanya Video Referensi)

Teruskan beberapa URL video dalam reference_urls. Atur shot_type ke multi untuk menghasilkan video multi-shot.

curl --location 'https://dashscope-intl.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.6-r2v",
    "input": {
        "prompt": "character1 says to character2: “I’ll rely on you tomorrow morning!” character2 replies: “You can count on me!”",
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251217/dlrrly/%E5%B0%8F%E5%A5%B3%E5%AD%A91%E8%8B%B1%E6%96%872.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20251217/fkxknn/%E9%93%83%E9%93%83.mp4"
        ]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 10,
        "shot_type": "multi"
    }
}'

Peran Tunggal Bermain Peran

Teruskan satu URL video dalam reference_urls. Atur shot_type ke multi untuk menghasilkan video multi-shot.

# Catatan: Jika Anda menggunakan model dari China (Beijing), ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis
curl --location 'https://dashscope-intl.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.6-r2v",
    "input": {
        "prompt": "character1 drinks bubble tea and improvises a dance to music.",
        "reference_urls":["https://cdn.wanxai.com/static/demo-wan26/vace.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "shot_type":"multi"
    }
}'

Hasilkan Video Tanpa Suara

Hanya wan2.6-r2v-flash yang mendukung pembuatan video tanpa suara.

Saat menghasilkan video tanpa suara, Anda harus secara eksplisit mengatur parameters.audio = false.

curl --location 'https://dashscope-intl.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.6-r2v-flash",
    "input": {
        "prompt": "character1 drinks bubble tea and improvises a dance to music.",
        "reference_urls":["https://cdn.wanxai.com/static/demo-wan26/vace.mp4"]
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "shot_type":"multi"
    }
}'
Header Permintaan

Content-Type string (Wajib)

Tipe konten permintaan. Harus berupa application/json.

Authorization string (Wajib)

Kredensial otentikasi menggunakan Kunci API Model Studio.

Contoh: Bearer sk-xxxx

X-DashScope-Async string (Wajib)

Mengaktifkan pemrosesan asinkron. Harus diatur ke enable karena permintaan HTTP hanya mendukung pemrosesan asinkron.

Penting

Mengembalikan kesalahan "current user api does not support synchronous calls" jika tidak disertakan.

Body Permintaan

model string (Wajib)

Nama model. Untuk daftar lengkap dan detail harga, lihat Harga Model.

Nilai contoh: wan2.6-r2v-flash.

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

Prompt teks. Menggambarkan elemen dan fitur visual yang Anda harapkan dalam video yang dihasilkan.

Mendukung bahasa Mandarin dan Inggris. Setiap karakter Mandarin, huruf, atau tanda baca dihitung sebagai satu karakter. Karakter berlebih dipotong secara otomatis.

  • wan2.6-r2v-flash: Maksimal 1.500 karakter.

  • wan2.6-r2v: Maksimal 1.500 karakter.

Referensi peran: Gunakan pengenal seperti `character1` dan `character2` untuk merujuk peran referensi. Setiap referensi, baik video maupun gambar, harus hanya berisi satu peran. Model hanya mengidentifikasi peran melalui pengenal spesifik ini.

Contoh nilai: character1 menonton film dengan bahagia di sofa.

Untuk tips menulis prompt, lihat Panduan Prompt Text-to-Video / Image-to-Video.

negative_prompt string (Opsional)

Prompt negatif. Menggambarkan konten yang tidak Anda inginkan dalam video yang dihasilkan dan membantu membatasi output.

Mendukung bahasa Mandarin dan Inggris, dengan maksimal 500 karakter. Karakter berlebih dipotong secara otomatis.

Nilai contoh: low resolution, errors, worst quality, low quality, incomplete, extra fingers, poor proportions.

reference_urls array[string] (Wajib)

Penting

`reference_urls` berdampak langsung pada penagihan. Untuk informasi lebih lanjut, lihat Penagihan dan Pembatasan Laju.

Array URL yang mengarah ke file referensi. Mendukung video dan gambar. File-file ini digunakan untuk mengekstrak penampilan dan suara karakter (jika ada) guna menghasilkan video yang sesuai dengan ciri tersebut.

  • Setiap URL mengarah ke satu gambar atau satu video:

    • Maksimal 5 gambar.

    • Maksimal 3 video.

    • Jumlah total gambar dan video tidak boleh melebihi 5.

  • Jika Anda memberikan beberapa referensi, urutan URL dalam array menentukan urutan peran. URL pertama dipetakan ke `character1`, yang kedua ke `character2`, dan seterusnya.

  • Setiap file referensi harus hanya berisi satu subjek utama. Misalnya, `character1` adalah seorang gadis kecil dan `character2` adalah jam alarm.

Format yang didukung:

  1. URL publik:

    • Mendukung protokol HTTP atau HTTPS.

    • Nilai contoh: https://cdn.translate.alibaba.com/xxx.png.

Persyaratan video referensi:

  • Format: MP4, MOV.

  • Durasi: 1 hingga 30 detik.

  • Ukuran file: Maksimal 100 MB.

Persyaratan gambar referensi:

  • Format: JPEG, JPG, PNG (tanpa saluran alfa), BMP, WEBP.

  • Resolusi: Lebar dan tinggi harus antara 240 hingga 8.000 piksel.

  • Ukuran file: Maksimal 10 MB.

Nilai contoh: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.jpg"].

Bidang yang Ditinggalkan

reference_video_urls array[string]

Penting

Gunakan reference_urls sebagai ganti reference_video_urls.

Array URL yang mengarah ke file video referensi. File-file ini digunakan untuk mengekstrak penampilan dan suara karakter (jika ada) guna menghasilkan video yang sesuai dengan ciri tersebut.

  • Maksimal 3 video.

  • Jika Anda memberikan beberapa video, urutan URL dalam array menentukan urutan peran. URL pertama dipetakan ke `character1`, yang kedua ke `character2`, dan seterusnya.

  • Setiap video referensi harus hanya berisi satu karakter. Misalnya, `character1` adalah seorang gadis kecil dan `character2` adalah jam alarm.

  • URL harus menggunakan protokol HTTP atau HTTPS.

Persyaratan video tunggal:

  • Format: MP4, MOV.

  • Durasi: 2 hingga 30 detik.

  • Ukuran file: hingga 100 MB.

Nilai contoh: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4"].

parameters object (Opsional)

Parameter pemrosesan video, seperti pengaturan resolusi.

Properti

size string (Opsional)

Penting
  • `size` berdampak langsung pada penagihan. Biaya dihitung sebagai berikut: Harga Satuan (berdasarkan resolusi) × Durasi (dalam detik). Untuk model yang sama, 1080P lebih mahal daripada 720P. Sebelum melakukan pemanggilan, lihat Harga Model.

  • Anda harus mengatur `size` ke nilai tertentu, seperti 1280*720. Jangan gunakan rasio seperti 1:1 atau label seperti 720P.

Resolusi target video dalam format lebar*tinggi. Nilai default dan yang diizinkan bergantung pada parameter model.

  • wan2.6-r2v-flash: Nilai default adalah 1920*1080 (1080P). Semua opsi 720P dan 1080P didukung.

  • wan2.6-r2v: Nilai default adalah 1920*1080 (1080P). Semua opsi 720P dan 1080P didukung.

Opsi 720P dan rasio aspeknya:

  • 1280*720: 16:9.

  • 720*1280: 9:16.

  • 960*960: 1:1.

  • 1088*832: 4:3.

  • 832*1088: 3:4.

Opsi 1080P dan rasio aspeknya:

  • 1920*1080: 16:9.

  • 1080*1920: 9:16.

  • 1440*1440: 1:1.

  • 1632*1248: 4:3.

  • 1248*1632: 3:4.

duration integer (Opsional)

Penting

`duration` berdampak langsung pada penagihan. Biaya dihitung sebagai berikut: Harga Satuan (berdasarkan resolusi) × Durasi (dalam detik). Sebelum melakukan pemanggilan, lihat Harga Model.

Durasi target video dalam detik.

  • wan2.6-r2v-flash: Bilangan bulat dari 2 hingga 10. Nilai default adalah 5.

  • wan2.6-r2v: Bilangan bulat dari 2 hingga 10. Nilai default adalah 5.

Nilai contoh: 5.

shot_type string (Opsional)

Menentukan jenis shot untuk video yang dihasilkan. Anda dapat memilih antara shot kontinu tunggal atau beberapa shot yang berganti-ganti.

Prioritas parameter: `shot_type` > `prompt`. Misalnya, jika `shot_type` diatur ke single, model menghasilkan video single-shot meskipun prompt menentukan "generate multi-shot video".

Nilai yang valid:

  • `single`: Nilai default. Menghasilkan video single-shot.

  • `multi`: Menghasilkan video multi-shot.

Nilai contoh: single.

Catatan

Anda dapat menggunakan parameter ini untuk mengontrol struktur narasi secara ketat. Misalnya, Anda dapat menggunakan single shot untuk demo produk dan multiple shots untuk cerita pendek.

audio boolean (Opsional)

Penting

`audio` berdampak langsung pada penagihan. Harga video dengan audio dan video tanpa suara berbeda. Sebelum melakukan pemanggilan, lihat Harga Model.

Model yang didukung: wan2.6-r2v-flash.

Menentukan apakah akan menghasilkan video dengan audio.

Nilai yang valid:

  • `true`: Nilai default. Menghasilkan video dengan audio.

  • `false`: Menghasilkan video tanpa suara.

Nilai contoh: true.

watermark boolean (Opsional)

Menentukan apakah akan menambahkan watermark di pojok kanan bawah video. Teks watermark adalah "AI Generated".

  • `false`: Nilai default. Tidak ada watermark yang ditambahkan.

  • `true`: Watermark ditambahkan.

Nilai contoh: false.

seed integer (Opsional)

Bilangan acak seed. Harus merupakan bilangan bulat antara 0 dan 2147483647.

Jika tidak diberikan, seed acak akan dihasilkan. Menggunakan seed tetap meningkatkan kemampuan reproduksi, meskipun hasilnya mungkin masih bervariasi karena keacakan model.

Contoh: 12345

Parameter Tanggapan

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

Tanggapan Kesalahan

Pembuatan tugas gagal. Lihat kode kesalahan untuk menyelesaikan masalah.

{
    "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. Dapat digunakan untuk mengkueri tugas hingga 24 jam.

task_status string

Status tugas.

Enumerasi

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: Tugas tidak ada atau status tidak diketahui

request_id string

Pengenal unik untuk permintaan. Digunakan untuk pelacakan dan troubleshooting masalah.

code string

Kode kesalahan. Dikembalikan hanya saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

message string

Pesan kesalahan detail. Dikembalikan hanya saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

Langkah 2: Kueri Hasil Menggunakan ID Tugas

Singapura

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

Virginia

GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}

Beijing

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Catatan
  • Saran polling: Generasi video dapat memakan waktu beberapa menit. Gunakan mekanisme polling dengan interval kueri yang wajar, misalnya 15 detik, untuk mengambil hasilnya.

  • Transisi status tugas: PENDING → RUNNING → SUCCEEDED atau FAILED.

  • URL hasil: Setelah tugas berhasil, URL video dikembalikan. URL tersebut berlaku selama 24 jam. Setelah Anda mendapatkan URL, segera unduh dan simpan video ke layanan penyimpanan permanen, seperti Object Storage Service (OSS).

  • Masa berlaku task_id: 24 jam. Setelah periode ini, Anda tidak dapat mengkueri hasilnya, dan API mengembalikan status tugas UNKNOWN.

Parameter Permintaan

Kueri Hasil Tugas

Ganti {task_id} dengan nilai task_id yang dikembalikan oleh pemanggilan API sebelumnya. task_id berlaku untuk kueri dalam 24 jam.

curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Header Permintaan

Authorization string (Wajib)

Kredensial otentikasi menggunakan Kunci API Model Studio.

Contoh: Bearer sk-xxxx

Parameter Jalur URL

task_id string (Wajib)

ID tugas yang akan dikueri.

Parameter Tanggapan

Tugas Berhasil

URL video hanya disimpan selama 24 jam lalu secara otomatis dihapus. Segera simpan video yang dihasilkan.

{
    "request_id": "caa62a12-8841-41a6-8af2-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-12-16 00:25:59.869",
        "scheduled_time": "2025-12-16 00:25:59.900",
        "end_time": "2025-12-16 00:30:35.396",
        "orig_prompt": "character1 watches a movie happily on the sofa",
        "video_url": "https://dashscope-result-sh.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
     "usage": {
        "duration": 10.0,
        "size": "1280*720",
        "input_video_duration": 5,
        "output_video_duration": 5,
        "video_count": 1,
        "SR": 720
    }
}

Tugas Gagal

Saat tugas gagal, task_status diatur ke FAILED dengan kode dan pesan kesalahan. Lihat kode kesalahan untuk menyelesaikan masalah.

{
    "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 gagal dan mengembalikan pesan 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 yang akan dikueri.

task_status string

Status tugas.

Enumerasi

  • PENDING

  • RUNNING

  • SUCCEEDED

  • FAILED

  • CANCELED

  • UNKNOWN: Tugas tidak ada atau status tidak diketahui

submit_time string

Waktu saat tugas diajukan. Waktu dalam UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time string

Waktu saat tugas mulai berjalan. Waktu dalam UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

end_time string

Waktu saat tugas selesai. Waktu dalam UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

video_url string

URL video yang dihasilkan. Dikembalikan hanya saat task_status adalah SUCCEEDED.

URL berlaku selama 24 jam. Gunakan untuk mengunduh video dalam format MP4 dengan encoding H.264.

orig_prompt string

Prompt input asli. Ini adalah nilai dari parameter permintaan prompt.

code string

Kode kesalahan. Dikembalikan hanya saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

message string

Pesan kesalahan detail. Dikembalikan hanya saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

usage object

Statistik penggunaan. Ini hanya dihitung untuk hasil yang berhasil.

Properti

input_video_duration integer

Durasi video referensi input, dalam detik.

output_video_duration integer

Durasi video output, dalam detik.

duration float

Total durasi video. Nilai ini digunakan untuk penagihan.

Rumus: duration = input_video_duration + output_video_duration.

SR integer

Tingkat resolusi video yang dihasilkan. Nilai contoh: `720`.

sizestring

Resolusi video yang dihasilkan. Formatnya adalah `lebar*tinggi`. Nilai contoh: `1280*720`.

video_count integer

Jumlah video yang dihasilkan. Nilainya tetap 1.

request_id string

Pengenal unik untuk permintaan. Digunakan untuk pelacakan dan troubleshooting masalah.

Batasan

  • Kedaluwarsa Data: task_id dan video_url keduanya kedaluwarsa setelah 24 jam. Setelah kedaluwarsa, Anda tidak dapat mengkueri atau mengunduhnya.

  • Moderasi Konten: Prompt input dan video output menjalani moderasi konten. Permintaan yang berisi konten terlarang mengembalikan kesalahan seperti `IPInfringementSuspect` atau `DataInspectionFailed`. Untuk informasi lebih lanjut, lihat Informasi Kesalahan.

Kode kesalahan

Jika pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Pesan kesalahan untuk penyelesaian.

FAQ

T: Bagaimana cara mendapatkan daftar putih nama domain untuk akses penyimpanan video?

J: Video yang dihasilkan oleh model disimpan di OSS. API mengembalikan URL publik sementara. Untuk mengonfigurasi daftar putih firewall untuk URL unduhan ini, perhatikan hal berikut: Penyimpanan dasar dapat berubah secara dinamis. Topik ini tidak menyediakan daftar putih nama domain OSS tetap untuk mencegah masalah akses akibat informasi yang kedaluwarsa. Jika Anda memiliki persyaratan kontrol keamanan, hubungi manajer akun Anda untuk mendapatkan daftar nama domain OSS terbaru.