Model Wan 2.2 menghasilkan video dengan transisi mulus berdasarkan bingkai pertama, bingkai terakhir , dan prompt teks .
Dokumen terkait: Panduan pengguna
Untuk memastikan panggilan API berhasil, model, URL endpoint, dan Kunci API Anda harus berada di wilayah yang sama. Panggilan lintas-wilayah akan gagal.
Karena tugas image-to-video merupakan operasi berdurasi panjang yang biasanya memakan waktu 1 hingga 5 menit, API menggunakan panggilan asinkron. Prosesnya melibatkan dua langkah utama: membuat tugas, lalu polling hasilnya.
Nama parameter SDK sebagian besar konsisten dengan API HTTP, dan struktur parameternya mengikuti konvensi masing-masing bahasa pemrograman.
Karena tugas image-to-video berdurasi panjang (biasanya 1–5 menit), SDK menangani panggilan HTTP asinkron secara internal, mendukung metode panggilan sinkron dan asinkron.
Tetapkan
Jika pemanggilan model gagal, lihat Error codes untuk troubleshooting.
J: Rasio aspek video output bergantung pada gambar frame pertama (first_frame_url). Namun, rasio yang tepat (misalnya 3:4 secara ketat) tidak dapat dijamin, dan mungkin sedikit menyimpang.
J: Video yang dihasilkan oleh model disimpan di OSS. API mengembalikan URL publik temporary. 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 kebutuhan kontrol keamanan, hubungi account manager Anda untuk mendapatkan daftar nama domain OSS terbaru.
Catatan penggunaan
Untuk memastikan panggilan API berhasil, model, URL endpoint, dan Kunci API Anda harus berada di wilayah yang sama. Panggilan lintas-wilayah akan gagal.
- Pilih model: Konfirmasi wilayah tempat model tersedia.
- Pilih URL: Pilih URL endpoint yang sesuai dengan wilayah Anda. Baik URL HTTP maupun URL SDK DashScope didukung.
- Konfigurasikan Kunci API Anda: Pilih wilayah, dapatkan Kunci API Anda, lalu tetapkan sebagai Variabel lingkungan.
- Instal SDK: Untuk melakukan panggilan API menggunakan SDK, instal SDK DashScope.
Contoh kode dalam topik ini berlaku untuk Singapore.
Panggilan HTTP
Karena tugas image-to-video merupakan operasi berdurasi panjang yang biasanya memakan waktu 1 hingga 5 menit, API menggunakan panggilan asinkron. Prosesnya melibatkan dua langkah utama: membuat tugas, lalu polling hasilnya.
Langkah 1: Buat tugas
- Singapore
- China (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesisGanti {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 permintaanHeader permintaanContent-Typestring (Wajib)Tipe konten permintaan. Harus application/json.Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.X-DashScope-Async string (Wajib)Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus enable.Body permintaanmodelstring (Wajib)Nama model. Contoh: wan2.2-kf2v-flash.Untuk detailnya, lihat Konsol Model Studio.input object (Wajib)Berisi input utama untuk tugas, seperti prompt.
Properti prompt string (Opsional)Prompt teks. Mendukung bahasa Mandarin dan Inggris. Panjang maksimum adalah 800 karakter. Baik karakter Mandarin maupun huruf dihitung sebagai satu karakter. Teks yang melebihi batas ini akan dipotong.Jika terdapat perubahan signifikan pada subjek atau adegan antara frame pertama dan terakhir, kami merekomendasikan mendeskripsikan proses transisinya, seperti pergerakan kamera (misalnya, "camera moves to the left") atau pergerakan subjek (misalnya, "a person runs forward").Contoh: "Seekor kucing hitam kecil menatap langit dengan rasa ingin tahu. Kamera secara bertahap naik dari ketinggian mata dan akhirnya menangkap tatapan penasarannya dari sudut pandang atas."Untuk tips menulis prompt yang efektif, lihat Panduan prompt untuk text-to-video dan image-to-video.negative_prompt string (Opsional)Prompt negatif yang mendeskripsikan konten yang harus dikecualikan dari video, yang membantu membatasi output.Mendukung bahasa Mandarin dan Inggris. Panjang maksimum adalah 500 karakter. Teks yang melebihi batas ini akan dipotong.Contoh: "low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions".first_frame_url string (Wajib)URL gambar frame pertama. Rasio aspek video output akan mengikuti rasio aspek gambar tersebut.URL harus berupa alamat publik yang dapat diakses serta mendukung protokol HTTP atau HTTPS.Persyaratan gambar:
string (Wajib)URL gambar frame terakhir.URL harus berupa alamat publik yang dapat diakses serta mendukung protokol HTTP atau HTTPS.Persyaratan gambar:
object (Opsional)Parameter pemrosesan video.
Properti resolution string (Opsional)Resolusi video yang dihasilkan. Parameter ini menyesuaikan definisi (total piksel) tanpa mengubah rasio aspeknya.Nilai default dan nilai yang tersedia untuk parameter ini bergantung pada parameter model, seperti dijelaskan di bawah ini:
integer (Opsional)Nilai ini tetap pada 5.prompt_extendbool (Opsional)Menentukan apakah akan mengaktifkan penulisan ulang prompt. Saat diaktifkan, model bahasa besar (LLM) secara cerdas menulis ulang prompt input. Ini dapat secara signifikan meningkatkan hasil untuk prompt pendek tetapi meningkatkan latensi.
bool (Opsional)Menentukan apakah akan menambahkan watermark dengan teks "AI-generated" di pojok kanan bawah video.
integer (Opsional)Bilangan acak seed harus berupa integer 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. |
Menghasilkan video berdasarkan frame pertama, frame terakhir, dan prompt. |
Parameter responsoutputobjectInformasi output untuk tugas.
Properti task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.
Nilai enumerasi
stringPengidentifikasi permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Dikembalikan hanya untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Dikembalikan hanya untuk permintaan yang gagal. Lihat Kode kesalahan. |
Simpan task_id untuk mengkueri status dan hasil tugas. |
Langkah 2: Kueri hasil
- Singapore
- China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.- Rekomendasi polling: Pembuatan video memakan waktu beberapa menit. Gunakan mekanisme polling dengan interval yang wajar, seperti 15 detik.
- Transisi status tugas: PENDING → RUNNING → SUCCEEDED atau FAILED.
- Tautan hasil: Setelah tugas berhasil, URL video yang berlaku selama 24 jam dikembalikan. Unduh dan simpan video ke penyimpanan permanen, seperti OSS.
task_idmasa berlaku: 24 jam. Setelah periode ini, kueri mengembalikan status tugas sebagaiUNKNOWN.
Parameter permintaanHeader permintaanAuthorizationstring (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.Parameter pathtask_idstring (Wajib)ID tugas. |
Ganti 86ecf553-d340-4e21-xxxxxxxxx dengan task_id aktual Anda.Kunci API berbeda untuk setiap wilayah. Untuk informasi lebih lanjut, lihat Dapatkan Kunci API. Jika Anda menggunakan model di wilayah China (Beijing), ganti |
Parameter responsoutputobjectInformasi output untuk tugas.
Properti task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.
Nilai enumerasi
stringWaktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL video yang dihasilkan. Dikembalikan hanya 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.actual_prompt stringPrompt yang dioptimalkan yang digunakan saat penulisan ulang prompt diaktifkan. Tidak dikembalikan saat dinonaktifkan.code stringKode kesalahan. Dikembalikan hanya untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Dikembalikan hanya untuk permintaan yang gagal. Lihat Kode kesalahan.objectStatistik penggunaan tugas. Hanya tugas yang berhasil yang ditagih.
Properti video_duration integerDurasi video yang dihasilkan dalam detik, yang selalu 5. Rumus penagihan: Biaya = Detik video × Harga satuan.video_count integerJumlah video yang dihasilkan. Nilai ini tetap pada 1.video_ratio stringNilai ini saat ini hanya dikembalikan oleh model 2.1. Rasio aspek video yang dihasilkan, yang tetap pada standard.SR integerNilai ini saat ini hanya dikembalikan oleh model 2.2. Tingkat resolusi video yang dihasilkan. Nilai yang mungkin adalah 480, 720, dan 1080.stringPengidentifikasi permintaan unik untuk pelacakan dan troubleshooting. |
URL video hanya berlaku selama 24 jam, lalu secara otomatis dipurge. Simpan video yang dihasilkan segera. |
Panggilan SDK DashScope
Nama parameter SDK sebagian besar konsisten dengan API HTTP, dan struktur parameternya mengikuti konvensi masing-masing bahasa pemrograman.
Karena tugas image-to-video berdurasi panjang (biasanya 1–5 menit), SDK menangani panggilan HTTP asinkron secara internal, mendukung metode panggilan sinkron dan asinkron.
Waktu pemrosesan aktual bergantung pada jumlah tugas dalam antrian dan performa layanan. Mohon bersabar.
Panggilan SDK Python
Tetapkan base_http_api_url berdasarkan wilayah model:
- Singapore
- Beijing
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.Kode contoh
- Panggilan sinkron
- Panggilan asinkron
Contoh ini menunjukkan panggilan sinkron dengan dua metode input gambar: URL publik dan jalur file lokal.
Contoh permintaan
Contoh respons
video_url berlaku selama 24 jam. Harap unduh video dalam periode ini.
Panggilan SDK Java
Kode contoh
- Panggilan sinkron
- Panggilan asinkron
Contoh ini menunjukkan panggilan sinkron dengan dua metode input gambar: URL publik dan jalur file lokal.
Contoh permintaan
Contoh respons
video_url berlaku selama 24 jam. Harap unduh video tersebut dalam periode ini.
Batasan
- Retensi data:
task_iddanvideo_urldisimpan selama 24 jam, setelah itu tidak dapat diquery atau diunduh. - Dukungan audio: Layanan ini hanya menghasilkan video tanpa suara. Untuk menghasilkan audio, gunakan speech synthesis.
- Content Moderation: Content Moderation memeriksa semua prompt input, gambar, dan video output. Jika ada konten yang melanggar kebijakan penggunaan, layanan akan mengembalikan error "IPInfringementSuspect" atau "DataInspectionFailed". Untuk detailnya, lihat Error codes.
Error codes
Jika pemanggilan model gagal, lihat Error codes untuk troubleshooting.
FAQ
T: Bagaimana cara menghasilkan rasio aspek tertentu?
J: Rasio aspek video output bergantung pada gambar frame pertama (first_frame_url). Namun, rasio yang tepat (misalnya 3:4 secara ketat) tidak dapat dijamin, dan mungkin sedikit menyimpang.
-
Mengapa rasio aspek menyimpang?
Model menggunakan rasio aspek gambar input sebagai garis dasar dan menghitung resolusi valid terdekat berdasarkan total piksel dari pengaturan
resolutionyang dipilih. Karena lebar dan tinggi video harus merupakan kelipatan 16, model melakukan penyesuaian kecil pada resolusi akhir.- Sebagai contoh, jika Anda memberikan gambar input berukuran 750×1000 (rasio aspek 3:4 atau 0,75) dan menetapkan
resolutionke "720P" (menargetkan sekitar 920.000 piksel), output aktual mungkin berupa 816×1104 (rasio aspek sekitar 0,739, dengan sekitar 900.000 piksel).
- Sebagai contoh, jika Anda memberikan gambar input berukuran 750×1000 (rasio aspek 3:4 atau 0,75) dan menetapkan
-
Saran:
- Gambar Input: Untuk hasil terbaik, gunakan gambar frame pertama yang sesuai dengan rasio aspek target Anda.
- Pasca-pemrosesan: Jika diperlukan rasio aspek yang ketat, gunakan tool pengeditan video untuk memotong video yang dihasilkan atau menambahkan batang hitam (black bars).