All Products
Search

This Product

    Alibaba Cloud Model Studio:Wan - referensi API pertukaran karakter video

    Document Center

    Alibaba Cloud Model Studio:Wan - referensi API pertukaran karakter video

    Last Updated:Mar 04, 2026

    Model pertukaran karakter video Wan menggantikan karakter utama dalam video dengan karakter dari gambar yang ditentukan, sekaligus mempertahankan adegan, pencahayaan, dan nuansa video asli untuk integrasi tanpa hambatan.

    • Fitur utama: Menggantikan karakter dalam video dengan seseorang dari gambar yang ditentukan, sekaligus mempertahankan tindakan, ekspresi, dan lingkungan video aslinya.

    • Skenario: Cocok untuk skenario yang memerlukan penggantian karakter, seperti pembuatan konten turunan dan pascaproduksi.

    Contoh

    wan2.2-animate-mix tersedia dalam dua mode layanan dengan performa dan penagihan berbeda: mode standar wan-std dan mode profesional wan-pro. Untuk informasi selengkapnya, lihat Penagihan dan pembatasan laju.

    Gambar karakter

    Video referensi

    Video output (mode standarwan-std)

    Video output (mode profesionalwan-pro)

    mix_input_image

    HTTP

    Dapatkan Kunci API dan ekspor kunci API sebagai variabel lingkungan.

    Penting

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

    Tugas pertukaran karakter video memakan waktu lama, sehingga API menggunakan pemanggilan asinkron dalam dua langkah: "Buat tugas → Polling hasil":

    Langkah 1: Buat tugas

    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 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 tutorial pemula, lihat Postman.

    Parameter permintaan

    Pertukaran karakter video

    Berikut adalah base_url untuk wilayah Singapura. Jika Anda menggunakan model dari 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-mix",
    "input": {
        "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg",
        "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4",
        "watermark": true
    },
    "parameters": {
        "mode": "wan-std"
    }
  }'

    Header

    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 kesalahan "current user api does not support synchronous calls" jika tidak disertakan.

    Body permintaan

    model string (Wajib)

    Nama model. Atur ke wan2.2-animate-mix.

    input object (Wajib)

    Informasi input dasar.

    Properties

    image_url string (Wajib)

    Tautan HTTP atau HTTPS yang dapat diakses publik ke gambar input. URL tidak boleh mengandung karakter non-ASCII, seperti karakter Tionghoa. Jika mengandung karakter tersebut, Anda harus mengencode URL sebelum mengirimkannya.

    • Format: JPG, JPEG, PNG, BMP, atau WEBP.

    • Batas resolusi: Lebar dan tinggi gambar harus berada dalam rentang [200, 4096] piksel. Rasio aspek harus antara 1:3 dan 3:1.

    • Ukuran file: Maksimal 5 MB

    • Contoh: https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg

    video_url string (Wajib)

    Tautan HTTP atau HTTPS yang dapat diakses publik ke video input. URL tidak boleh mengandung karakter non-ASCII, seperti karakter Tionghoa. Jika mengandung karakter tersebut, Anda harus mengencode URL sebelum mengirimkannya.

    Saran: Tingkatkan resolusi dan laju frame video referensi untuk meningkatkan kualitas video yang dihasilkan.

    • Format: MP4, AVI, atau MOV.

    • Batas resolusi: Lebar dan tinggi video harus berada dalam rentang [200, 2048] piksel. Rasio aspek harus antara 1:3 dan 3:1.

    • Ukuran file: Maksimal 200 MB

    • Durasi: 2 hingga 30 detik

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

    watermark boolean (Opsional)

    Menentukan apakah akan menambahkan watermark. Watermark ditempatkan di pojok kanan bawah video dengan teks tetap "AI Generated".

    • false (default)

    • true

    parameters object (Wajib)

    Properti

    check_image boolean (Opsional)

    Menentukan apakah akan melakukan deteksi gambar.

    • true (default): API mendeteksi gambar input.

    • false: Deteksi gambar dilewati dan gambar diproses langsung.

    mode string (Wajib)

    Mode layanan model. Dua mode berikut didukung:

    • wan-std: Mode standar. Mode ini menghasilkan output lebih cepat dan hemat biaya. Cocok untuk pratinjau cepat dan skenario animasi dasar.

    • wan-pro: Mode profesional. Mode ini memberikan animasi yang lebih halus dan efek yang lebih baik, tetapi waktu pemrosesan dan biaya meningkat sesuai.

    Untuk informasi selengkapnya, lihat Contoh dan Penagihan dan pembatasan laju.

    Parameter respons

    Respons sukses

    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"
}

    Respons kesalahan

    Pembuatan tugas gagal. Lihat kode kesalahan untuk menyelesaikan masalah.

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

    output object

    Informasi output tugas.

    Properti

    task_id string

    ID tugas. Dapat digunakan untuk menanyakan tugas hingga 24 jam.

    task_status string

    Status tugas.

    Enumerasi

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Tugas tidak ada atau status tidak diketahui

    request_id string

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

    message string

    Pesan kesalahan 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 tugas

    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 tugas: PENDING → RUNNING → SUCCEEDED atau FAILED.

    • URL hasil: Setelah tugas 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 tugas UNKNOWN.

    Parameter permintaan

    Tanyakan hasil tugas

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

    Base URL di bawah ini 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

    Authorization string (Wajib)

    Kredensial otentikasi menggunakan Kunci API Model Studio.

    Contoh: Bearer sk-xxxx

    Parameter path URL

    task_id string (Wajib)

    ID tugas yang akan ditanyakan.

    Parameter respons

    Tugas 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"
    }
}

    Tugas gagal

    Saat tugas gagal, task_status diatur ke FAILED dengan kode kesalahan 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

    Informasi output tugas.

    Properti

    task_id string

    ID tugas. Dapat digunakan untuk menanyakan tugas hingga 24 jam.

    task_status string

    Status tugas.

    Enumerasi

    • PENDING

    • RUNNING

    • SUCCEEDED

    • FAILED

    • CANCELED

    • UNKNOWN: Tugas tidak ada atau status tidak diketahui

    submit_time string

    Waktu tugas diajukan. Waktu dalam UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    Waktu tugas mulai dijalankan. Waktu dalam UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    Waktu tugas 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 kesalahan detail. Hanya dikembalikan saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

    usage object

    Statistik output hanya untuk hasil yang sukses.

    Properti

    video_duration float

    Durasi video yang dihasilkan, dalam satuan detik.

    video_ratio string

    Mode layanan model yang digunakan untuk permintaan ini. Nilai yang valid: standard dan pro.

    Jika Anda mengatur parameter `mode` ke wan-std, parameter ini mengembalikan standard. Jika Anda mengatur parameter `mode` ke wan-pro, parameter ini mengembalikan pro.

    request_id string

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

    Batasan

    Periode retensi data: ID tugas dan URL video hanya disimpan selama 24 jam. Setelah kedaluwarsa, Anda tidak dapat menanyakan atau mengunduhnya. Anda harus mengunduh video ke perangkat lokal Anda.

    Moderasi konten: Konten input dan output tunduk pada Moderasi Konten. Permintaan yang mengandung konten terlarang akan mengembalikan kesalahan `IPInfringementSuspect` atau `DataInspectionFailed`. Untuk informasi selengkapnya, lihat Pesan kesalahan.

    Penagihan dan pembatasan laju

    • Untuk kuota gratis dan harga satuan, lihat harga model.

    • Untuk batas laju, lihat Seri Wan.

    • Detail penagihan:

      • Anda tidak ditagih untuk input. Anda ditagih untuk output berdasarkan durasi dalam detik dari video yang berhasil dihasilkan.

      • Pemanggilan model yang gagal atau kesalahan pemrosesan tidak dikenai biaya atau mengurangi kuota gratis.

    Kode kesalahan

    Jika pemanggilan model gagal dan pesan kesalahan dikembalikan, lihat Pesan kesalahan untuk menyelesaikan masalah.

    FAQ

    T: Bagaimana cara melihat penggunaan pemanggilan model?

    J: Data pemanggilan model memiliki penundaan sekitar satu jam. Sekitar satu jam setelah Anda memanggil model, Anda dapat membuka halaman Pemantauan (Singapura atau Beijing) untuk melihat metrik seperti volume pemanggilan, jumlah pemanggilan, dan tingkat keberhasilan. Untuk informasi selengkapnya, lihat Bagaimana cara melihat catatan pemanggilan model?

    T: Bagaimana cara mengoptimalkan kualitas video yang dihasilkan?

    A: Pertimbangkan saran berikut:

    1. Pastikan framing karakter dalam gambar input mirip dengan framing dalam video referensi.

    2. Pertahankan proporsi tubuh karakter yang konsisten antara gambar dan video.

    3. Gunakan materi sumber definisi tinggi. Hindari gambar buram dan video dengan laju frame rendah untuk memastikan pengenalan detail yang akurat.

    T: Bagaimana cara mengonversi tautan video sementara menjadi tautan permanen?

    J: Anda tidak dapat mengonversi tautan secara langsung. Metode yang benar adalah layanan backend Anda mengunduh file video menggunakan URL tersebut, lalu mengunggahnya ke Object Storage Service (OSS) untuk menghasilkan tautan akses permanen baru.

    Kode contoh: 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) # Atur timeout
        response.raise_for_status() # Bangkitkan exception jika kode status HTTP bukan 200
        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}")
        # Logika untuk mengunggah ke penyimpanan permanen dapat ditambahkan 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)

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

    J: Hal ini tidak disarankan karena tautan tersebut kedaluwarsa setelah 24 jam. Praktik terbaik adalah backend mengunduh dan menyimpan video, lalu menggunakan tautan permanen untuk pemutaran.

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

    J: 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 manajer akun Anda untuk mendapatkan daftar nama domain OSS terbaru.