全部产品
Search

搜索本产品

    Alibaba Cloud Model Studio：Wan - referensi API penukaran karakter video

    文档中心

    Alibaba Cloud Model Studio：Wan - referensi API penukaran karakter video

    更新时间：Feb 12, 2026

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

    • Fitur inti: Menggantikan karakter utama dalam video dengan karakter dari gambar yang ditentukan sambil mempertahankan gerakan, ekspresi, dan lingkungan video asli.

    • Skenario: Fitur ini cocok untuk kasus penggunaan seperti pembuatan konten turunan dan pasca-produksi film.

    Contoh

    Model penukaran karakter video Wan wan2.2-animate-mix mendukung dua mode layanan: mode standar wan-std dan mode profesional wan-pro. Mode-mode ini berbeda dalam performa dan penagihan. Untuk informasi selengkapnya, lihat Penagihan dan pembatasan laju.

    Gambar karakter

    Video referensi

    Video output (Mode Standar wan-std)

    Video output (Mode Profesional wan-pro)

    mix_input_image

    HTTP

    Anda harus mendapatkan Kunci API dan menyetel 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 otentikasi atau kesalahan layanan.

    Generasi video memakan waktu lama. API HTTP beroperasi dalam mode asinkron. Proses pemanggilan terdiri dari dua langkah:

    1. Buat tugas untuk mendapatkan ID tugas: Kirim permintaan untuk membuat tugas. Respons mencakup task_id.

    2. Kueri hasil berdasarkan ID tugas: Gunakan task_id untuk melakukan polling status tugas hingga tugas selesai dan URL video dikembalikan.

    Langkah 1: Buat tugas

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

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

    Catatan

    • Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk mengkueri 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

    Penukaran karakter video

    Contoh berikut menunjukkan permintaan untuk wilayah Singapura. Untuk menggunakan model di wilayah Beijing, ganti URL dasar 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 permintaan

    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 parameter ini ke wan2.2-animate-mix.

    input object (Wajib)

    Objek parameter input, yang berisi bidang-bidang berikut:

    Properti

    image_url string (Wajib)

    URL HTTP atau HTTPS yang dapat diakses publik dari gambar input. URL tidak boleh mengandung karakter non-ASCII, seperti karakter Tionghoa. Jika mengandung karakter tersebut, encode URL sebelum meneruskannya dalam permintaan.

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

    • Batas dimensi: Lebar dan tinggi gambar masing-masing harus berada dalam rentang [200,4096] piksel, dan rasio aspek harus antara 1:3 hingga 3:1.

    • Batas ukuran: 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)

    URL HTTP atau HTTPS yang dapat diakses publik dari video input. URL tidak boleh mengandung karakter non-ASCII, seperti karakter Tionghoa. Jika mengandung karakter tersebut, encode URL sebelum meneruskannya dalam permintaan.

    Rekomendasi: Untuk kualitas video yang lebih baik, gunakan video referensi dengan resolusi dan laju frame yang lebih tinggi.

    • Format: MP4, AVI, MOV

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

    • Batas ukuran: Maksimal 200 MB

    • Batas durasi: Durasi harus antara 2 detik hingga 30 detik.

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

    watermark bool (Opsional)

    Menentukan apakah akan menambahkan Watermark. Watermark muncul di pojok kanan bawah video dan menampilkan teks "Tongyi AI Generated".

    • false (default)

    • true

    parameters object (Wajib)

    Properti

    check_image bool (Opsional)

    Menentukan apakah akan melakukan pemeriksaan gambar.

    • true (default)

    • false

    mode string (Wajib)

    Mode layanan model. Dua mode didukung.

    • wan-std

    • wan-pro

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

    Parameter respons

    Respons berhasil

    Simpan task_id untuk mengkueri 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 mengatasi 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 mengkueri 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. Digunakan 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: Kueri hasil

    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: Generasi video dapat memakan waktu beberapa menit. Kami menyarankan Anda menggunakan mekanisme polling dengan interval kueri 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 berlaku selama 24 jam. Setelah Anda mengambil 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 mengkueri hasilnya, dan API akan mengembalikan status tugas UNKNOWN.

    Parameter permintaan

    Kueri hasil tugas

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

    Contoh berikut menunjukkan permintaan untuk wilayah Singapura. Untuk menggunakan model di wilayah Beijing, ganti URL dasar 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 otentikasi menggunakan Kunci API Model Studio.

    Contoh: Bearer sk-xxxx

    Parameter path URL

    task_id string (Wajib)

    ID tugas yang akan dikueri.

    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 mengatasi 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 mengkueri 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 saat tugas dikirim. Waktu dalam UTC+8. Format: YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

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

    end_time string

    Waktu saat 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 penggunaan untuk tugas. Hanya hasil yang berhasil yang dihitung.

    Properti

    video_duration float

    Durasi penagihan video yang dihasilkan oleh permintaan ini, dalam satuan detik.

    video_ratio string

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

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

    request_id string

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

    Batasan

    Retensi data: task_id dan URL video hanya disimpan selama 24 jam. Setelah periode ini, data tersebut tidak dapat dikueri atau diunduh. Segera unduh video ke perangkat lokal Anda.

    Moderasi konten: Konten input dan output dikenai moderasi konten. Permintaan yang mengandung konten tidak sesuai akan mengembalikan kesalahan "IPInfringementSuspect" atau "DataInspectionFailed". Untuk informasi selengkapnya, lihat Pesan kesalahan.

    Konfigurasi akses jaringan: URL video disimpan di Object Storage Service (OSS). Jika sistem bisnis Anda tidak dapat mengakses URL OSS eksternal karena kebijakan keamanan, tambahkan Nama domain OSS berikut ke daftar putih akses jaringan.

    # Daftar nama domain OSS
dashscope-result-bj.oss-cn-beijing.aliyuncs.com
dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

    Penagihan dan pembatasan laju

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

    • Untuk batas laju, lihat Seri Wan.

    • Deskripsi penagihan:

      • Input tidak dikenai biaya. Output dikenai biaya. Anda dikenai biaya berdasarkan durasi dalam detik video yang berhasil dihasilkan.

      • Jika pemanggilan model gagal atau terjadi kesalahan selama pemrosesan, tidak ada biaya yang dikenakan, dan kuota gratis Anda tidak dikonsumsi.

    Kode kesalahan

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

    FAQ

    T: Bagaimana cara melihat penggunaan pemanggilan model?

    J: Informasi pemanggilan model mengalami penundaan sekitar satu jam. Sekitar satu jam setelah model dipanggil, buka halaman Monitoring (Singapura atau Beijing) untuk melihat metrik seperti jumlah pemanggilan dan tingkat keberhasilan. Bagaimana cara melihat catatan pemanggilan model?

    T: Bagaimana cara meningkatkan kualitas video yang dihasilkan?

    A: Ikuti saran berikut:

    1. Pastikan framing karakter pada gambar input dan video referensi serupa.

    2. Usahakan agar proporsi tubuh karakter 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 URL video sementara menjadi permanen?

    J: Anda tidak dapat mengonversi URL secara langsung. Prosedur yang benar adalah layanan backend Anda mengambil URL tersebut, mengunduh file video secara terprogram, lalu mengunggahnya ke layanan penyimpanan objek permanen—seperti OSS—untuk menghasilkan URL 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) # Tetapkan 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)

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

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