Wan3.0 - Referensi API Generasi Video - Alibaba Cloud Model Studio

Prasyarat

Untuk memastikan panggilan API berhasil, pastikan bahwa model, URL Endpoint, dan Kunci API semuanya berada di wilayah yang sama. Panggilan lintas-wilayah akan gagal.

Select a model: Buka Model Gallery untuk memilih model dan konfirmasi wilayah tempat model tersebut berada.
Select a URL: Pilih URL Endpoint sesuai wilayah yang bersangkutan.
Configure API Key: Pilih wilayah dan Obtain an API key, lalu Configure API key as an environment variable.

Kode contoh dalam topik ini berlaku untuk wilayah Singapura.

Panggilan HTTP

Karena tugas generasi video memerlukan waktu relatif lama (biasanya 1–5 menit), API menggunakan panggilan asinkron. Seluruh proses terdiri dari dua langkah inti: "Create a task → Poll for results", seperti dijelaskan di bawah ini:

Langkah 1: Buat tugas dan peroleh ID tugas

Singapura
Beijing
AS (Virginia)
Tiongkok (Hong Kong)

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

Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk menanyakan hasilnya. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.
Untuk panduan pemula, lihat Call APIs with Postman or cURL.

Parameter permintaan

Header permintaan (Headers)

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.

Isi permintaan (Request Body)

model string (Wajib)Nama model. Nilai tetap: wan3.0-video.input object (Wajib)Informasi input dasar. Salah satu dari prompt atau media harus disediakan.

Properti

prompt string (Wajib kondisional)Prompt teks yang digunakan untuk menggambarkan konten video yang diinginkan. Salah satu dari ini atau media harus disediakan.Mendukung bahasa Tionghoa dan Inggris. Setiap karakter Tionghoa atau huruf dihitung sebagai satu karakter, dengan batas maksimum 20.000 karakter. Konten yang melebihi batas ini akan dipotong secara otomatis.Dalam mode referensi, Anda dapat menggunakan "Gambar 1", "Video 1", dll. dalam prompt untuk merujuk ke aset media sesuai urutan dalam array media.media array (Wajib kondisional)Array aset media yang mendukung gambar, video, audio, file, dan halaman web sebagai input. Salah satu dari ini atau prompt harus disediakan.

Setiap elemen dalam array adalah objek media yang berisi bidang type dan url.
Dalam mode generasi video berbasis referensi, urutan array menentukan urutan referensi aset dalam prompt. Gambar dan video dihitung secara terpisah, artinya Gambar 1 dan Video 1 dapat eksis bersamaan.
- reference_video ke-1 dalam array bersesuaian dengan Video 1, yang ke-2 bersesuaian dengan Video 2, dan seterusnya.
- reference_image ke-1 dalam array bersesuaian dengan Gambar 1, yang ke-2 bersesuaian dengan Gambar 2, dan seterusnya.
- reference_audio ke-1 dalam array bersesuaian dengan Audio 1, yang ke-2 bersesuaian dengan Audio 2, dan seterusnya.

Properti

type string (Wajib)Jenis aset media. Nilai valid:

first_frame: Gambar frame pertama. Maksimal 1 gambar, digunakan secara ketat sebagai frame pertama video.
last_frame: Gambar frame terakhir. Maksimal 1 gambar, digunakan secara ketat sebagai frame terakhir video.
reference_image: Gambar referensi. Maksimal 10 gambar.
reference_video: Video referensi. Maksimal 5 klip, dengan total durasi tidak lebih dari 15 detik.
reference_audio: Audio referensi. Maksimal 5 klip, dengan total durasi tidak lebih dari 15 detik.
file: File. Maksimal 1 file, tidak dapat digunakan bersamaan dengan link.
link: Tautan web. Maksimal 1 tautan, tidak dapat digunakan bersamaan dengan file.

Tipe reference_xx/file/link dan tipe first_frame/last_frame saling eksklusif dan tidak dapat digunakan bersamaan dalam satu permintaan.

url string (Wajib)URL aset media atau data yang dikodekan Base64.

Gambar input (type=first_frame / last_frame / reference_image)

URL gambar atau data yang dikodekan Base64.Batasan gambar:

Format: JPEG, JPG, PNG (saluran transparan tidak didukung), BMP, WEBP.
Resolusi: [240, 8000] piksel per sisi.
Rasio aspek: tidak lebih dari 8:1.
Ukuran file: tidak lebih dari 20 MB.

Format input yang didukung:

URL publik:
- Mendukung protokol HTTP atau HTTPS.
- Contoh: https://xxx/xxx.png.
String gambar yang dikodekan Base64:
- Format data: data:{MIME_type};base64,{base64_data}.
- Contoh: data:image/png;base64,GDU7MtCZzEbTbmRZ...... (string terkode terlalu panjang, hanya fragmen yang ditampilkan)
- Untuk detailnya, lihat Input Image.

Video input (type=reference_video)

URL video referensi.Batasan video:

Format: mp4, mov.
Durasi: [1, 15] detik per klip, dengan total durasi tidak lebih dari 15 detik.
Frame rate: ≥16 fps.
Resolusi: [240, 4096] piksel per sisi.
Rasio aspek: tidak lebih dari 8:1.
Ukuran file per klip: tidak lebih dari 100 MB.

Format input yang didukung:

URL publik:
- Mendukung protokol HTTP atau HTTPS.
- Contoh: https://xxx/xxx.mp4.

Audio input (type=reference_audio)

URL audio referensi.Batasan audio:

Format: wav, mp3.
Durasi: [1, 15] detik per klip, dengan total durasi tidak lebih dari 15 detik.
Ukuran file: tidak lebih dari 15 MB.

Format input yang didukung:

URL publik:
- Mendukung protokol HTTP atau HTTPS.
- Contoh: https://xxx/xxx.mp3.

File input (type=file)

URL file.Batasan file:

Format: docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md.
Ukuran file: tidak lebih dari 100 MB.
Batas halaman: tidak lebih dari 50 halaman (divalidasi untuk format pdf, docx, doc, pptx, ppt, key, pages).

Format input yang didukung:

URL publik:
- Mendukung protokol HTTP atau HTTPS.
- Contoh: https://xxx/xxx.pdf.

Tautan web input (type=link)

URL halaman web publik. Hanya mendukung penguraian halaman web yang dapat diakses publik dan tidak memerlukan login (seperti berita, blog, akun publik, dll.).Format input yang didukung:

URL publik:
- Mendukung protokol HTTP atau HTTPS.
- Contoh: https://xxx/article/xxx.

parameters object (Opsional)Parameter pemrosesan video.

Properti

resolution string (Opsional)Tingkat resolusi video yang dihasilkan. Nilai default: 1080P. Nilai valid:

1080P
720P
480P

ratio string (Opsional)Rasio aspek video yang dihasilkan. Nilai valid:

adaptive (Nilai default): Rasio aspek adaptif yang secara otomatis merekomendasikan rasio aspek yang sesuai berdasarkan proporsi media input dan maksudnya.
21:9
16:9
4:3
1:1
3:4
9:16

duration integer (Opsional)Durasi video yang dihasilkan, dalam satuan detik. Nilai default: 5.

Tanpa input video: bilangan bulat dalam rentang [2, 30].
Dengan input video: total durasi video input + durasi video output tidak boleh melebihi 30 detik.
Jika diatur ke -1: Mode durasi cerdas, di mana model secara otomatis merekomendasikan durasi yang sesuai berdasarkan prompt input, konten, dan media kaya.

audio boolean (Opsional)Apakah video output berisi audio.

true: Nilai default, video output berisi audio.
false: Video output tidak berisi trek audio.

Mengaktifkan atau menonaktifkan audio tidak memengaruhi harga.seed integer (Opsional)Seed acak. Digunakan untuk mereproduksi hasil generasi. Rentang nilai: -1 atau [0, 2147483647]. Jika diatur ke -1 atau tidak ditentukan, sistem secara otomatis menghasilkan seed acak. Meskipun menggunakan seed yang sama, hasil generasi mungkin tidak selalu identik.prompt_extend boolean (Opsional)Apakah akan mengaktifkan penulisan ulang prompt cerdas. Saat diaktifkan, model bahasa besar akan menulis ulang prompt input. Ini secara signifikan meningkatkan kualitas generasi untuk prompt yang lebih pendek, tetapi meningkatkan latensi.

true: Nilai default, penulisan ulang cerdas diaktifkan.
false: Penulisan ulang cerdas dinonaktifkan.

Saat dokumen (file) atau halaman web (link) diberikan sebagai input, prompt_extend harus diatur ke true.

watermark boolean (Opsional)Apakah akan menambahkan Watermark.

false: Nilai default, tidak ada Watermark yang ditambahkan.
true: Watermark ditambahkan.

File Reference to Video
Reference-based Video Generation
Text-to-Video
First Frame to Video
First-Last Frame to Video

Masukkan file melalui tipe file, dan model secara otomatis memahami konten file tersebut 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": "wan3.0-video",
    "input": {
        "prompt": "Iklan produk kacamata pintar premium dengan gaya minimalis, futuristik, dan modis. Palet warna menampilkan nuansa hitam, abu-abu perak, dan biru es dengan aksen cahaya putih halus serta grafis UI parameter. Dimulai dengan latar belakang hitam pekat, sepasang kacamata pintar perlahan muncul dari kegelapan dengan sorotan halus pada ujung gagangnya. Kamera menangkap detail ultra-dekat lensa, bantalan hidung, engsel, gagang, dan tekstur material, menampilkan material logam dan komposit berkinerja-tinggi. Produk kemudian berputar perlahan di udara dengan grafis gerak minimalis yang menampilkan parameter inti. Lalu kamera menjauh saat semua bagian secara tepat menyatu kembali menjadi produk lengkap, beralih ke model muda yang memakainya dalam ruang minimalis dan lingkungan pencahayaan perkotaan.",
        "media": [
            {
                "type": "file",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260806/ebapmr/glass.pptx"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 10,
        "prompt_extend": true
    }
}'

Masukkan gambar referensi, video, audio, file, atau tautan web melalui input.media, dan model secara otomatis memahami maksudnya 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": "wan3.0-video",
    "input": {
        "prompt": "Video 1 memegang Gambar 3 dan memainkan lagu country folk yang menenangkan di kursi pada Gambar 4, berkata: '\''Cuaca cerah hari ini.'\'' Gambar 1 memegang Gambar 2, melewati Video 1, meletakkan Gambar 2 di atas meja di samping Video 1, dan berkata: '\''Kedengarannya indah, bisakah kamu menyanyikannya lagi?'\''",
        "media": [
            {
                "type": "reference_image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg"
            },
            {
                "type": "reference_video",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4"
            },
            {
                "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": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": true
    }
}'

Hasilkan video hanya menggunakan prompt, tanpa memasukkan file media apa pun.

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": "wan3.0-video",
    "input": {
        "prompt": "Seekor anak kucing berlari di atap gedung di bawah cahaya bulan, lampu neon kota berkedip di kejauhan, kualitas sinematik, gerakan kamera yang mulus."
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": true
    }
}'

Tentukan secara ketat gambar frame pertama video menggunakan first_frame.

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": "wan3.0-video",
    "input": {
        "prompt": "Adegan seni fantasi urban. Karakter seni grafiti dinamis. Remaja yang dilukis semprot hidup dari dinding beton. Ia nge-rap dengan kecepatan sangat tinggi sambil berpose klasik energetik ala rapper. Adegan berlatar di bawah jembatan kereta api pada malam hari dengan suasana urban. Pencahayaan berasal dari satu lampu jalan, menciptakan atmosfer sinematik penuh energi tinggi dan detail memukau. Audio video hanya terdiri dari rap, tanpa dialog atau kebisingan lainnya.",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": true
    }
}'

Masukkan first_frame dan last_frame untuk menentukan secara ketat gambar frame pertama dan terakhir 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": "wan3.0-video",
    "input": {
        "prompt": "Seorang gadis muda secara bertahap berubah dari tersenyum menjadi tertawa, kamera perlahan mendekat, pencahayaan latar berubah dari nada dingin ke hangat.",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            },
            {
                "type": "last_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260408/sjuytr/wan-r2v-object-girl.jpg"
            }
        ]
    },
    "parameters": {
        "resolution": "480P",
        "ratio": "adaptive",
        "duration": 5,
        "prompt_extend": 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 stringIdentifikasi permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Dikembalikan hanya untuk permintaan yang gagal. Lihat Error codes.message stringPesan kesalahan detail. Dikembalikan hanya untuk permintaan yang gagal. Lihat Error codes.

Respons berhasil
Respons kesalahan

Simpan task_id untuk menanyakan status dan hasil tugas.

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Langkah 2: Tanyakan hasil berdasarkan ID tugas

Singapura
Beijing
AS (Virginia)
Tiongkok (Hong Kong)

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

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 akan mengembalikan status tugas sebagai UNKNOWN.

Parameter permintaan

Header permintaan (Headers)

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

Parameter jalur URL (Path parameters)

task_id string (Wajib)ID tugas.

Tanyakan 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 workspace ID Anda yang sebenarnya.

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter respons

output objectInformasi 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.orig_prompt stringPrompt input asli.video_url stringURL video yang dihasilkan. Dikembalikan saat tugas berhasil.code stringKode kesalahan. Dikembalikan hanya untuk permintaan yang gagal. Lihat Error codes.message stringPesan kesalahan detail. Dikembalikan hanya untuk permintaan yang gagal. Lihat Error codes.

usage objectStatistik output. Hanya menghitung hasil yang berhasil.

Properti

video_count integerJumlah video yang dihasilkan. Tetap bernilai 1.duration floatTotal durasi video, dalam satuan detik. Jika tidak ada video referensi input, nilainya sama dengan durasi video output; jika ada video referensi input, nilainya sama dengan jumlah durasi video input dan durasi video output.input_video_duration floatDurasi video input, dalam satuan detik. Mengembalikan 0,0 jika tidak ada video yang diberikan sebagai input.output_video_duration floatDurasi video output, dalam satuan detik.fps integerLaju bingkai video yang dihasilkan. Nilai default: 30.SR integerResolusi video yang dihasilkan. Contoh: 720.ratio stringRasio aspek video yang dihasilkan. Contoh: 16:9.

request_id stringIdentifikasi permintaan unik untuk pelacakan dan troubleshooting.

Tugas berhasil
Tugas gagal
Kueri tugas kedaluwarsa

URL video hanya berlaku selama 24 jam dan kemudian secara otomatis dipurge. Segera simpan video yang dihasilkan.

{
    "request_id": "78c9b768-0285-996c-b682-xxxxxx",
    "output": {
        "task_id": "17ed7e50-00cf-4509-aea1-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-08-06 10:01:35.452",
        "scheduled_time": "2026-08-06 10:01:35.507",
        "end_time": "2026-08-06 10:13:33.838",
        "orig_prompt": "Seekor golden retriever berlari di pantai yang cerah, ombak menghantam di latar belakang, pencahayaan sinematik",
        "video_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/video.mp4"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "input_video_duration": 0.0,
        "output_video_duration": 5.0,
        "fps": 30,
        "SR": 720,
        "ratio": "16:9"
    }
}

Saat tugas gagal, task_status bernilai FAILED dengan kode dan pesan kesalahan. Lihat Error codes.

{
    "request_id": "e5e57877-c0fc-47ed-8fad-xxxxxx",
    "output": {
        "task_id": "eff1443c-ccab-4676-aad3-xxxxxx",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The two modes are mutually exclusive. Do not pass reference_xx and first_frame/last_frame at the same time."
    }
}

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

​Prasyarat

​Panggilan HTTP

​Langkah 1: Buat tugas dan peroleh ID tugas

Parameter permintaan

Header permintaan (Headers)

Isi permintaan (Request Body)

Parameter respons

​Langkah 2: Tanyakan hasil berdasarkan ID tugas

Parameter permintaan

Header permintaan (Headers)

Parameter jalur URL (Path parameters)

Parameter respons

Prasyarat

Panggilan HTTP

Langkah 1: Buat tugas dan peroleh ID tugas

Langkah 2: Tanyakan hasil berdasarkan ID tugas