Model image-to-video Wan 2.7 mendukung input multimodal (teks, gambar, audio, dan video) serta menjalankan tiga tugas: first-frame-to-video, first-and-last-frame-to-video, dan video continuation .
Referensi: Panduan pengguna
Model, URL endpoint, dan Kunci API harus berada dalam Wilayah yang sama. Pemanggilan lintas-Wilayah akan gagal.
Tugas image-to-video biasanya memerlukan waktu 1 hingga 5 menit, sehingga API menggunakan pemanggilan asinkron. Alur kerja terdiri dari dua langkah: buat tugas, lalu poll hasilnya.
Ganti
Ganti
Nama parameter SDK sesuai dengan API HTTP. Struktur parameter dienkapsulasi berdasarkan konvensi bahasa.
Tugas image-to-video biasanya memerlukan waktu 1 hingga 5 menit. SDK mengenkapsulasi proses pemanggilan asinkron HTTP dan mendukung pemanggilan sinkron maupun asinkron.
Atur dashscope.base_http_api_url berdasarkan Wilayah model:
Ganti
Atur Constants.baseHttpApiUrl berdasarkan Wilayah model:
Ganti
Jika pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk menyelesaikan masalah.
J: Rasio aspek output ditentukan oleh materi input (gambar frame pertama atau klip video pertama) tetapi tidak dijamin persis sama. Deviasi kecil dapat terjadi.
Contoh berikut menjelaskan logika menggunakan gambar frame pertama sebagai input:
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 usang. Jika Anda memiliki kebutuhan kontrol keamanan, hubungi manajer akun Anda untuk mendapatkan daftar nama domain OSS terbaru.
API image-to-video baru (model wan2.7) mendukung ketiga tugas tersebut. API image-to-video dari frame pertama sebelumnya (wan2.6 dan versi lebih lama) hanya mendukung first-frame-to-video.
Ketersediaan
Model, URL endpoint, dan Kunci API harus berada dalam Wilayah yang sama. Pemanggilan lintas-Wilayah akan gagal.
- Pilih model: Pastikan model tersedia di Wilayah target Anda.
- Pilih URL: Gunakan URL endpoint yang sesuai dengan Wilayah model Anda. URL HTTP dan SDK DashScope didukung.
- Konfigurasikan Kunci API: Dapatkan Kunci API untuk Wilayah tersebut, lalu konfigurasikan Kunci API sebagai Variabel lingkungan.
- Instal SDK: Untuk melakukan pemanggilan API menggunakan SDK, instal SDK DashScope.
Kode contoh dalam topik ini berlaku untuk Wilayah Singapura.
HTTP
Tugas image-to-video biasanya memerlukan waktu 1 hingga 5 menit, sehingga API menggunakan pemanggilan asinkron. Alur kerja terdiri dari dua langkah: buat tugas, lalu poll hasilnya.
Langkah 1: Buat tugas dan dapatkan ID tugas
- Singapura
- Beijing
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis{WorkspaceId} dengan ID ruang kerja aktual Anda.
- Setelah tugas dibuat, gunakan
task_idyang dikembalikan untuk mengkueri hasilnya.task_idberlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya. - Untuk panduan pemula, lihat Panggil API dengan Postman atau cURL.
Parameter permintaan |
Buat video berdasarkan gambar frame pertama dan audio. |
Content-Type string (Wajib)Tipe konten permintaan. Harus application/json. | |
Authorization string (Wajib)Mengautentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx. | |
X-DashScope-Async string (Wajib)Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung pemanggilan asinkron. Harus enable. | |
Body permintaan | |
model string (Wajib)Nama model. Untuk daftar model dan harga, lihat Harga model.Contoh: wan2.7-i2v-2026-04-25. | |
input object (Wajib)Informasi input dasar, termasuk prompt.
Properti prompt string (Opsional)Prompt teks yang menjelaskan elemen dan karakteristik visual untuk video yang dihasilkan.Mendukung bahasa Tionghoa dan Inggris. Maksimal 5.000 karakter.Setiap karakter Tionghoa atau huruf dihitung sebagai satu karakter. Teks yang melebihi batas akan dipotong secara otomatis.Contoh: Seekor anak kucing berlari di atas rumput.Untuk informasi lebih lanjut tentang cara menggunakan prompt, lihat Panduan prompt text-to-video/image-to-video.negative_prompt string (Opsional)Menjelaskan konten yang harus dikecualikan dari video.Mendukung bahasa Tionghoa dan Inggris. Maksimal 500 karakter. Teks yang melebihi batas akan dipotong secara otomatis.Contoh: resolusi rendah, error, kualitas terburuk, kualitas rendah, cacat, jari ekstra, proporsi buruk.media array (Wajib)Materi referensi (gambar, audio, dan video) untuk generasi video.Setiap elemen adalah objek media dengan bidang type dan url.
Kombinasi aset Hanya kombinasi aset berikut yang valid. Kombinasi tidak valid akan mengembalikan kesalahan.
Properti type string (Wajib)Jenis aset media. Nilai valid:
type hanya boleh muncul paling banyak sekali dalam array media. Misalnya, Anda tidak dapat mengirim dua aset first_frame.url string (Wajib)URL aset media (gambar, audio, atau video).
Kirim gambar (type=first_frame atau last_frame) URL atau data Base64-encoded untuk gambar frame pertama atau terakhir.Batasan gambar:
Kirim audio (type=driving_audio) URL file audio.
Kirim video (type=first_clip) URL file video. Model menghasilkan kelanjutan berdasarkan konten video. Parameter duration mengontrol durasi total maksimum output.Misalnya, jika duration=15 dan video input berdurasi 3 detik, model menghasilkan kelanjutan 12 detik. Video output akhir berdurasi 15 detik dan ditagih untuk 15 detik.Batasan video:
| |
parameters object (Opsional)Parameter pemrosesan video: resolusi, durasi, penulisan ulang prompt, dan watermark.
Properti resolution string (Opsional)Tingkat resolusi untuk video yang dihasilkan. Mengontrol jumlah total piksel.Model secara otomatis menskalakan video ke jumlah total piksel yang mendekati tingkat yang dipilih. Rasio aspek output mengikuti materi input (frame pertama atau klip video pertama). Untuk detail, lihat FAQ.Nilai valid adalah 720P dan 1080P. Default: 1080P.duration integer (Opsional)Durasi video yang dihasilkan dalam detik. Rentang valid tergantung pada model:Nilai valid: bilangan bulat dari 2 hingga 15. Default: 5.prompt_extendboolean (Opsional)Apakah akan mengaktifkan penulisan ulang prompt. Saat diaktifkan, model menulis ulang prompt input untuk meningkatkan hasil prompt pendek, tetapi meningkatkan waktu pemrosesan.
boolean (Opsional)Apakah akan menambahkan watermark "AI Generated" di pojok kanan bawah video.
integer (Opsional)Seed bilangan acak harus berupa bilangan bulat dalam rentang [0, 2147483647].Jika tidak ditentukan, seed acak akan dihasilkan. Seed tetap meningkatkan reproduktibilitas.Karena generasi model bersifat probabilistik, seed yang sama tidak menjamin hasil identik. |
Parameter respons |
Simpan task_id untuk mengkueri status dan hasil tugas. |
output objectInformasi output tugas.
Properti task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.
Nilai enumerasi
| |
request_id stringIdentifikasi permintaan unik untuk pelacakan dan troubleshooting. | |
code stringKode kesalahan. Hanya dikembalikan untuk permintaan gagal. Lihat Kode kesalahan. | |
message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan gagal. Lihat Kode kesalahan. |
Langkah 2: Kueri hasil berdasarkan ID tugas
- Singapura
- Beijing
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}{WorkspaceId} dengan ID ruang kerja aktual Anda.
- Rekomendasi polling: Generasi video memerlukan beberapa menit. Gunakan mekanisme polling dengan interval 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 sebagaiUNKNOWN.
Parameter permintaan |
Ganti {task_id} dengan nilai task_id yang dikembalikan oleh pemanggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam, Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. |
Header | |
Authorization string (Wajib)Mengautentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx. | |
Parameter path | |
task_id string (Wajib)ID tugas. |
Parameter respons |
URL video hanya berlaku selama 24 jam, lalu secara otomatis dipurge. Segera simpan video yang dihasilkan. |
outputobjectInformasi output tugas.
Properti task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.
Nilai enumerasi
stringWaktu saat tugas dikirim. Waktu dalam UTC+8 dan format YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu saat tugas dieksekusi. Waktu dalam UTC+8 dan format YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu saat tugas selesai. Waktu dalam UTC+8 dan format YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL video yang dihasilkan. Hanya dikembalikan saat task_status bernilai SUCCEEDED.Berlaku selama 24 jam. Video dalam format MP4 dengan encoding H.264.orig_prompt stringPrompt input asli, sesuai dengan parameter permintaan prompt.code stringKode kesalahan. Hanya dikembalikan untuk permintaan gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan gagal. Lihat Kode kesalahan. | |
usage objectStatistik penggunaan. Dihitung hanya untuk tugas yang berhasil.
Properti input_video_duration integerDurasi video input, dalam detik.output_video_duration integerDurasi video output, dalam detik.duration integerTotal durasi video yang digunakan untuk penagihan.SR integerResolusi video output. Contoh: 720.video_count integerJumlah video output. Tetap 1. | |
request_id stringIdentifikasi permintaan unik untuk pelacakan dan troubleshooting. |
DashScope SDK
Nama parameter SDK sesuai dengan API HTTP. Struktur parameter dienkapsulasi berdasarkan konvensi bahasa.
Tugas image-to-video biasanya memerlukan waktu 1 hingga 5 menit. SDK mengenkapsulasi proses pemanggilan asinkron HTTP dan mendukung pemanggilan sinkron maupun asinkron.
Waktu pemrosesan aktual tergantung pada antrian tugas dan beban layanan. Tunggu hasilnya.
SDK Python
Atur dashscope.base_http_api_url berdasarkan Wilayah model:
- Singapura
- Beijing
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'{WorkspaceId} dengan ID ruang kerja aktual Anda.
- Panggilan sinkron
- Panggilan asinkron
Contoh permintaan
Contoh respons
video_url berlaku selama 24 jam. Segera unduh video.
SDK Java
Atur Constants.baseHttpApiUrl berdasarkan Wilayah model:
- Singapura
- Beijing
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"{WorkspaceId} dengan ID ruang kerja aktual Anda.
- Panggilan sinkron
- Panggilan asinkron
Panggilan sinkron akan memblokir hingga generasi video selesai dan hasil dikembalikan.
Contoh permintaan
Contoh respons
video_url berlaku selama 24 jam. Segera unduh video.
Kode kesalahan
Jika pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk menyelesaikan masalah.
FAQ
T: Bagaimana cara menghasilkan video dengan rasio aspek tertentu, seperti 3:4?
J: Rasio aspek output ditentukan oleh materi input (gambar frame pertama atau klip video pertama) tetapi tidak dijamin persis sama. Deviasi kecil dapat terjadi.
Contoh berikut menjelaskan logika menggunakan gambar frame pertama sebagai input:
-
Mengapa deviasi terjadi?
- Logika eksekusi: Sistem menggunakan rasio aspek gambar input sebagai garis dasar, dikombinasikan dengan total piksel target untuk tingkat
resolution. Karena pengkodean video memerlukan lebar dan tinggi kelipatan 16, sistem menyesuaikan output ke resolusi valid terdekat. - Contoh perhitungan: Gambar input 750 x 1000 piksel (rasio 3:4 = 0,75) dengan resolusi "720P" (~920.000 total piksel) menghasilkan output 816 x 1104 piksel (rasio ~0,739, ~900.000 total piksel).
- Logika eksekusi: Sistem menggunakan rasio aspek gambar input sebagai garis dasar, dikombinasikan dengan total piksel target untuk tingkat
-
Rekomendasi:
- Kontrol input: Gunakan frame pertama atau klip video yang sesuai dengan rasio aspek target Anda.
- Pasca-pemrosesan: Untuk kebutuhan rasio aspek ketat, potong video atau tambahkan bilah hitam setelah generasi.