All Products
Search
Document Center

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

Last Updated:Mar 13, 2026

Model Wan - referensi-ke-video mendukung input multi-modal (teks, gambar, dan video) serta menghasilkan video yang menampilkan satu atau beberapa karakter. Model ini mendukung pertunjukan karakter tunggal maupun adegan interaktif multi-karakter, serta pembagian shot cerdas untuk menghasilkan video multi-shot.

Referensi: Panduan pengguna

Cakupan

Agar pemanggilan API berhasil, model, URL titik akhir, dan kunci API harus berada di wilayah yang sama. Pemanggilan lintas-wilayah akan gagal.

Catatan

Kode contoh dalam topik ini berlaku untuk wilayah Singapura.

Pemanggilan HTTP

Tugas referensi-ke-video biasanya memerlukan waktu 1 hingga 5 menit. Oleh karena itu, API menggunakan pemanggilan asinkron. Alur kerja lengkapnya terdiri dari dua langkah inti: buat tugas, lalu lakukan polling untuk hasilnya:

Langkah 1: Buat tugas

Singapura

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

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
  • 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 tutorial pemula, lihat Gunakan Postman atau cURL.

Parameter permintaan

Interaksi multi-karakter (gambar dan video referensi)

Teruskan URL gambar dan video dalam reference_urls dan 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 window-side chair, holding character3, playing a soothing American country folk song next to 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 (video referensi)

Teruskan beberapa URL video dalam reference_urls dan 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"
    }
}'

Asumsi peran karakter tunggal

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

# Catatan: Jika Anda menggunakan model di wilayah 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 while dancing impromptu to the 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 video tanpa suara.

Untuk menghasilkan video tanpa suara, atur secara eksplisit 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 while dancing impromptu to the 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 model dan harga, lihat Harga model.

Contoh: wan2.6-r2v-flash.

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

Prompt teks yang menjelaskan elemen dan fitur visual untuk video yang dihasilkan.

Mendukung bahasa Tiongkok dan Inggris. Setiap karakter, huruf, dan tanda baca dihitung sebagai satu karakter. Teks yang melebihi batas akan dipotong secara otomatis.

  • wan2.6-r2v-flash: Panjang maksimum 1.500 karakter.

  • wan2.6-r2v: Panjang maksimum 1.500 karakter.

Deskripsi referensi peran: Rujuk peran menggunakan pengenal seperti character1 atau character2. Setiap referensi—baik video maupun gambar—hanya berisi satu peran. Model mengidentifikasi peran dalam referensi secara eksklusif dengan cara ini.

Contoh: character1 sedang menonton film dengan gembira di sofa.

Untuk informasi tentang cara menggunakan prompt, lihat Panduan prompt teks-ke-video/gambar-ke-video.

negative_prompt string (Opsional)

Menjelaskan konten yang tidak diinginkan dalam frame video untuk membatasi output.

Mendukung bahasa Tiongkok dan Inggris. Maksimum 500 karakter. Teks yang melebihi batas akan dipotong secara otomatis.

Contoh: resolusi rendah, error, kualitas terburuk, kualitas rendah, cacat, jari ekstra, proporsi buruk.

reference_urls array[string] (Wajib)

Penting

Parameter reference_urls berdampak langsung pada penagihan. Untuk informasi lebih lanjut tentang aturan penagihan, lihat Penagihan dan batas laju.

Array URL untuk file referensi yang diunggah (video dan gambar) yang digunakan untuk mengekstrak penampilan dan suara karakter guna menghasilkan video yang sesuai dengan fitur referensi.

  • Setiap URL dapat menunjuk ke satu gambar atau satu video:

    • Jumlah gambar: 0 hingga 5.

    • Jumlah video: 0 hingga 3.

    • Batas total: Gambar + Video ≤ 5.

  • Ketika Anda menyediakan beberapa file referensi, urutannya menentukan urutan karakter: URL pertama sesuai dengan character1, yang kedua dengan character2, dan seterusnya.

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

Format yang didukung:

  1. URL jaringan publik:

    • Mendukung protokol HTTP atau HTTPS.

    • Contoh: https://cdn.translate.alibaba.com/xxx.png.

Persyaratan untuk video referensi:

  • Format: MP4, MOV.

  • Durasi: 1 hingga 30 detik.

  • Ukuran video: Maksimum 100 MB.

Persyaratan untuk gambar referensi:

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

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

  • Ukuran gambar: Maksimum 10 MB.

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 tidak digunakan lagi

reference_video_urls array[string]

Penting

Kami menyarankan menggunakan reference_urls daripada reference_video_urls.

Array URL untuk video referensi yang diunggah yang digunakan untuk mengekstrak penampilan dan suara karakter guna menghasilkan video yang sesuai dengan fitur referensi.

  • Mendukung hingga 3 video.

  • Ketika Anda menyediakan beberapa video, urutannya menentukan urutan karakter: URL pertama sesuai dengan character1, yang kedua dengan character2, dan seterusnya.

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

  • URL mendukung HTTP atau HTTPS.

Persyaratan untuk setiap video:

  • Format: MP4, MOV.

  • Durasi: 2 hingga 30 detik.

  • Ukuran file: Maksimum 100 MB.

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

parameters object (Opsional)

Parameter untuk resolusi video, penulisan ulang prompt, dan watermark.

Properti

size string (Opsional)

Penting
  • Parameter size berdampak langsung pada penagihan. Biaya sama dengan harga satuan—berdasarkan resolusi—dikalikan durasi dalam detik. Untuk model yang sama, 1080P lebih mahal daripada 720P. Tinjau harga model sebelum memanggil API.

  • Size harus berupa nilai spesifik (seperti 1280*720), bukan rasio seperti 1:1 atau tingkatan seperti 720P.

Resolusi video dalam format lebar*tinggi. Nilai default dan yang tersedia bergantung pada model:

  • wan2.6-r2v-flash: Default adalah 1920*1080 (1080P). Semua resolusi 720P dan 1080P didukung.

  • wan2.6-r2v: Default adalah 1920*1080 (1080P). Semua resolusi 720P dan 1080P didukung.

Tingkatan 720P: Resolusi video dan rasio aspek yang tersedia:

  • 1280*720: 16:9.

  • 720*1280: 9:16.

  • 960*960: 1:1.

  • 1088*832: 4:3.

  • 832*1088: 3:4.

Tingkatan 1080P: Resolusi video dan rasio aspek yang tersedia:

  • 1920*1080: 16:9.

  • 1080*1920: 9:16.

  • 1440*1440: 1:1.

  • 1632*1248: 4:3.

  • 1248*1632: 3:4.

duration integer (Opsional)

Penting

Parameter duration berdampak langsung pada penagihan. Biaya sama dengan harga satuan—berdasarkan resolusi—dikalikan durasi dalam detik. Tinjau harga model sebelum memanggil API.

Durasi video dalam detik.

  • wan2.6-r2v-flash: Bilangan bulat antara 2 dan 10. Default adalah 5.

  • wan2.6-r2v: Bilangan bulat antara 2 dan 10. Default adalah 5.

Contoh: 5.

shot_type string (Opsional)

Jenis shot: shot kontinu tunggal atau beberapa shot yang berubah.

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

Nilai opsional:

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

  • multi: Menghasilkan video multi-kamera.

Contoh: single.

Catatan

Gunakan parameter ini untuk kontrol ketat atas struktur narasi video—misalnya, shot tunggal untuk pameran produk atau urutan multi-shot untuk cerita pendek.

audio boolean (opsional)

Penting

Parameter audio berdampak langsung pada penagihan. Harga bervariasi tergantung apakah video menyertakan audio. Sebelum memanggil API, tinjau harga model.

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

Apakah akan menghasilkan video dengan audio.

Nilai opsional:

  • true: Ini adalah nilai default, yang menghasilkan konten audio-video.

  • false: Menghasilkan video tanpa suara.

Contoh: true.

watermark boolean (Opsional)

Apakah akan menambahkan watermark ("AI Generated" di pojok kanan bawah).

  • false: Nilai default. Watermark tidak ditambahkan.

  • true: Menambahkan watermark.

Contoh: false.

seed integer (Opsional)

Seed bilangan acak. Harus berupa bilangan bulat antara 0 dan 2147483647.

Jika tidak disediakan, seed acak akan dihasilkan. Menggunakan seed tetap meningkatkan reproduktibilitas, meskipun hasilnya mungkin masih bervariasi karena keacakan model.

Contoh: 12345

Parameter respons

Respons sukses

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 untuk menyelesaikan masalah.

{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

output object

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

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: Pembuatan 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 tersebut, segera unduh dan simpan video ke layanan penyimpanan permanen, seperti Object Storage Service (OSS).

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

Parameter permintaan

Hasil tugas kueri

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

task_id string (Wajib)

ID Tugas yang akan dikueri.

Parameter respons

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 is happily watching a movie 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

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 dikirim. 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 output. Dihitung hanya untuk tugas 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. Penagihan didasarkan pada durasi ini.

Rumus: duration = input_video_duration + output_video_duration.

SR integer

Tingkat resolusi video yang dihasilkan. Contoh: 720.

sizestring

Resolusi video yang dihasilkan dalam format "lebar*tinggi". Contoh: 1280*720.

video_count integer

Jumlah video yang dihasilkan. Tetap bernilai 1.

request_id string

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

Batasan

  • Validitas data: task_id dan video_url video hanya disimpan selama 24 jam. Setelah kedaluwarsa, tidak dapat dikueri atau diunduh.

  • Moderasi konten: Baik prompt input maupun video output menjalani moderasi konten. Permintaan yang berisi konten tidak sesuai akan mengembalikan kesalahan `IPInfringementSuspect` atau `DataInspectionFailed`. Untuk detailnya, lihat Pesan kesalahan.

Kode kesalahan

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

FAQ

T: Bagaimana cara mendapatkan daftar putih nama domain untuk 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.