All Products
Search

This Product

    Alibaba Cloud Model Studio:Referensi API image-to-action Wan

    Document Center

    Alibaba Cloud Model Studio:Referensi API image-to-action Wan

    Last Updated:Mar 04, 2026

    API image-to-action Wan menganimasikan gambar karakter dengan mentransfer aksi dari video referensi.

    • Rangkuman fitur: Mentransfer aksi dan ekspresi dari video referensi ke gambar karakter untuk membuat video animasi.

    • Skenario penggunaan: Meniru 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 selengkapnya, lihat Harga pemanggilan model.

    Gambar karakter

    Video referensi

    Video output (mode standarwan-std)

    Video output (mode profesionalwan-pro)

    move_input_image

    Prasyarat

    Dapatkan Kunci API dan ekspor Kunci API sebagai Variabel lingkungan.

    Penting

    Wilayah Beijing dan Singapura memiliki Kunci API dan titik akhir permintaan yang terpisah. Jangan menggunakannya secara bergantian. Pemanggilan lintas wilayah akan menyebabkan kegagalan autentikasi atau error layanan.

    HTTP

    Pembuatan video menggunakan panggilan asinkron. Proses ini terdiri dari dua langkah: buat task, lalu polling hasilnya.

    Langkah 1: Buat task dan dapatkan ID task

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

    Beijing: POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    Catatan

    • Setelah task dibuat, gunakan task_id yang dikembalikan untuk menanyakan hasilnya. task_id berlaku selama 24 jam. Jangan membuat task duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.

    • Untuk tutorial pemula, lihat Postman.

    Parameter permintaan

    Image to action

    base_url berikut digunakan untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti base_url dengan: https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

    curl --location 'https://dashscope-intl.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"
    }
  }'

    Header permintaan

    Content-Type string (Wajib)

    Tipe konten permintaan. Harus berupa application/json.

    Authorization string (Wajib)

    Kredensial autentikasi 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

    Akan mengembalikan error "current user api does not support synchronous calls" jika tidak disertakan.

    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 input. URL yang berisi karakter non-ASCII (seperti karakter Tionghoa) harus di-URL-encoded.

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

    • Konten: Gambar harus menampilkan satu orang yang menghadap ke depan dengan wajah tidak terhalang, menempati bagian sedang dari frame.

    • 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 input. URL yang berisi karakter non-ASCII (seperti karakter Tionghoa) harus di-URL-encoded.

    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.

    • Konten: Video harus menampilkan satu orang yang menghadap ke depan dengan wajah tidak terhalang, menempati bagian sedang dari frame.

    • Contoh: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4

    watermark bool (Opsional)

    Menentukan apakah akan menambahkan watermark "Generated by Qwen AI" di pojok kanan bawah video.

    • false (default)

    • true

    parameters object (Wajib)

    Properti

    check_image bool (Opsional)

    Menentukan apakah akan memvalidasi gambar input.

    • true (default)

    • false

    mode string (Wajib)

    Mode layanan. Nilai yang valid:

    • wan-std: Mode standar. Generasi lebih cepat dengan biaya lebih rendah. Cocok untuk pratinjau cepat dan animasi dasar.

    • wan-pro: Mode profesional. Animasi lebih halus dan kualitas lebih tinggi, dengan waktu pemrosesan lebih lama dan biaya lebih tinggi.

    Untuk informasi selengkapnya, lihat Efek model dan Penagihan dan Pembatasan laju.

    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 menyelesaikan masalah.

    {
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

    output object

    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

    Identifier unik untuk permintaan. Gunakan untuk pelacakan dan troubleshooting masalah.

    message string

    Pesan error detail. Hanya dikembalikan saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

    code string

    Kode kesalahan. Hanya dikembalikan saat 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}

    Catatan

    • Saran polling: Pembuatan video dapat memakan waktu beberapa menit. Kami menyarankan Anda menggunakan mekanisme polling dengan interval permintaan yang wajar, misalnya 15 detik, untuk mengambil hasilnya.

    • Transisi status task: PENDING → RUNNING → SUCCEEDED atau FAILED.

    • URL hasil: Setelah task berhasil, URL video dikembalikan. URL tersebut berlaku selama 24 jam. Setelah Anda mendapatkan URL tersebut, segera unduh dan simpan video ke layanan penyimpanan permanen, seperti Object Storage Service (OSS).

    • Validitas task_id: 24 jam. Setelah periode ini, Anda tidak dapat menanyakan hasilnya, dan API akan mengembalikan status task UNKNOWN.

    Parameter permintaan

    Hasil Kueri Tugas

    Ganti 0385dc79-5ff8-4d82-bcb6-xxxxxx dengan task_id Anda yang sebenarnya.

    base_url berikut digunakan untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti base_url dengan: https://dashscope.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx
    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    Header permintaan

    Authorization string (Wajib)

    Kredensial autentikasi 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

    URL video hanya disimpan selama 24 jam, lalu secara otomatis dipurge. 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"
    }
}

    Task gagal

    Saat task gagal, task_status diatur ke FAILED dengan kode error dan pesan. Lihat kode kesalahan untuk menyelesaikan masalah.

    {
    "request_id": "daad9007-6acd-9fb3-a6bc-xxxxxx",
    "output": {
        "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx",
        "task_status": "FAILED",
        "code": "InternalError",
        "message": "xxxxxx"
    }
}

    output object

    Keluaran Tugas.

    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.

    results object

    Properti

    video_url string

    URL video yang dihasilkan. Hanya dikembalikan saat task_status bernilai SUCCEEDED.

    URL berlaku selama 24 jam. Gunakan untuk mengunduh video dalam format MP4 dengan encoding H.264.

    code string

    Kode kesalahan. Hanya dikembalikan saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

    message string

    Pesan error detail. Hanya dikembalikan saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

    usage object

    Statistik output. Hanya hasil sukses yang dihitung.

    Properti

    video_duration float

    Durasi video yang dihasilkan untuk permintaan ini, dalam satuan detik.

    video_ratio string

    Mode layanan yang dipilih untuk permintaan video ini. Nilai enumerasi: standard dan pro.

    Jika Anda memilih mode standar (wan-std), nilainya adalah standard. Jika Anda memilih mode profesional (wan-pro), nilainya adalah pro.

    request_id string

    Identifier unik untuk permintaan. Gunakan untuk pelacakan dan troubleshooting masalah.

    Batasan

    Validitas data: ID task dan URL video kedaluwarsa setelah 24 jam dan tidak dapat diakses setelah itu. Unduh video segera.

    Moderasi Konten: Semua input dan output dimoderasi secara otomatis. Konten yang tidak sesuai akan memicu error "IPInfringementSuspect" atau "DataInspectionFailed". Untuk informasi selengkapnya, lihat Pesan error.

    Penagihan dan Pembatasan laju

    • Untuk kuota gratis dan harga, lihat Harga pemanggilan model.

    • Untuk batas laju, lihat Seri Wan.

    • Deskripsi penagihan:

      • Hanya output yang dikenai biaya. Biaya dihitung berdasarkan durasi (dalam detik) video yang dihasilkan.

      • Panggilan yang gagal tidak dikenai biaya atau mengurangi kuota gratis pengguna baru.

    Kode kesalahan

    Jika pemanggilan model gagal dan mengembalikan pesan error, lihat Pesan error untuk penyelesaiannya.

    FAQ

    Q: Bagaimana cara mengoptimalkan kualitas video yang dihasilkan?

    A: Pertimbangkan hal-hal berikut:

    1. Pastikan orang tersebut menempati bagian frame yang serupa baik di gambar input maupun video referensi.

    2. Jaga agar proporsi tubuh konsisten antara gambar dan video.

    3. Gunakan materi sumber berdefinisi tinggi. Hindari gambar buram atau video dengan laju frame rendah.

    Q: Bagaimana cara mengonversi tautan video sementara menjadi permanen?

    A: Tautan tersebut tidak dapat dikonversi secara langsung. Backend Anda harus mengunduh file video tersebut dan mengunggahnya ke penyimpanan objek permanen (seperti OSS) untuk menghasilkan URL permanen.

    Contoh kode: Unduh video ke perangkat lokal

    import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # Setel 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)

    Q: Apakah tautan video yang dikembalikan dapat diputar langsung di browser?

    A: Tidak disarankan. Tautan tersebut kedaluwarsa setelah 24 jam. Backend Anda harus mengunduh dan menyimpan video tersebut, lalu menggunakan tautan permanen untuk pemutaran.

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

    A: Video yang dihasilkan oleh model disimpan di OSS. API mengembalikan URL publik sementara. Untuk mengonfigurasi daftar putih firewall untuk 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 persyaratan kontrol keamanan, hubungi account manager Anda untuk mendapatkan daftar nama domain OSS terbaru.