Bagaimana cara memanggil API pengeditan video umum Wan (VACE)? -

Model pengeditan video umum Wan mendukung berbagai modalitas input, seperti teks, gambar, dan video, serta dapat menjalankan berbagai tugas pembuatan dan pengeditan video.

Referensi: Panduan pengguna

Ketersediaan

Gunakan wilayah yang sesuai untuk model, URL endpoint, dan Kunci API.

Pilih model: Pastikan model tersedia di wilayah target Anda.
Pilih URL: Pilih URL endpoint regional yang sesuai. Protokol HTTP dan HTTPS didukung.
Konfigurasikan Kunci API: Pilih wilayah, dapatkan Kunci API, dan konfigurasikan dalam variabel lingkungan.

Catatan

Kode contoh dalam topik ini berlaku untuk wilayah Singapura.

HTTP

Tugas pembuatan video memerlukan waktu 5–10 menit. API menggunakan pemanggilan asinkron: "Buat task → Poll hasil".

Langkah 1: Buat task

Singapura

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

Beijing

POST 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 Dapatkan Kunci API dan host API

URL berikut ini untuk wilayah Singapura. 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' \
--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": "Dalam video, seorang gadis berjalan anggun keluar dari hutan kuno yang berkabut. Langkahnya ringan, dan kamera menangkap setiap momen lincahnya. Saat ia berhenti dan melihat sekeliling ke hutan yang rimbun, senyum terkejut dan gembira merekah di wajahnya. Adegan ini, membeku dalam momen interaksi antara cahaya dan bayangan, merekam pertemuannya yang indah dengan alam.",
        "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 Dapatkan Kunci API dan host API

URL berikut ini untuk wilayah Singapura. 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' \
--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": "Video menampilkan mobil bergaya steampunk hitam yang dikemudikan oleh seorang pria. Mobil tersebut dihiasi roda gigi dan pipa tembaga. Latar belakang menampilkan pabrik permen bertenaga uap dan elemen retro, menciptakan adegan vintage yang menyenangkan.",
        "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 Dapatkan Kunci API dan host API

URL berikut ini untuk wilayah Singapura. 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' \
--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": "Video menampilkan kafe Prancis bergaya Paris tempat seekor singa berjas sedang menyesap kopi dengan elegan. Ia memegang cangkir kopi di satu tangan, menyesap pelan dengan ekspresi santai. Kafenya didekorasi secara apik, dengan nuansa lembut dan pencahayaan hangat yang menerangi area di sekitar singa tersebut.",
        "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 China (Beijing) berbeda. Untuk informasi lebih lanjut, lihat Dapatkan Kunci API dan host API

URL berikut ini untuk wilayah Singapura. 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' \
--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": "Seekor anjing yang memakai kacamata hitam sedang berselancar papan di jalan, kartun 3D.",
        "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 Dapatkan Kunci API dan host API

URL berikut ini untuk wilayah Singapura. 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' \
--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": "Seorang wanita elegan sedang memainkan biola dengan penuh semangat, dengan orkestra simfoni lengkap di belakangnya.",
        "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 error "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)

Teks yang menggambarkan elemen dan fitur visual untuk video. Mendukung bahasa Tionghoa dan Inggris. Setiap karakter, huruf, dan tanda baca dihitung sebagai satu. Teks yang melebihi batas akan dipotong.

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

function string (Wajib)

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

Mendukung hingga 3 gambar referensi. Konten gambar dapat mencakup entitas (manusia, hewan, pakaian) dan latar belakang (pemandangan). Gunakan prompt untuk menggambarkan konten video yang diinginkan. Model akan menggabungkan gambar menjadi video yang koheren.

ref_images_url array[string] (Wajib)

URL gambar referensi.

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

Berikan 1–3 gambar referensi. Jika lebih dari 3 disediakan, hanya 3 gambar pertama yang digunakan.

Persyaratan untuk gambar referensi:

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

Saran:

Untuk gambar entitas, gunakan satu entitas per gambar dengan latar belakang warna solid (putih atau satu warna).
Untuk gambar latar belakang, gunakan maksimal satu gambar, dan tidak boleh mengandung objek entitas.

parameters object (Opsional)

Parameter pemrosesan video, seperti pengaturan watermark.

Properti

obj_or_bg array[string] (Opsional)

Mengidentifikasi tujuan setiap gambar referensi (berkorespondensi satu-satu dengan ref_images_url). Setiap elemen menunjukkan apakah gambar yang sesuai merupakan "entitas" atau "latar belakang":

obj: Referensi entitas.
bg: Referensi latar belakang. Maksimal satu referensi latar belakang diperbolehkan.

Petunjuk:

Disarankan. Panjang harus sama dengan ref_images_url atau akan dilaporkan error.
Abaikan hanya ketika ref_images_url memiliki satu elemen (default ke ["obj"]).

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

size string (Opsional)

Resolusi video dalam format width*height. Nilai yang tersedia:

1280*720 (default): 16:9.
720*1280: 9:16.
960*960: 1:1.
832*1088: 3:4.
1088*832: 4:3.

duration integer (Opsional)

Durasi video dalam detik. Tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

Apakah akan mengaktifkan penulisan ulang prompt. LLM akan menulis ulang prompt input, meningkatkan kualitas untuk prompt pendek tetapi memperpanjang waktu pemrosesan.

true (default)
false

seed integer (Opsional)

Seed acak yang mengontrol keacakan generasi. Rentang: [0, 2147483647].

Dibuat otomatis jika diabaikan. Gunakan seed yang sama untuk hasil konsisten.

watermark bool (Opsional)

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

false (default)
true

Re-rendering Video

model string (Wajib)

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

input object (Wajib)

Informasi input dasar, seperti prompt.

Properti

prompt string (Wajib)

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

function string (Wajib)

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

Menyari pose entitas, aksi, komposisi, kontur gerak, dan struktur sketsa dari video input, lalu menggabungkannya dengan prompt teks untuk menghasilkan video baru dengan fitur dinamis yang sama. Anda juga dapat mengganti entitas dengan gambar referensi untuk mengubah penampilan sambil mempertahankan aksi.

video_url string (Wajib)

URL video input.

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

Persyaratan untuk video input:

Format: MP4.
Laju frame: 16 FPS atau lebih tinggi.
Ukuran: Maksimum 50 MB.
Durasi: Maksimum 5 detik. Jika lebih panjang, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Tionghoa.

Tentang resolusi video output:

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

Tentang 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 gambar referensi input.

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

Hanya 1 gambar referensi yang didukung. Kami menyarankan gambar ini berupa gambar entitas yang digunakan untuk menggantikan 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 Tionghoa.

Saran:

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

parameters object (Wajib)

Parameter pemrosesan video, seperti pengaturan watermark.

Properti

control_condition string (Wajib)

Mengatur metode ekstraksi fitur video.

posebodyface: Menyari ekspresi wajah dan gerakan tubuh entitas dalam video input. Cocok untuk skenario yang memerlukan pelestarian detail wajah.
posebody: Menyari gerakan tubuh entitas dari video input, tanpa ekspresi wajah. Gunakan ini untuk skenario yang hanya memerlukan kontrol gerakan tubuh.
depth: Menyari komposisi dan kontur gerak dari video input.
scribble: Menyari struktur sketsa 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 [0.0, 1.0].

Nilai yang lebih besar membuat video yang dihasilkan lebih mirip dengan aksi dan komposisi video asli. Nilai yang lebih kecil memberikan kebebasan kreatif lebih besar.

prompt_extend bool (Opsional)

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

true (default)
false (Direkomendasikan)

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

seed integer (Opsional)

Seed acak yang mengontrol keacakan generasi. Rentang: [0, 2147483647].

Dibuat otomatis jika diabaikan. Gunakan seed yang sama untuk hasil konsisten.

watermark bool (Opsional)

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

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)

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 publik:
- Mendukung protokol HTTP dan HTTPS.
- Contoh: https://xxx/xxx.mp3.

Persyaratan untuk video input:

Format: MP4.
Laju frame: 16 FPS atau lebih tinggi.
Ukuran: Maksimum 50 MB.
Durasi: Maksimum 5 detik. Jika lebih panjang, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Tionghoa.

Tentang resolusi video output:

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

Tentang 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 gambar referensi input.

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

Saat ini, hanya 1 gambar referensi yang didukung. Gambar ini dapat digunakan sebagai entitas atau latar belakang untuk menggantikan 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 Tionghoa.

Saran:

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

mask_image_url string (Opsional)

URL gambar mask.

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

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

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

Persyaratan gambar:

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

mask_frame_id integer (Opsional)

Parameter ini hanya digunakan ketika mask_image_url tidak kosong. Parameter ini mengidentifikasi frame tempat objek yang dimask muncul, direpresentasikan oleh "ID frame".

Nilai default adalah 1, yang menunjukkan frame pertama video.

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

Contohnya, 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 publik:
- Mendukung protokol HTTP dan HTTPS.
- Contoh: https://xxx/xxx.mp3.

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

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

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

parameters object (Opsional)

Parameter pemrosesan video, seperti pengaturan watermark.

Properti

control_condition string (Opsional)

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

posebodyface: Menyari ekspresi wajah dan gerakan tubuh entitas dalam video input. Cocok untuk skenario di mana wajah entitas besar dalam frame dan memiliki fitur yang jelas terlihat.
depth: Menyari komposisi dan kontur 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 mengikuti lintasan objek target secara dinamis. Mode ini cocok untuk adegan dengan objek bergerak.
fixed: Area pengeditan tetap dan tidak berubah mengikuti konten video.

expand_ratio float (Opsional)

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

Rentang nilai [0.0, 1.0]. Nilai default adalah 0.05. Kami merekomendasikan 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)

Ketika mask_type diatur ke tracking, parameter ini berlaku dan menentukan bentuk area mask.

Algoritma menghasilkan video mask dengan bentuk yang sesuai berdasarkan gambar mask input dan expand_mode yang dipilih. Nilai yang didukung:

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

size string (Opsional)

Resolusi video dalam format width*height. Nilai yang tersedia:

1280*720 (default): 16:9.
720*1280: 9:16.
960*960: 1:1.
832*1088: 3:4.
1088*832: 4:3.

duration integer (Opsional)

Durasi video dalam detik. Tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

true (default)
false (Direkomendasikan)

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

seed integer (Opsional)

Seed acak yang mengontrol keacakan generasi. Rentang: [0, 2147483647].

Dibuat otomatis jika diabaikan. Gunakan seed yang sama untuk hasil konsisten.

watermark bool (Opsional)

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

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)

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

function string (Wajib)

Nama fitur. Ekstensi video diatur ke video_extension.

Ekstensi video menghasilkan konten berkelanjutan berdasarkan gambar atau video. Fitur ini juga mengekstraksi fitur dinamis, seperti aksi dan komposisi, dari video referensi untuk membimbing generasi video dengan gerakan serupa.

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

first_frame_url string (Opsional)

URL gambar frame pertama.

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

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

last_frame_url string(Opsional)

URL gambar frame terakhir.

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

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

first_clip_url string (Opsional)

URL segmen video pertama.

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

Persyaratan video:

Format video: MP4.
Laju frame video: 16 FPS atau lebih tinggi. Jika Anda menggunakan first_clip_url dan last_clip_url, kami menyarankan kedua klip memiliki laju frame yang sama.
Ukuran video: Tidak boleh melebihi 50 MB.
Durasi video: Tidak boleh melebihi 3 detik. Jika durasi lebih panjang, 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 Tionghoa.

Tentang resolusi video output:

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

last_clip_url string(Opsional)

URL segmen video terakhir.

URL publik:
- Mendukung protokol HTTP dan HTTPS.
- Contoh: https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3.

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.
Durasi video: Tidak boleh melebihi 3 detik. Jika durasi lebih panjang, 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 Tionghoa.

Tentang resolusi video output:

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

video_url string (Opsional)

URL video input.

URL publik:
- Mendukung protokol HTTP dan HTTPS.
- Contoh: https://help-static-aliyun-doc.aliyuncs.com/xxx.mp3.

Digunakan untuk mengekstraksi fitur gerak. Gabungkan dengan first_frame_url, last_frame_url, first_clip_url, dan last_clip_url untuk membimbing generasi video ekstensi dengan gerakan 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.
Durasi video: Tidak boleh melebihi 5 detik. Jika durasi lebih panjang, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Tionghoa.

parameters object (Opsional)

Parameter pemrosesan video, seperti resolusi video output.

Properti

control_condition string (Opsional)

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

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

duration integer (Opsional)

Durasi video dalam detik. Tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

true (default)
false (Direkomendasikan)

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

seed integer (Opsional)

Seed acak yang mengontrol keacakan generasi. Rentang: [0, 2147483647].

Dibuat otomatis jika diabaikan. Gunakan seed yang sama untuk hasil konsisten.

watermark bool (Opsional)

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

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)

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.

Memungkinkan ekstensi video proporsional ke arah atas, bawah, kiri, dan kanan.

video_url string (Wajib)

URL video input.

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

Persyaratan untuk video input:

Format: MP4.
Laju frame: 16 FPS atau lebih tinggi.
Ukuran: Maksimum 50 MB.
Durasi: Maksimum 5 detik. Jika lebih panjang, hanya 5 detik pertama yang digunakan.
URL tidak boleh mengandung karakter Tionghoa.

Tentang resolusi video output:

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

Tentang 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: [1.0, 2.0]. Default: 1.0 (tanpa penskalaan).

bottom_scale float (Opsional)

Memusatkan frame video dan menskalakan video ke bawah secara proporsional. Rentang: [1.0, 2.0]. Default: 1.0 (tanpa penskalaan).

left_scale float (Opsional)

Memusatkan frame video dan menskalakan video ke kiri secara proporsional. Rentang: [1.0, 2.0]. Default: 1.0 (tanpa penskalaan).

right_scale float (Opsional)

Memusatkan bingkai video dan menskala video secara proporsional. Rentang: [1,0–2,0]. Default: 1,0 (tanpa penskalaan).

duration integer (Opsional)

Durasi video dalam detik. Tetap pada 5 dan tidak dapat diubah. Model selalu menghasilkan video berdurasi 5 detik.

prompt_extend bool (Opsional)

true (default)
false (Direkomendasikan)

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

seed integer (Opsional)

Seed acak yang mengontrol keacakan generasi. Rentang: [0, 2147483647].

Dibuat otomatis jika diabaikan. Gunakan seed yang sama untuk hasil konsisten.

watermark bool (Opsional)

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

false (default)
true

Parameter respons	Respons sukses 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 error Pembuatan task gagal. Lihat kode kesalahan untuk mengatasi 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 Tugas. Enumerasi PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Task tidak ada atau status tidak diketahui
request_id `string` Pengidentifikasi unik untuk permintaan. Digunakan untuk pelacakan dan troubleshooting 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

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 `{task_id}` dengan nilai `task_id` yang dikembalikan oleh panggilan API sebelumnya. `task_id` valid untuk permintaan 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 task yang akan ditanyakan.

Parameter respons	Task berhasil Data task disimpan selama 24 jam, lalu dihapus otomatis. Simpan video segera. { "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": "Dalam video, seorang gadis berjalan anggun keluar dari hutan kuno yang berkabut. Langkahnya ringan, dan kamera menangkap setiap momen lincahnya. Saat gadis itu berhenti dan melihat sekeliling ke hutan yang rimbun, senyum terkejut dan gembira merekah di wajahnya. Adegan ini, membeku dalam momen interaksi antara cahaya dan bayangan, merekam pertemuannya yang indah dengan alam.", "actual_prompt": "Seorang gadis berbaju panjang berwarna terang berjalan perlahan keluar dari hutan kuno yang berkabut, langkahnya ringan seperti menari. Rambutnya panjang agak keriting, wajahnya halus, dan matanya cerah. Kamera mengikuti gerakannya, menangkap setiap momen lincahnya. Saat ia berhenti, berbalik, dan melihat sekeliling ke hutan yang rimbun, senyum terkejut dan gembira merekah di wajahnya. Sinar matahari menembus dedaunan, menciptakan bayangan bercak dan membekukan momen indah harmoni antara manusia dan alam. Gaya gambarnya adalah potret segar dan alami, menggabungkan bidikan medium dan penuh dengan perspektif datar dan sedikit gerakan kamera." }, "usage": { "video_duration": 5, "video_ratio": "standard", "video_count": 1 } } Task gagal Saat task gagal, `task_status` diatur ke FAILED dengan kode dan pesan kesalahan. Lihat kode kesalahan untuk mengatasi 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 diajukan. 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 (valid selama 24 jam). Format: 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 output, hanya dihitung untuk task yang berhasil. 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.

Batasan

Validitas data: task_id dan video_url disimpan selama 24 jam. Setelah kedaluwarsa, tidak dapat ditanyakan atau diunduh.
Dukungan audio: Model menghasilkan video tanpa suara. Untuk menambahkan audio, gunakan sintesis suara.

Kode kesalahan

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

FAQ

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

J: Video yang dihasilkan model disimpan di OSS. API mengembalikan URL publik sementara. Untuk mengonfigurasi daftar putih firewall untuk URL unduh 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.

Ketersediaan

HTTP

Langkah 1: Buat task

Singapura

Beijing

Parameter permintaan

Referensi multi-gambar

Repainting video

Pengeditan lokal

Ekstensi video

Outpainting video

Header permintaan

Body permintaan

Referensi multi-gambar

Re-rendering Video

Pengeditan lokal

Ekstensi video

Outpainting video

Parameter respons

Respons sukses

Respons error

Langkah 2: Tanyakan hasil

Singapura

Beijing

Parameter permintaan

Hasil tugas kueri

Header permintaan

Parameter path URL

Parameter respons

Task berhasil

Task gagal

Batasan

Kode kesalahan

FAQ

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