Bagaimana cara memanggil API model pengeditan video terpadu (VACE) Wan? - Alibaba Cloud Model Studio

Topik ini menjelaskan parameter input dan output untuk model Wan-VACE. Model ini mendukung berbagai modalitas input, seperti teks, gambar, dan video, serta dapat melakukan berbagai tugas pembuatan dan pengeditan video.

Tautan cepat: Coba secara online di website resmi Wan

Catatan

Fitur-fitur di website resmi mungkin berbeda dari kemampuan yang didukung oleh API. Kemampuan API dijelaskan secara rinci dalam topik ini. Topik ini diperbarui segera setelah fitur baru dirilis.

Ikhtisar model

Wilayah Singapura

Model	Harga satuan	Batas laju (dibagi bersama oleh Akun Alibaba Cloud dan Pengguna RAM)		Kuota gratis (Lihat)
		Batas RPS untuk API pengiriman task	Jumlah Tugas Konkuren
wan2.1-vace-plus	$0,1/detik	2	2	50 detik

Wilayah China (Beijing)

Penting

Wilayah China (Beijing) tidak menyediakan kuota gratis. Semua panggilan di wilayah ini dikenakan biaya. Harap konfirmasi sebelum melanjutkan.

Model	Harga satuan	Batas laju (dibagi bersama oleh Akun Alibaba Cloud dan Pengguna RAM)
		Batas RPS untuk API pengiriman task	Jumlah task konkuren
wanx2.1-vace-plus	$0,100347/detik	2	2

Klik untuk melihat contoh penagihan

Penagihan dimulai setelah kuota gratis habis. Rumus penagihan adalah: Total biaya = Harga satuan × Durasi video (detik).

Asumsikan Anda membuat satu video menggunakan model wan2.1-vace-plus di wilayah Singapura.
Perhitungan biaya: $0,10/detik × 5 detik = $0,50.

Contoh performa

Fitur	Gambar referensi input	Prompt masukan	Video output
Referensi multi-gambar	Gambar referensi 1 (entitas referensi) Gambar referensi 2 (latar belakang referensi)	Dalam video tersebut, seorang gadis berjalan anggun keluar dari hutan kuno yang berkabut. Langkahnya ringan, dan kamera menangkap setiap gerakannya yang gesit. Saat gadis itu berhenti dan memandang sekeliling ke hutan yang rimbun, senyum penuh kejutan dan sukacita merekah di wajahnya. Adegan ini, yang membeku dalam momen interaksi antara cahaya dan bayangan, merekam pertemuannya yang indah dengan alam.	Video output
Repainting video		Video tersebut menampilkan sebuah mobil hitam bergaya steampunk yang dikemudikan oleh seorang pria. Mobil tersebut dihiasi roda gigi dan pipa tembaga. Latar belakangnya menampilkan pabrik permen bertenaga uap dan elemen retro, menciptakan suasana vintage yang menyenangkan.
Pengeditan lokal	Video input Gambar mask (Area putih menunjukkan area pengeditan)	Video tersebut menampilkan kafe Prancis bergaya Paris, tempat seekor singa berjas dengan elegan menyesap kopi. Ia memegang cangkir kopi dengan satu tangan, menyesapnya dengan lembut sambil menunjukkan ekspresi santai. Kafenya didekorasi dengan selera tinggi, dengan warna-warna lembut dan pencahayaan hangat yang menerangi area tempat singa tersebut berada.	Konten di area pengeditan dimodifikasi berdasarkan prompt.
Ekstensi video	Klip pertama input (1 detik)	Anjing yang mengenakan kacamata hitam sedang berseluncur di jalan dengan skateboard, kartun 3D.	Video ekstensi output (5 detik)
Video outpainting		Seorang wanita elegan sedang bersemangat memainkan biola, dengan orkestra simfoni lengkap di belakangnya.

Prasyarat

Anda harus mendapatkan Kunci API dan mengatur Kunci API sebagai Variabel lingkungan.

Penting

Wilayah Beijing dan Singapura memiliki Kunci API dan Titik akhir permintaan yang terpisah. Jangan gunakan secara bergantian. Panggilan lintas wilayah akan mengakibatkan kegagalan otentikasi atau kesalahan layanan.

HTTP

Pemrosesan model pembuatan video membutuhkan waktu yang relatif lama. Untuk menghindari timeout permintaan, panggilan HTTP hanya mendukung pengambilan hasil model secara asinkron. Anda perlu melakukan dua permintaan:

Buat task: Kirim permintaan untuk membuat task, yang akan mengembalikan ID task.
Kueri hasil menggunakan ID: Gunakan ID task untuk menanyakan status dan hasil task. Jika berhasil, URL video akan dikembalikan, yang berlaku selama 24 jam.

Catatan

Setelah Anda membuat task, task tersebut akan ditambahkan ke antrian. Selanjutnya, panggil antarmuka kueri untuk mendapatkan status dan hasil task berdasarkan ID task.

Model pengeditan video umum membutuhkan waktu lama untuk memproses task, biasanya 5 hingga 10 menit. Waktu pemrosesan aktual tergantung pada jumlah task dalam antrian dan status eksekusi layanan.

Langkah 1: Buat task dan dapatkan ID task

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

Jika model Anda berada di wilayah China (Beijing), Anda harus mengganti URL dengan https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis.

Parameter permintaan

Referensi multi-gambar

Kunci API untuk wilayah Singapura dan China (Beijing) berbeda. Untuk informasi lebih lanjut, lihat Mendapatkan Kunci API

URL berikut ini untuk wilayah Singapura. Jika Anda menggunakan model di wilayah China (Beijing), Anda harus mengganti 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' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.1-vace-plus",
    "input": {
        "function": "image_reference",
        "prompt": "In the video, a girl gracefully walks out from a misty, ancient forest. Her steps are light, and the camera captures her every nimble moment. When the girl stops and looks around at the lush woods, a smile of surprise and joy blossoms on her face. This scene, frozen in a moment of interplay between light and shadow, records her wonderful encounter with nature.",
        "ref_images_url": [
            "http://wanx.alicdn.com/material/20250318/image_reference_2_5_16.png",
            "http://wanx.alicdn.com/material/20250318/image_reference_1_5_16.png"
        ]
    },
    "parameters": {
        "prompt_extend": true,
        "obj_or_bg": ["obj","bg"],
        "size": "1280*720"
    }
}'

Repainting video

Kunci API untuk wilayah Singapura dan China (Beijing) berbeda. Untuk informasi lebih lanjut, lihat Mendapatkan Kunci API

URL berikut ini untuk wilayah Singapura. Jika Anda menggunakan model di wilayah China (Beijing), Anda harus mengganti 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' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.1-vace-plus",
    "input": {
        "function": "video_repainting",
        "prompt": "The video shows a black steampunk-style car driven by a gentleman. The car is decorated with gears and copper pipes. The background features a steam-powered candy factory and retro elements, creating a vintage and playful scene.",
        "video_url": "http://wanx.alicdn.com/material/20250318/video_repainting_1.mp4"
    },
    "parameters": {
        "prompt_extend": false,
        "control_condition": "depth"
    }
}'

Pengeditan lokal

Kunci API untuk wilayah Singapura dan China (Beijing) berbeda. Untuk informasi lebih lanjut, lihat Mendapatkan Kunci API

URL berikut ini untuk wilayah Singapura. Jika Anda menggunakan model di wilayah China (Beijing), Anda harus mengganti 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' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.1-vace-plus",
    "input": {
        "function": "video_edit",
        "prompt": "The video shows a Parisian-style French cafe where a lion in a suit is elegantly sipping coffee. It holds a coffee cup in one hand, taking a gentle sip with a relaxed expression. The cafe is tastefully decorated, with soft hues and warm lighting illuminating the area where the lion is.",
        "mask_image_url": "http://wanx.alicdn.com/material/20250318/video_edit_1_mask.png",
        "video_url": "http://wanx.alicdn.com/material/20250318/video_edit_2.mp4",
        "mask_frame_id": 1
    },
    "parameters": {
        "prompt_extend": false,
        "mask_type": "tracking",
        "expand_ratio": 0.05
    }
}'

Ekstensi video

Kunci API untuk wilayah Singapura dan Beijing berbeda. Untuk informasi lebih lanjut, lihat Persiapan: Mendapatkan dan mengonfigurasi Kunci API

URL berikut ini untuk wilayah Singapura. Jika Anda menggunakan model di wilayah China (Beijing), Anda harus mengganti 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' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.1-vace-plus",
    "input": {
        "function": "video_extension",
        "prompt": "A dog wearing sunglasses is skateboarding on the street, 3D cartoon.",
        "first_clip_url": "http://wanx.alicdn.com/material/20250318/video_extension_1.mp4"
    },
    "parameters": {
        "prompt_extend": false
    }
}'

Outpainting video

Kunci API untuk wilayah Singapura dan China (Beijing) berbeda. Untuk informasi lebih lanjut, lihat Mendapatkan Kunci API

URL berikut ini untuk wilayah Singapura. Jika Anda menggunakan model di wilayah China (Beijing), Anda harus mengganti 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' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "wan2.1-vace-plus",
    "input": {
        "function": "video_outpainting",
        "prompt": "An elegant lady is passionately playing the violin, with a full symphony orchestra behind her.",
        "video_url": "http://wanx.alicdn.com/material/20250318/video_outpainting_1.mp4"
    },
    "parameters": {
        "prompt_extend": false,
        "top_scale": 1.5,
        "bottom_scale": 1.5,
        "left_scale": 1.5,
        "right_scale": 1.5
    }
}'

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

Referensi multi-gambar

model string (Wajib)

Nama model. Contoh: wan2.1-vace-plus.

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

Prompt yang menggambarkan elemen dan karakteristik visual yang diinginkan dalam video yang dihasilkan.

Prompt dapat dalam bahasa Mandarin atau Inggris dan tidak boleh melebihi 800 karakter. Setiap karakter Mandarin atau huruf dihitung sebagai satu karakter. Karakter berlebih akan dipotong secara otomatis.

Untuk informasi lebih lanjut tentang teknik prompt, lihat Panduan prompt pembuatan video.

function string (Wajib)

Nama fitur. Untuk referensi multi-gambar, atur nilai ini ke image_reference.

Fitur referensi multi-gambar mendukung hingga tiga gambar referensi, yang dapat berisi entitas dan latar belakang, seperti orang, hewan, pakaian, dan pemandangan. Anda dapat menggunakan parameter prompt untuk menggambarkan konten video yang diinginkan. Model kemudian menggabungkan gambar-gambar ini untuk menghasilkan video yang koheren.

ref_images_url array[string] (Wajib)

Array URL untuk gambar referensi input.

URL harus dapat diakses melalui Internet dan mendukung protokol HTTP atau HTTPS.

Anda dapat memberikan 1 hingga 3 gambar referensi. Jika Anda memberikan lebih dari 3 gambar, hanya 3 gambar pertama yang digunakan sebagai input.

Persyaratan gambar:

Format gambar: JPG, JPEG, PNG, BMP, TIFF, atau WEBP.
Resolusi gambar: Lebar dan tinggi harus antara 360 hingga 2.000 piksel.
Ukuran gambar: Tidak boleh melebihi 10 MB.
URL tidak boleh mengandung karakter Mandarin.

Saran:

Jika Anda menggunakan entitas dari gambar referensi, kami menyarankan agar setiap gambar hanya berisi satu entitas. Latar belakang harus berwarna solid, seperti putih atau warna tunggal, untuk lebih menonjolkan entitas.
Jika Anda menggunakan latar belakang dari gambar referensi, Anda dapat menggunakan maksimal satu gambar latar belakang, dan gambar tersebut tidak boleh mengandung objek entitas apa pun.

parameters object (Opsional)

Parameter pemrosesan video, seperti pengaturan watermark.

Properti

obj_or_bg array[string] (Opsional)

Parameter ini adalah array yang berkorespondensi satu-ke-satu dengan parameter ref_images_url. Setiap elemen dalam array ini menentukan tujuan gambar yang sesuai, apakah itu "entitas" atau "latar belakang":

obj: Gambar yang berfungsi sebagai referensi entitas.
bg: Gambar yang digunakan sebagai referensi latar belakang. Maksimal satu referensi latar belakang diperbolehkan.

Instruksi:

Kami menyarankan Anda menyediakan parameter ini, yang harus memiliki panjang yang sama dengan ref_images_url. Jika tidak, kesalahan akan dikembalikan.
Anda dapat mengabaikan parameter ini hanya ketika ref_images_url adalah array dengan satu elemen, dalam hal ini nilai default-nya adalah ["obj"].

Contoh: ["obj", "obj", "bg"].

size string (Opsional)

Resolusi video yang dihasilkan (lebar*tinggi). Model saat ini mendukung pembuatan video 720P. Nilai yang valid:

1280*720 (default): Rasio aspek 16:9, dengan lebar 1280 piksel dan tinggi 720 piksel.
720*1280: Rasio aspek 9:16.
960*960: Rasio aspek 1:1.
832*1088: Rasio aspek 3:4.
1088*832: Rasio aspek 4:3.

duration integer (Opsional)

Durasi video yang dihasilkan dalam detik. Parameter ini tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

Menentukan apakah akan mengaktifkan penulisan ulang prompt. Jika diaktifkan, model bahasa besar (LLM) akan menulis ulang prompt input. Ini dapat secara signifikan meningkatkan kualitas video yang dihasilkan untuk prompt pendek tetapi meningkatkan waktu pemrosesan.

true (default)
false

seed integer (Opsional)

Seed acak mengontrol keacakan konten yang dihasilkan. Nilai parameter ini berkisar dari [0, 2147483647].

Jika Anda tidak memberikan seed, algoritma akan secara otomatis menghasilkan bilangan acak sebagai seed. Untuk memastikan bahwa konten yang dihasilkan relatif stabil, gunakan nilai seed yang sama untuk setiap permintaan.

watermark bool (Opsional)

Menentukan apakah akan menambahkan watermark. Watermark terletak di pojok kanan bawah video dan bertuliskan "AI-generated".

false (default)
true

Repainting video

model string (Wajib)

Nama model. Contoh: wan2.1-vace-plus.

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

Prompt yang menggambarkan elemen dan karakteristik visual yang diinginkan dalam video yang dihasilkan.

Untuk informasi lebih lanjut tentang teknik prompt, lihat Panduan prompt pembuatan video.

function string (Wajib)

Nama fitur. Untuk repainting video, atur nilai ke video_repainting.

Repainting video mengekstraksi pose dan gerakan entitas, komposisi dan kontur gerak, serta struktur garis seni dari video input. Model kemudian menggabungkan informasi ini dengan prompt teks untuk menghasilkan video baru dengan fitur dinamis yang sama. Anda juga dapat mengganti entitas dalam video asli dengan gambar referensi, misalnya, untuk mengubah penampilan karakter sambil mempertahankan gerakan aslinya.

video_url string (Wajib)

URL video input.

URL harus dapat diakses publik dan mendukung protokol HTTP atau HTTPS.

Persyaratan video:

Format video: MP4.
Laju frame video: 16 FPS atau lebih tinggi.
Ukuran video: Tidak boleh melebihi 50 MB.
Panjang video: Tidak boleh melebihi 5 detik. Jika melebihi, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Mandarin.

Resolusi video output:

Jika resolusi video input 720P atau lebih rendah, video output mempertahankan resolusi aslinya.
Jika resolusi video input lebih tinggi dari 720P, video akan diskalakan turun ke 720P atau lebih rendah sambil mempertahankan rasio aspek aslinya.

Durasi video output:

Video output memiliki durasi yang sama dengan video input, hingga maksimum 5 detik.
Contoh: Jika video input berdurasi 3 detik, output juga berdurasi 3 detik. Jika input berdurasi 6 detik, output adalah 5 detik pertama.

ref_images_url array[string] (Opsional)

Array URL untuk gambar referensi input. URL harus merupakan titik akhir yang dapat diakses publik dan mendukung protokol HTTP atau HTTPS.

Hanya mendukung 1 gambar referensi. Kami menyarankan gambar ini berupa gambar entitas yang digunakan untuk mengganti entitas dalam video input.

Persyaratan gambar:

Format gambar: JPG, JPEG, PNG, BMP, TIFF, atau WEBP.
Resolusi gambar: Lebar dan tinggi harus antara 360 hingga 2.000 piksel.
Ukuran gambar: Tidak boleh melebihi 10 MB.
URL tidak boleh mengandung karakter Mandarin.

Saran:

Jika Anda menggunakan entitas dari gambar referensi, kami menyarankan agar setiap gambar hanya berisi satu entitas. Latar belakang harus berwarna solid, seperti putih atau warna tunggal, untuk lebih menonjolkan entitas.

parameters object (Wajib)

Parameter pemrosesan video, seperti pengaturan watermark.

Properti

control_condition string (Wajib)

Menentukan metode untuk ekstraksi fitur video.

posebodyface: Mengekstraksi ekspresi wajah dan gerakan tubuh entitas dalam video input. Cocok untuk skenario yang memerlukan pelestarian detail wajah.
posebody: Mengekstraksi gerakan tubuh entitas dari video input, tidak termasuk ekspresi wajah. Gunakan ini untuk skenario di mana Anda hanya perlu mengontrol gerakan tubuh.
depth: Mengekstraksi komposisi dan kontur gerak dari video input.
scribble: Mengekstraksi struktur garis seni dari video input.

strength float (Opsional)

Menyesuaikan kekuatan kontrol yang diterapkan oleh metode ekstraksi fitur control_condition pada video yang dihasilkan.

Nilai default adalah 1.0. Rentang nilai adalah [0.0, 1.0].

Nilai yang lebih besar membuat video yang dihasilkan lebih mirip dengan gerakan dan komposisi video aslinya. Nilai yang lebih kecil memungkinkan lebih banyak kebebasan kreatif.

prompt_extend bool (Opsional)

Menentukan apakah akan mengaktifkan penulisan ulang prompt. Jika diaktifkan, LLM akan menulis ulang prompt input. Ini dapat secara signifikan meningkatkan kualitas video yang dihasilkan untuk prompt pendek tetapi meningkatkan waktu pemrosesan.

true (default)
false (disarankan)

Jika deskripsi teks tidak konsisten dengan konten video, model mungkin salah menafsirkan prompt. Untuk meningkatkan konsistensi dan akurasi generasi, nonaktifkan secara manual penulisan ulang prompt dan berikan deskripsi yang jelas dan spesifik dalam prompt.

seed integer (Opsional)

Seed acak mengontrol keacakan konten yang dihasilkan. Nilai parameter ini berkisar dari [0, 2147483647].

watermark bool (Opsional)

Menentukan apakah akan menambahkan watermark. Watermark terletak di pojok kanan bawah video dan bertuliskan "AI-generated".

false (default)
true

Pengeditan lokal

model string (Wajib)

Nama model. Contoh: wan2.1-vace-plus.

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

Prompt yang menggambarkan elemen dan karakteristik visual yang diinginkan dalam video yang dihasilkan.

Untuk informasi lebih lanjut tentang teknik prompt, lihat Panduan prompt pembuatan video.

function string (Wajib)

Nama fitur. Untuk pengeditan lokal, atur nilai ke video_edit.

Pengeditan lokal memungkinkan Anda menambah, memodifikasi, atau menghapus elemen di area tertentu dari video input. Anda juga dapat mengganti entitas atau latar belakang di area pengeditan untuk mencapai pengeditan video detail halus.

video_url string (Wajib)

URL video input.

URL harus dapat diakses publik dan mendukung protokol HTTP atau HTTPS.

Persyaratan video:

Format video: MP4.
Laju frame video: 16 FPS atau lebih tinggi.
Ukuran video: Tidak boleh melebihi 50 MB.
Panjang video: Tidak boleh melebihi 5 detik. Jika melebihi, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Mandarin.

Resolusi video output:

Jika resolusi video input 720P atau lebih rendah, video output mempertahankan resolusi aslinya.
Jika resolusi video input lebih tinggi dari 720P, video akan diskalakan turun ke 720P atau lebih rendah sambil mempertahankan rasio aspek aslinya.

Durasi video output:

Video output memiliki durasi yang sama dengan video input, hingga maksimum 5 detik.
Contoh: Jika video input berdurasi 3 detik, output juga berdurasi 3 detik. Jika input berdurasi 6 detik, output adalah 5 detik pertama.

ref_images_url array[string] (Opsional)

Array URL untuk gambar referensi input.

URL harus merupakan titik akhir yang dapat diakses melalui Internet dan mendukung protokol HTTP atau HTTPS.

Saat ini, hanya mendukung 1 gambar referensi. Gambar ini dapat digunakan sebagai entitas atau latar belakang untuk mengganti konten yang sesuai dalam video input.

Persyaratan gambar:

Format gambar: JPG, JPEG, PNG, BMP, TIFF, atau WEBP.
Resolusi gambar: Lebar dan tinggi harus antara 360 hingga 2.000 piksel.
Ukuran gambar: Tidak boleh melebihi 10 MB.
URL tidak boleh mengandung karakter Mandarin.

Saran:

Jika Anda menggunakan entitas dari gambar referensi, kami menyarankan agar setiap gambar hanya berisi satu entitas. Latar belakang harus berwarna solid, seperti putih atau warna tunggal, untuk lebih menonjolkan entitas.
Jika Anda menggunakan latar belakang dari gambar referensi, gambar latar belakang tersebut tidak boleh mengandung objek entitas apa pun.

mask_image_url string (Opsional)

URL gambar mask. URL harus berupa URL publik dan mendukung protokol HTTP atau HTTPS.

Parameter ini menentukan area pengeditan video. Anda harus menentukan salah satu parameter ini atau parameter mask_video_url. Kami merekomendasikan parameter ini.

Area putih pada gambar mask (dengan nilai piksel [255, 255, 255]) menunjukkan bagian yang akan diedit. Area hitam (dengan nilai piksel [0, 0, 0]) menunjukkan area yang akan dipertahankan.

Persyaratan gambar:

Format gambar: JPG, JPEG, PNG, BMP, TIFF, atau WEBP.
Resolusi gambar harus sama dengan resolusi video input (video_url).
Ukuran gambar: Tidak boleh melebihi 10 MB.
URL tidak boleh mengandung karakter Mandarin.

mask_frame_id integer (Opsional)

Parameter ini hanya digunakan ketika mask_image_url tidak kosong. Parameter ini menentukan ID frame dari frame video tempat objek yang dimask muncul.

Nilai default adalah 1, yang menunjukkan frame pertama video.

Nilai harus berada dalam rentang [1, max_frame_id], di mana max_frame_id = laju frame video input × durasi video input + 1.

Contoh, untuk video input (video_url) dengan laju frame 16 FPS dan durasi 5 detik, jumlah total frame adalah 81 (16 × 5 + 1). Oleh karena itu, nilai max_frame_id adalah 81.

mask_video_url string (Opsional)

URL video mask. URL ini harus merupakan titik akhir yang dapat diakses melalui Internet dan mendukung protokol HTTP atau HTTPS.

Parameter ini menentukan area video yang akan diedit. Anda harus menentukan salah satu parameter ini atau parameter mask_image_url.

Video mask harus memiliki format, laju frame, resolusi, dan panjang yang sama dengan video input (video_url).

Area putih pada video mask (dengan nilai piksel [255, 255, 255]) menunjukkan bagian yang akan diedit. Area hitam (dengan nilai piksel [0, 0, 0]) menunjukkan area yang akan dipertahankan.

parameters object (Opsional)

Parameter pemrosesan video, seperti pengaturan watermark.

Properti

control_condition string (Opsional)

Menentukan metode untuk ekstraksi fitur video. Nilai default adalah "", yang berarti tidak ada ekstraksi yang dilakukan.

posebodyface: Mengekstraksi ekspresi wajah dan gerakan tubuh dari entitas dalam video input. Fitur ini cocok untuk skenario di mana wajah entitas menonjol dalam frame dan memiliki fitur yang jelas.
depth: Mengekstraksi kontur struktural dan gerak dari video input.

mask_type string (Opsional)

Parameter ini hanya berlaku ketika mask_image_url tidak kosong. Parameter ini menentukan perilaku area pengeditan.

tracking (default): Area pengeditan secara dinamis mengikuti lintasan objek target. Mode ini cocok untuk adegan dengan objek bergerak.
fixed: Area pengeditan tetap, terlepas dari konten video.

expand_ratio float (Opsional)

Ketika mask_type diatur ke tracking, parameter ini menentukan rasio ekspansi area mask.

Rentang nilai adalah [0.0, 1.0]. Nilai default adalah 0.05. Kami menyarankan menggunakan nilai default.

Nilai yang lebih kecil membuat area mask lebih pas mengikuti objek target. Nilai yang lebih besar memperluas area mask lebih luas.

expand_mode string (Opsional)

Parameter ini menentukan bentuk area mask ketika mask_type diatur ke tracking.

Algoritma menghasilkan video mask yang bentuknya didasarkan pada gambar mask input dan expand_mode yang dipilih. Nilai yang didukung:

hull (default): Mode poligon. Poligon membungkus objek yang dimask.
bbox: Mode kotak pembatas, yang menggunakan persegi panjang untuk membungkus objek yang dimask.
original: Mode mentah. Mempertahankan bentuk objek yang dimask sebanyak mungkin.

size string (Opsional)

Resolusi video yang dihasilkan (lebar*tinggi). Model saat ini mendukung pembuatan video 720P. Nilai yang valid:

1280*720 (default): Rasio aspek 16:9, dengan lebar 1280 piksel dan tinggi 720 piksel.
720*1280: Rasio aspek 9:16.
960*960: Rasio aspek 1:1.
832*1088: Rasio aspek 3:4.
1088*832: Rasio aspek 4:3.

duration integer (Opsional)

Durasi video yang dihasilkan dalam detik. Parameter ini tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

true (default)
false (disarankan)

Jika deskripsi teks tidak konsisten dengan konten video, model mungkin salah menafsirkan prompt. Untuk meningkatkan konsistensi dan akurasi generasi, nonaktifkan secara manual penulisan ulang prompt dan berikan deskripsi yang jelas dan spesifik dalam prompt.

seed integer (Opsional)

Seed acak mengontrol keacakan konten yang dihasilkan. Nilai parameter ini berkisar dari [0, 2147483647].

watermark bool (Opsional)

Menentukan apakah akan menambahkan watermark. Watermark terletak di pojok kanan bawah video dan bertuliskan "AI-generated".

false (default)
true

Ekstensi video

model string (Wajib)

Nama model. Contoh: wan2.1-vace-plus.

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

Prompt yang menggambarkan elemen dan karakteristik visual yang diinginkan dalam video yang dihasilkan.

Untuk informasi lebih lanjut tentang teknik prompt, lihat Panduan prompt pembuatan video.

function string (Wajib)

Nama fitur. Untuk ekstensi video, nilainya adalah video_extension.

Ekstensi video mendukung pembuatan konten berkelanjutan berdasarkan gambar atau video. Fitur ini juga mendukung ekstraksi fitur dinamis, seperti gerakan dan komposisi, dari video referensi untuk memandu pembuatan video dengan performa gerak yang serupa.

Durasi total video yang diekstensi adalah 5 detik. Catatan: Ini adalah durasi total video output akhir, bukan tambahan ekstensi 5 detik ke video asli.

first_frame_url string (Opsional)

URL gambar frame pertama.

URL harus merupakan titik akhir publik yang mendukung protokol HTTP atau HTTPS.

Persyaratan gambar:

Format gambar: JPG, JPEG, PNG, BMP, TIFF, atau WEBP.
Resolusi gambar: Lebar dan tinggi harus antara 360 hingga 2.000 piksel.
Ukuran gambar: Tidak boleh melebihi 10 MB.
URL tidak boleh mengandung karakter Mandarin.

last_frame_url string(Opsional)

URL gambar frame terakhir. URL harus dapat diakses melalui Internet dan mendukung protokol HTTP atau HTTPS.

Persyaratan gambar:

Format gambar: JPG, JPEG, PNG, BMP, TIFF, atau WEBP.
Resolusi gambar: Lebar dan tinggi harus antara 360 hingga 2.000 piksel.
Ukuran gambar: Tidak boleh melebihi 10 MB.
URL tidak boleh mengandung karakter Mandarin.

first_clip_url string (Opsional)

URL segmen video pertama. URL harus merupakan titik akhir yang dapat diakses publik dan mendukung protokol HTTP atau HTTPS.

Persyaratan video:

Format video: MP4.
Laju frame video harus 16 FPS atau lebih tinggi. Jika Anda menggunakan first_clip_url dan last_clip_url bersamaan, kami menyarankan kedua klip memiliki laju frame yang sama.
Ukuran video: Tidak boleh melebihi 50 MB.
Video tidak boleh lebih panjang dari 3 detik. Jika video melebihi batas ini, hanya 3 detik pertama yang digunakan. Jika first_clip_url dan last_clip_url keduanya ditentukan, durasi gabungannya tidak boleh melebihi 3 detik.
URL tidak boleh mengandung karakter Mandarin.

Resolusi video output:

Jika resolusi video input 720P atau lebih rendah, video output mempertahankan resolusi aslinya.
Jika resolusi video input lebih tinggi dari 720P, video akan diskalakan turun ke 720P atau lebih rendah sambil mempertahankan rasio aspek aslinya.

last_clip_url string(Opsional)

URL segmen video terakhir. URL harus dapat diakses melalui Internet dan mendukung protokol HTTP atau HTTPS.

Persyaratan video:

Format video: MP4.
Laju frame video: 16 FPS atau lebih tinggi. Saat menggunakan first_clip_url dan last_clip_url bersamaan, kami menyarankan kedua klip memiliki laju frame yang sama.
Ukuran video: Tidak boleh melebihi 50 MB.
Panjang video: Panjang maksimum video adalah 3 detik. Jika video lebih panjang dari 3 detik, hanya 3 detik pertama yang digunakan. Jika first_clip_url dan last_clip_url keduanya ditentukan, durasi gabungannya tidak boleh melebihi 3 detik.
URL tidak boleh mengandung karakter Mandarin.

Resolusi video output:

Jika resolusi video input 720P atau lebih rendah, video output mempertahankan resolusi aslinya.
Jika resolusi video input lebih tinggi dari 720P, video akan diskalakan turun ke 720P atau lebih rendah sambil mempertahankan rasio aspek aslinya.

video_url string (Opsional)

URL video. URL harus dapat diakses publik dan mendukung protokol HTTP atau HTTPS.

Video ini mengekstraksi fitur gerak dan menggunakan parameter first_frame_url, last_frame_url, first_clip_url, dan last_clip_url untuk menghasilkan video ekstensi dengan gerakan yang serupa.

Persyaratan video:

Format video: MP4.
Laju frame video: 16 FPS atau lebih tinggi, konsisten dengan klip sebelum dan sesudahnya.
Resolusi video: Konsisten dengan frame dan klip sebelum dan sesudahnya.
Ukuran video: Tidak boleh melebihi 50 MB.
Panjang video: Tidak boleh melebihi 5 detik. Jika melebihi, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Mandarin.

parameters object (Opsional)

Parameter pemrosesan video, seperti resolusi video output.

Properti

control_condition string (Opsional)

Menentukan metode untuk ekstraksi fitur video. Ini diperlukan ketika `video_url` disediakan. Nilai default adalah "", yang berarti tidak ada ekstraksi yang dilakukan.

posebodyface: Mengekstraksi ekspresi wajah dan gerakan tubuh entitas dari video input.
depth: Mengekstraksi komposisi dan kontur gerak dari video input.

duration integer (Opsional)

Durasi video yang dihasilkan dalam detik. Parameter ini tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

true (default)
false (disarankan)

Jika deskripsi teks tidak konsisten dengan konten video, model mungkin salah menafsirkan prompt. Untuk meningkatkan konsistensi dan akurasi generasi, nonaktifkan secara manual penulisan ulang prompt dan berikan deskripsi yang jelas dan spesifik dalam prompt.

seed integer (Opsional)

Seed acak mengontrol keacakan konten yang dihasilkan. Nilai parameter ini berkisar dari [0, 2147483647].

watermark bool (Opsional)

Menentukan apakah akan menambahkan watermark. Watermark terletak di pojok kanan bawah video dan bertuliskan "AI-generated".

false (default)
true

Outpainting video

model string (Wajib)

Nama model. Contoh: wan2.1-vace-plus.

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

Prompt yang menggambarkan elemen dan karakteristik visual yang diinginkan dalam video yang dihasilkan.

Untuk informasi lebih lanjut tentang teknik prompt, lihat Panduan prompt pembuatan video.

function string (Wajib)

Menentukan fitur yang akan digunakan. Untuk outpainting video, atur parameter ini ke video_outpainting.

Outpainting video mendukung penskalaan proporsional video ke arah atas, bawah, kiri, dan kanan.

video_url string (Wajib)

URL video input.

URL harus dapat diakses publik dan mendukung protokol HTTP atau HTTPS.

Persyaratan video:

Format video: MP4.
Laju frame video: 16 FPS atau lebih tinggi.
Ukuran video: Tidak boleh melebihi 50 MB.
Panjang video: Tidak boleh melebihi 5 detik. Jika melebihi, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Mandarin.

Resolusi video output:

Jika resolusi video input 720P atau lebih rendah, video output mempertahankan resolusi aslinya.
Jika resolusi video input lebih tinggi dari 720P, video akan diskalakan turun ke 720P atau lebih rendah sambil mempertahankan rasio aspek aslinya.

Durasi video output:

Video output memiliki durasi yang sama dengan video input, hingga maksimum 5 detik.
Contoh: Jika video input berdurasi 3 detik, output juga berdurasi 3 detik. Jika input berdurasi 6 detik, output adalah 5 detik pertama.

parameters object (Opsional)

Parameter pemrosesan video, seperti rasio penskalaan.

Properti

top_scale float (Opsional)

Memusatkan frame video dan menskalakan video ke atas secara proporsional.

Rentang nilai adalah [1.0, 2.0]. Nilai default adalah 1.0, yang berarti tidak ada penskalaan.

bottom_scale float (Opsional)

Memusatkan frame video dan menskalakan video ke bawah secara proporsional.

Rentang nilai adalah [1.0, 2.0]. Nilai default adalah 1.0, yang berarti tidak ada penskalaan.

left_scale float (Opsional)

Memusatkan frame video dan menskalakan video ke kiri secara proporsional.

Rentang nilai adalah [1.0, 2.0]. Nilai default adalah 1.0, yang berarti tidak ada penskalaan.

right_scale float (Opsional)

Memusatkan frame video dan menskalakan video ke kanan secara proporsional.

Rentang nilai adalah [1.0, 2.0]. Nilai default adalah 1.0, yang berarti tidak ada penskalaan.

duration integer (Opsional)

Durasi video yang dihasilkan dalam detik. Parameter ini tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

true (default)
false (disarankan)

Jika deskripsi teks tidak konsisten dengan konten video, model mungkin salah menafsirkan prompt. Untuk meningkatkan konsistensi dan akurasi generasi, nonaktifkan secara manual penulisan ulang prompt dan berikan deskripsi yang jelas dan spesifik dalam prompt.

seed integer (Opsional)

Seed acak mengontrol keacakan konten yang dihasilkan. Nilai parameter ini berkisar dari [0, 2147483647].

watermark bool (Opsional)

Menentukan apakah akan menambahkan watermark. Watermark terletak di pojok kanan bawah video dan bertuliskan "AI-generated".

false (default)
true

Parameter respons	Respons berhasil Simpan `task_id` untuk menanyakan status dan hasil task. `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }` Respons kesalahan Pembuatan task 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 task. Properti task_id `string` ID task. Dapat digunakan untuk menanyakan task hingga 24 jam. task_status `string` Status task. Enumerasi PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task tidak ada atau status tidak diketahui
request_id `string` Pengidentifikasi unik untuk permintaan, digunakan dalam pelacakan dan pemecahan masalah.
code `string` Kode kesalahan. Dikembalikan hanya ketika permintaan gagal. Lihat kode kesalahan untuk detailnya.
message `string` Pesan kesalahan detail. Dikembalikan hanya ketika permintaan gagal. Lihat kode kesalahan untuk detailnya.

Langkah 2: Tanyakan hasil berdasarkan ID task

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

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

Parameter permintaan	Hasil tugas kueri Ganti `86ecf553-d340-4e21-xxxxxxxxx` dengan ID task yang sebenarnya. Kunci API bersifat spesifik wilayah. Lihat dokumentasi Kunci API untuk detailnya. Untuk model di wilayah Beijing, ganti base_url dengan `https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx` `curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \ --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 task yang akan ditanyakan.

Parameter respons	Task berhasil Data task, seperti status task dan URL video, hanya disimpan selama 24 jam dan secara otomatis dihapus. Pastikan untuk segera menyimpan video yang dihasilkan. { "request_id": "851985d0-fbba-9d8d-a17a-xxxxxx", "output": { "task_id": "208e2fd1-fcb4-4adf-9fcc-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-05-15 16:14:44.723", "scheduled_time": "2025-05-15 16:14:44.750", "end_time": "2025-05-15 16:20:09.389", "video_url": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.mp4?xxxxxx", "orig_prompt": "In the video, a girl gracefully walks out from a misty, ancient forest. Her steps are light, and the camera captures her every nimble moment. When the girl stops and looks around at the lush woods, a smile of surprise and joy blossoms on her face. This scene, frozen in a moment of interplay between light and shadow, records her wonderful encounter with nature.", "actual_prompt": "A girl in a light-colored long dress slowly walks out from a misty, ancient forest, her steps as light as a dance. She has slightly curly long hair, a delicate face, and bright eyes. The camera follows her movements, capturing every nimble moment. When she stops, turns, and looks around at the lush woods, a smile of surprise and joy blossoms on her face. Sunlight filters through the leaves, casting mottled shadows and freezing this beautiful moment of harmony between human and nature. The style is a fresh and natural portrait, combining medium and full shots with a level perspective and slight camera movement." }, "usage": { "video_duration": 5, "video_ratio": "standard", "video_count": 1 } } Task gagal Ketika task gagal, `task_status` diatur ke FAILED dengan kode kesalahan dan pesan. 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" } }`
output `object` Informasi output task. Properti task_id `string` ID task. Dapat digunakan untuk menanyakan task hingga 24 jam. task_status `string` Status task. Enumerasi PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task tidak ada atau status tidak diketahui submit_time `string` Waktu saat task dikirim. Waktu dalam UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. scheduled_time `string` Waktu saat task mulai berjalan. Waktu dalam UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. end_time `string` Waktu saat task selesai. Waktu dalam UTC+8. Format: `YYYY-MM-DD HH:mm:ss.SSS`. video_url `string` URL video. Tautan berlaku selama 24 jam. Anda dapat menggunakan URL ini untuk mengunduh video. Format video output adalah MP4 (encoding H.264). orig_prompt `string` Prompt input asli. actual_prompt `string` Prompt aktual yang digunakan setelah penulisan ulang prompt diaktifkan. Jika penulisan ulang prompt dinonaktifkan, field ini tidak dikembalikan. code `string` Kode kesalahan. Dikembalikan hanya ketika permintaan gagal. Lihat kode kesalahan untuk detailnya. message `string` Pesan kesalahan detail. Dikembalikan hanya ketika permintaan gagal. Lihat kode kesalahan untuk detailnya.
usage `object` Statistik penggunaan untuk task. Hanya task yang berhasil yang dihitung. Properti video_duration `integer` Durasi video yang dihasilkan dalam detik. video_ratio `string` Rasio aspek video yang dihasilkan tetap pada `standard`. video_count `integer` Jumlah video yang dihasilkan.
request_id `string` Pengidentifikasi unik untuk permintaan. Digunakan untuk pelacakan dan troubleshooting masalah.

Penagihan dan batas laju

Untuk informasi tentang kuota gratis dan tarif penagihan model, lihat Pengeditan Video Umum.
Untuk informasi tentang batas laju model, lihat Seri Wan.

Kode kesalahan

Jika panggilan gagal, lihat Pesan kesalahan untuk troubleshooting.

Konfigurasi akses video

Konfigurasikan daftar putih nama domain: Pastikan sistem bisnis Anda dapat mengakses tautan video

Video yang dihasilkan disimpan di OSS Alibaba Cloud. Setiap video diberikan tautan OSS, seperti https://dashscope-result-xx.oss-cn-xxxx.aliyuncs.com/xxx.mp4. Tautan OSS memungkinkan akses publik, dan Anda dapat menggunakannya untuk mengunduh video. Tautan ini hanya berlaku selama 24 jam.

Jika bisnis Anda memiliki persyaratan keamanan tinggi dan tidak dapat mengakses tautan OSS Alibaba Cloud, Anda harus mengonfigurasi daftar putih untuk akses publik. Tambahkan nama domain berikut ke daftar putih Anda untuk mengakses tautan video.

# Daftar nama domain OSS
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

Ikhtisar model

Wilayah Singapura

Wilayah China (Beijing)

Contoh performa

Prasyarat

HTTP

Langkah 1: Buat task dan dapatkan ID task

Parameter permintaan

Referensi multi-gambar

Repainting video

Pengeditan lokal

Ekstensi video

Outpainting video

Header permintaan

Body permintaan

Referensi multi-gambar

Repainting video

Pengeditan lokal

Ekstensi video

Outpainting video

Parameter respons

Respons berhasil

Respons kesalahan

Langkah 2: Tanyakan hasil berdasarkan ID task

Parameter permintaan

Hasil tugas kueri

Header permintaan

Parameter path URL

Parameter respons

Task berhasil

Task gagal

Penagihan dan batas laju

Kode kesalahan

Konfigurasi akses video

Konfigurasikan daftar putih nama domain: Pastikan sistem bisnis Anda dapat mengakses tautan video