Skip to main content
Wan

Referensi API image-to-action Wan

Buat animasi gambar karakter dengan mentransfer aksi dari video referensi.

  • Rangkuman fitur: Transfer aksi dan ekspresi dari video referensi ke gambar karakter untuk menghasilkan video animasi.
  • Skenario: Replikasi tarian, gerakan tubuh kompleks, dan ekspresi wajah dari pertunjukan film dan televisi. Alternatif berbiaya rendah dibandingkan motion capture.

Efek model

Model wan2.2-animate-move mendukung dua mode layanan: mode standar wan-std dan mode profesional wan-pro, yang berbeda dalam kualitas output dan harga. Untuk informasi lebih lanjut, lihat Wanx-Image-to-Motion.
Gambar karakterVideo referensiVideo output (mode standarwan-std)Video output (mode profesionalwan-pro)
move_input_image

Prasyarat

Dapatkan Kunci API dan ekspor Kunci API sebagai variabel lingkungan.
Wilayah China (Beijing) dan Singapura memiliki Kunci API dan titik akhir permintaan yang terpisah. Keduanya tidak dapat saling dipertukarkan. Pemanggilan lintas wilayah menyebabkan kegagalan autentikasi atau error layanan.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
  • China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari https://dashscope-intl.aliyuncs.com ke https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan di halaman Detail Ruang Kerja pada Konsol Alibaba Cloud Model Studio. Domain lama tetap berfungsi sepenuhnya.

HTTP

Pembuatan video menggunakan panggilan asinkron. Prosesnya terdiri dari dua langkah: buat tugas, lalu polling hasilnya.

Langkah 1: Buat tugas dan dapatkan ID tugas

Singapura: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis Ganti {WorkspaceId} dengan ID Ruang Kerja aktual Anda. Beijing: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis
  • Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk menanyakan hasilnya. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.
  • Untuk panduan pemula, lihat Panggil API dengan Postman atau cURL.

Parameter permintaan

Header permintaan
Content-Type string (Wajib)Tipe konten permintaan. Harus berupa application/json.Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.X-DashScope-Async string (Wajib)Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus diatur ke enable.
Jika header permintaan ini tidak disertakan, error "current user api does not support synchronous calls" akan dikembalikan.
Body permintaan
model string (Wajib)Nama model. Atur parameter ini ke wan2.2-animate-move.input object (Wajib)Parameter input. Berisi bidang-bidang berikut:

Properti

image_url string (Wajib)URL HTTP atau HTTPS yang dapat diakses publik dari gambar karakter. URL yang mengandung karakter non-ASCII harus di-encode sesuai standar URL.
  • Format: JPG, JPEG, PNG, BMP, atau WEBP
  • Dimensi: Lebar dan tinggi harus berada dalam rentang [200, 4096] piksel. Rasio aspek harus antara 1:3 hingga 3:1.
  • Ukuran file: Maksimal 5 MB
  • Contoh: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg
video_url string (Wajib)URL HTTP atau HTTPS yang dapat diakses publik dari video referensi. URL yang mengandung karakter non-ASCII harus di-encode sesuai standar URL.Rekomendasi: Untuk hasil lebih baik, gunakan video referensi dengan resolusi dan laju frame lebih tinggi.
  • Format: MP4, AVI, atau MOV
  • Durasi: 2 hingga 30 detik
  • Dimensi: Lebar dan tinggi harus berada dalam rentang [200, 2048] piksel. Rasio aspek harus antara 1:3 hingga 3:1.
  • Ukuran file: Maksimal 200 MB
  • Contoh: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4
watermark bool (Opsional)Apakah akan menambahkan watermark "Generated by Qwen AI" di pojok kanan bawah video output.
  • false (default)
  • true
parameters object (Wajib)

Properti

check_image bool (Opsional)Apakah akan memvalidasi gambar input sebelum diproses.
  • true (default)
  • false
mode string (Wajib)Mode layanan. Nilai yang valid:
  • wan-std: Mode standar. Pembuatan lebih cepat dengan biaya lebih rendah. Cocok untuk pratinjau cepat dan animasi dasar.
  • wan-pro: Mode profesional. Animasi lebih mulus dan kualitas lebih tinggi, dengan waktu pemrosesan lebih lama dan biaya lebih tinggi.
Untuk informasi lebih lanjut, lihat Efek model dan Penagihan dan pembatasan laju.
  • Image to action
Berikut adalah URL wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Bailian Anda. URL berbeda-beda berdasarkan wilayah.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \
    --header 'X-DashScope-Async: enable' \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
        "model": "wan2.2-animate-move",
        "input": {
            "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/adsyrp/move_input_image.jpeg",
            "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4",
            "watermark": true
        },
        "parameters": {
            "mode": "wan-std"
        }
      }'

Parameter respons

output objectOutput tugas.

Properti

task_id stringID tugas. Berlaku untuk penanyakan selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
request_id stringIdentifikasi unik permintaan untuk pelacakan dan troubleshooting.message stringPesan error detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.
  • Respons sukses
  • Respons error
Simpan task_id untuk menanyakan status dan hasil tugas.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Langkah 2: Tanyakan hasil berdasarkan ID tugas

  • Singapura
  • China (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Saat memanggil, ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
  • Rekomendasi polling: Pembuatan video membutuhkan beberapa menit. Gunakan mekanisme polling dengan interval yang masuk akal, 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, penanyakan akan mengembalikan status tugas sebagai UNKNOWN.

Parameter permintaan

Header permintaan
Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
Parameter path URL
task_id string (Wajib)ID tugas tersebut.
  • Hasil kueri tugas
Ganti 0385dc79-5ff8-4d82-bcb6-xxxxxx dengan task_id Anda yang sebenarnya.
Berikut adalah URL wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Bailian Anda. URL berbeda-beda berdasarkan wilayah. 
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Parameter respons

output objectOutput tugas.

Properti

task_id stringID tugas. Berlaku untuk penanyakan selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
submit_time stringWaktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.results object

Properti

video_url stringURL video yang dihasilkan. Hanya dikembalikan ketika task_status bernilai SUCCEEDED.Berlaku selama 24 jam. Video dalam format MP4 dengan encoding H.264.
code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan error detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.
usage objectStatistik output. Hanya hasil sukses yang dihitung.

Properti

video_duration floatDurasi video yang dihasilkan, dalam satuan detik.video_ratio stringMode layanan yang digunakan untuk permintaan ini. Nilai enumerasi: standard dan pro.wan-std mengembalikan standard. wan-pro mengembalikan pro.
request_id stringIdentifikasi unik permintaan untuk pelacakan dan troubleshooting.
  • Tugas berhasil
  • Tugas gagal
URL video hanya berlaku selama 24 jam, lalu secara otomatis dihapus. Segera simpan video yang dihasilkan.
{
    "request_id": "a67f8716-18ef-447c-a286-xxxxxx",
    "output": {
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-18 15:32:00.105",
        "scheduled_time": "2025-09-18 15:32:15.066",
        "end_time": "2025-09-18 15:34:41.898",
        "results": {
            "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx"
        }
    },
    "usage": {
        "video_duration": 5.2,
        "video_ratio": "standard"
    }
}

Batasan

Validitas data: ID tugas dan URL video kedaluwarsa setelah 24 jam. Unduh video segera. Moderasi konten: Semua input dan output dimoderasi secara otomatis. Konten yang tidak sesuai mengembalikan error IPInfringementSuspect atau DataInspectionFailed. Untuk informasi lebih lanjut, lihat Kode kesalahan.

Penagihan dan pembatasan laju

Kode kesalahan

Jika pemanggilan model gagal dan mengembalikan pesan error, lihat Kode kesalahan.

FAQ

Bagaimana cara meningkatkan kualitas video output?

  1. Pastikan karakter menempati bagian frame yang serupa baik di gambar input maupun video referensi.
  2. Jaga proporsi tubuh konsisten antara gambar dan video.
  3. Gunakan materi sumber berdefinisi tinggi. Gambar buram atau video dengan laju frame rendah mengurangi kualitas output.

Bagaimana cara mengonversi tautan video sementara menjadi permanen?

Tautan tersebut tidak dapat dikonversi secara langsung. Unduh video dari backend Anda dan unggah ke penyimpanan objek permanen (seperti OSS) untuk mendapatkan URL permanen. 
import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Atur timeout
        response.raise_for_status() # Jika kode status HTTP bukan 200, bangkitkan exception
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"Video berhasil diunduh ke: {save_path}")
        # Anda dapat menambahkan logika untuk mengunggah ke penyimpanan permanen di sini
    except requests.exceptions.RequestException as e:
        print(f"Gagal mengunduh video: {e}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)

Apakah saya bisa memutar langsung tautan video yang dikembalikan di browser?

Tidak disarankan. Tautan tersebut kedaluwarsa setelah 24 jam. Unduh dan simpan video dari backend Anda, lalu sajikan melalui tautan permanen.

Bagaimana cara mendapatkan daftar putih nama domain untuk penyimpanan video?

Jawaban: Video yang dihasilkan model disimpan di OSS. API mengembalikan URL publik sementara. Untuk mengonfigurasi daftar putih firewall bagi URL unduhan 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 manajer akun Anda untuk mendapatkan daftar nama domain OSS terbaru.
Penggunaan API
Generasi teks
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Real-time multimodal
Realtime API
Penyematan Teks
Lainnya Model
Toolkit/Framework
TokenPlan
Model production
Manajemen file
Penagihan
Manajemen Model
Lebih Banyak Tentang Model