Skip to main content
Wan - legacy video models

Wan - reference-to-video (2.6)

Model reference-to-video Wan menerima input multimodal dan menghasilkan video interaksi karakter tunggal atau multi-karakter dengan menjadikan orang atau objek sebagai protagonis.

Lihat juga: Panduan pengguna

Ketersediaan

Model, URL endpoint, dan Kunci API harus berada di wilayah yang sama. Pemanggilan lintas wilayah akan gagal.
  • Pilih model: Konfirmasi wilayah model tersebut.
  • Pilih URL: Gunakan URL endpoint untuk wilayah yang sesuai. URL HTTP didukung.
  • Konfigurasikan Kunci API: Pilih wilayah dan Dapatkan Kunci API, lalu 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 yang ada tetap berfungsi penuh.

HTTP

Ini adalah API lawas yang hanya mendukung model wan2.6.
Tugas generasi video biasanya memerlukan waktu 1–5 menit. API menggunakan panggilan asinkron dua langkah: "buat tugas → polling hasil". Detailnya sebagai berikut:

Langkah 1: Buat tugas

  • Singapura
  • AS (Virginia)
  • Frankfurt
  • China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesisGanti {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 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 enable.
Jika header permintaan ini tidak ada, kesalahan "current user api does not support synchronous calls" akan dikembalikan.
Body permintaan
model string (Wajib)Model yang digunakan. Lihat Harga model untuk model yang tersedia dan harganya.Contoh: wan2.6-r2v-flash.input object (Wajib)Parameter input seperti prompt.

Properti

prompt string (Wajib)Prompt teks yang menggambarkan elemen dan karakteristik visual yang diinginkan dari video yang dihasilkan.Mendukung bahasa Tiongkok dan Inggris. Setiap karakter dihitung sebagai satu. Konten yang melebihi batas akan dipotong secara otomatis.
  • wan2.6-r2v-flash: Panjang maksimum: 1.500 karakter.
  • wan2.6-r2v: Panjang maksimum: 1.500 karakter.
Referensi karakter: Gunakan pengenal seperti "character1, character2" untuk merujuk karakter referensi. Setiap referensi (video atau gambar) harus hanya berisi satu karakter. Model mengidentifikasi karakter dalam referensi hanya melalui pengenal ini.Contoh: character1 dengan senang hati menonton film di sofa.Untuk tips menulis prompt, lihat Panduan prompt text-to-video/image-to-video.negative_prompt string (Opsional)Prompt negatif yang menggambarkan elemen yang tidak diinginkan dalam video.Mendukung bahasa Tiongkok dan Inggris. Panjang maksimum: 500 karakter. Konten yang melebihi batas akan dipotong secara otomatis.Contoh: resolusi rendah, error, kualitas terburuk, kualitas rendah, tidak lengkap, jari ekstra, proporsi buruk, dll.reference_urls array[string] (Wajib)
reference_urls berdampak langsung pada penagihan. Untuk detail harga, lihat Penagihan dan Pembatasan laju.
Array URL file referensi. Mendukung input video dan gambar. Digunakan untuk mengekstraksi penampilan karakter dan suara (jika tersedia) guna menghasilkan video yang sesuai dengan karakteristik referensi.
  • Setiap URL dapat menunjuk ke satu gambar atau satu video:
    • Gambar: 0–5.
    • Video: 0–3.
    • Total: gambar + video ≤ 5.
  • Saat meneruskan beberapa file referensi, urutan array menentukan urutan karakter. URL pertama dipetakan ke character1, yang kedua ke character2, dan seterusnya.
  • Setiap file referensi harus hanya berisi satu subjek karakter. Misalnya, character1 adalah seorang gadis, dan character2 adalah jam alarm.
Format yang didukung:
  1. URL publik:
Persyaratan video:
  • Format: MP4, MOV.
  • Durasi: 1–30 detik.
  • Ukuran file: hingga 100 MB.
Persyaratan gambar:
  • Format: JPEG, JPG, PNG (tanpa transparansi), BMP, WEBP.
  • Resolusi: lebar dan tinggi harus antara 240 hingga 8.000 piksel.
  • Ukuran file: hingga 20 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"].
reference_video_urls array[string]
Gunakan reference_urls sebagai ganti reference_video_urls.
Array URL video referensi. Digunakan untuk mengekstraksi penampilan karakter dan suara (jika tersedia) guna menghasilkan video yang sesuai dengan karakteristik referensi.
  • Hingga 3 video.
  • Saat meneruskan beberapa video, urutan array menentukan urutan karakter. URL pertama dipetakan ke character1, yang kedua ke character2, dan seterusnya.
  • Setiap video referensi harus hanya berisi satu karakter (misalnya, character1 adalah seorang gadis, dan character2 adalah jam alarm).
  • URL mendukung HTTP atau HTTPS.
Persyaratan untuk setiap video:
  • Format: MP4, MOV.
  • Durasi: 2–30 detik.
  • Ukuran file: hingga 100 MB.
Contoh: ["https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/xxx.mp4"].
parameters object (Opsional)Parameter generasi video seperti resolusi, penulisan ulang prompt, dan watermark.

Properti

size string (Opsional)
  • size berdampak langsung pada penagihan. Biaya = harga satuan (berdasarkan resolusi) x durasi (detik). Untuk model yang sama, 1080P > 720P. Periksa Harga model sebelum memanggil.
  • size harus berupa nilai eksak (seperti 1280*720), bukan rasio atau singkatan seperti 1:1 atau 720P.
Resolusi video yang dihasilkan, dalam format lebar*tinggi. Nilai default dan opsi yang tersedia bergantung pada parameter model:
  • wan2.6-r2v-flash: Default ke 1920*1080 (1080P). Mendukung semua resolusi 720P dan 1080P.
  • wan2.6-r2v: Default ke 1920*1080 (1080P). Mendukung semua resolusi 720P dan 1080P.
Resolusi 720P dan rasio aspeknya:
  • 1280*720: 16:9.
  • 720*1280: 9:16.
  • 960*960: 1:1.
  • 1088*832: 4:3.
  • 832*1088: 3:4.
Resolusi 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)
duration berdampak langsung pada penagihan. Biaya = harga satuan (berdasarkan resolusi) x durasi (detik). Periksa Harga model sebelum memanggil.
Durasi video yang dihasilkan, dalam satuan detik.
  • wan2.6-r2v-flash: Harus antara 2 dan 10. Default ke 5.
  • wan2.6-r2v: Harus antara 2 dan 10. Default ke 5.
Contoh: 5.shot_type string (Opsional)Komposisi shot video yang dihasilkan, menentukan apakah video terdiri dari satu shot berkelanjutan atau beberapa shot.Prioritas parameter: shot_type > prompt. Misalnya, jika shot_type diatur ke "single", model menghasilkan video single-shot meskipun prompt menyatakan "hasilkan video multi-shot".Nilai yang valid:
  • single: Video single-shot. Ini adalah default.
  • multi: Video multi-shot.
Contoh: single.
Gunakan parameter ini untuk mengontrol struktur naratif video, seperti single-shot untuk pameran produk atau multi-shot untuk klip cerita.
audio boolean (Opsional)
audio berdampak langsung pada penagihan. Video dengan dan tanpa audio memiliki harga berbeda. Periksa Harga model sebelum memanggil.
Model yang didukung: wan2.6-r2v-flash.Apakah akan menghasilkan audio dalam video.Nilai yang valid:
  • true (default)
  • false
Contoh: true.watermark boolean (Opsional)Apakah akan menambahkan watermark. Watermark muncul di pojok kanan bawah dengan teks "AI-generated".
  • false (default)
  • true
Contoh: false.seed integer (Opsional)Bilangan acak seed harus berupa integer 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.
  • Interaksi multi-karakter (gambar referensi dan video)
  • Interaksi multi-karakter (video referensi)
  • Karakter tunggal
  • Hasilkan video tanpa suara
Teruskan URL gambar dan video melalui reference_urls. Atur shot_type ke multi untuk video multi-shot.
# URL berikut ini untuk wilayah Singapura. Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda-beda tergantung wilayah.
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.6-r2v-flash",
    "input": {
        "prompt": "Character2 sits in a chair by the window, 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
    }
}'

Parameter respons

output objectOutput 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 stringPengenal 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 error
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: Ambil hasil tugas

  • Singapura
  • AS (Virginia)
  • Frankfurt
  • China (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: Generasi video memerlukan 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 dikembalikan. Unduh dan simpan video ke penyimpanan permanen, seperti OSS.
  • task_idmasa berlaku: 24 jam. Setelah periode ini, kueri 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.
  • Ambil hasil tugas
Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam, Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter respons

outputobjectOutput 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 encoding 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 penggunaan. Hanya menghitung hasil yang berhasil.

Properti

input_video_duration integerDurasi video referensi input, dalam satuan detik.output_video_duration integerDurasi video output, dalam satuan detik.duration floatTotal durasi video. Penagihan didasarkan pada nilai ini.Rumus: duration = input_video_duration + output_video_duration.SR integerTingkat resolusi video yang dihasilkan. Contoh: 720.size stringResolusi video yang dihasilkan dalam format lebar*tinggi. Contoh: 1280*720.video_count integerJumlah video yang dihasilkan. Selalu 1.
request_id stringPengenal permintaan unik untuk pelacakan dan troubleshooting.
  • Tugas berhasil
  • Tugas gagal
  • Tugas kedaluwarsa
URL video hanya berlaku selama 24 jam dan kemudian 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 happily watches 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
    }
}

DashScope SDK

Parameter SDK mengikuti konvensi penamaan yang sama dengan API HTTP, dengan wrapper khusus bahasa. Tugas reference-to-video biasanya memerlukan waktu 1–5 menit. SDK membungkus alur kerja asinkron HTTP dan mendukung panggilan sinkron maupun asinkron.
Waktu pemrosesan aktual bergantung pada antrian tugas dan beban server.

Python

Pastikan versi DashScope Python SDK Anda 1.25.16 atau lebih baru sebelum menjalankan kode berikut.Versi SDK yang usang dapat menyebabkan error seperti "url error, please check url!". Lihat Instal SDK untuk memperbarui.
Atur base_http_api_url berdasarkan wilayah model:
  • Singapura
  • China (Beijing)
  • Frankfurt
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
  • Sinkron
  • Asinkron
Panggilan sinkron memblokir hingga generasi video selesai dan hasil dikembalikan.
Contoh permintaan
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# URL wilayah Singapura. Gunakan URL untuk wilayah Anda.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# Jika DASHSCOPE_API_KEY tidak diatur, ganti baris berikut dengan: api_key="sk-xxx"
# Kunci API bersifat spesifik wilayah. Dapatkan Kunci API Anda: 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: memblokir hingga hasil siap
    print('please wait...')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model='wan2.6-r2v-flash',
        prompt='Character2 sits in a chair by the window, 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"
        ],
        shot_type='multi',
        audio=True,
        size='1280*720',
        duration=10,
        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()

Java

Pastikan versi DashScope Java SDK Anda 2.22.14 atau lebih baru sebelum menjalankan kode berikut.Versi SDK yang usang dapat menyebabkan error seperti "url error, please check url!". Lihat Instal SDK untuk memperbarui.
Atur baseHttpApiUrl berdasarkan wilayah model:
  • Singapura
  • China (Beijing)
  • Frankfurt
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
  • Sinkron
  • Asinkron
Panggilan sinkron memblokir hingga generasi video selesai dan hasil dikembalikan.
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.List;

public class Ref2Video26 {

    static {
        // URL wilayah Singapura. Gunakan URL untuk wilayah Anda.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // Jika DASHSCOPE_API_KEY tidak diatur, ganti baris berikut dengan: apiKey="sk-xxx"
    // Kunci API bersifat spesifik wilayah. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void ref2video26() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        List<String> referenceUrls = new ArrayList<>();
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/aacgyk/wan-r2v-role1.mp4");
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/20260205/mmizqq/wan-r2v-role2.mp4");
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png");
        referenceUrls.add("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png");

        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wan2.6-r2v-flash")
                        .prompt("Character2 sits in a chair by the window, holding character3, playing a soothing American country folk song next to character4. Character1 says to Character2: “that sounds great”")
                        .referenceUrls(referenceUrls)
                        .shotType(VideoSynthesis.ShotType.MULTI)
                        .audio(Boolean.TRUE)
                        .size("1280*720")
                        .duration(10)
                        .watermark(Boolean.TRUE)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

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

Kode kesalahan

Jika pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk solusinya.
Pembuatan Gambar
  • FAQ
Model Dunia
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production