Skip to main content
Wan

Referensi API video character swap Wan

Mengganti karakter utama dalam video dengan karakter dari gambar sambil mempertahankan adegan, pencahayaan, dan nuansa asli untuk integrasi tanpa hambatan.

  • Fitur utama: Mengganti karakter dalam video dengan orang dari gambar yang ditentukan sambil mempertahankan tindakan, ekspresi, dan lingkungan video asli.
  • Skenario: Ideal untuk penggantian karakter dalam pembuatan konten turunan dan pasca produksi.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain berikut:
  • 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.

Contoh

wan2.2-animate-mix mendukung dua mode layanan: mode standar (wan-std) dan mode profesional (wan-pro). Lihat Penagihan dan pembatasan laju untuk perbedaan performa dan penagihan.
Gambar karakterVideo referensiVideo output (mode standarwan-std)Video output (mode profesionalwan-pro)
mix_input_image

HTTP

Dapatkan Kunci API dan ekspor Kunci API sebagai variabel lingkungan.
Wilayah China (Beijing) dan Singapura memiliki Kunci API dan titik akhir permintaan terpisah. Keduanya tidak dapat digunakan secara bergantian. Pemanggilan lintas wilayah menyebabkan kegagalan autentikasi atau error layanan.
Penggantian karakter memerlukan waktu lama, sehingga API menggunakan pemanggilan asinkron: buat tugas, lalu polling hasilnya.

Langkah 1: Buat tugas

Singapura:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis 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
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 ada, error "current user api does not support synchronous calls" akan dikembalikan.
Body permintaan
model string (Wajib)Nama model. Atur nilai ini ke wan2.2-animate-mix.input object (Wajib)Gambar dan video input untuk penggantian karakter.

Properti

image_url string (Wajib)URL HTTP atau HTTPS yang dapat diakses publik untuk gambar karakter. URL tidak boleh mengandung karakter non-ASCII (misalnya, karakter Tionghoa). Jika mengandung karakter tersebut, encode URL sebelum mengirimkannya.
  • Format: JPG, JPEG, PNG, BMP, atau WEBP.
  • Resolusi: Lebar dan tinggi masing-masing harus 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)URL HTTP atau HTTPS yang dapat diakses publik untuk video referensi. URL tidak boleh mengandung karakter non-ASCII (misalnya, karakter Tionghoa). Jika mengandung karakter tersebut, encode URL sebelum mengirimkannya.Tips: Resolusi dan laju frame yang lebih tinggi meningkatkan kualitas output.
  • Format: MP4, AVI, atau MOV.
  • Resolusi: Lebar dan tinggi masing-masing harus 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)Menambahkan watermark "AI Generated" di pojok kanan bawah video output.
  • false (default): Tanpa watermark.
  • true: Watermark ditambahkan.
parameters object (Wajib)

Properti

check_image boolean (Opsional)Mengontrol apakah gambar input diperiksa sebelum diproses.
  • true (default): Memeriksa gambar input sebelum diproses.
  • false: Melewati pemeriksaan dan langsung memproses gambar.
mode string (Wajib)Mode layanan. Tersedia dua mode:
  • 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 visual lebih baik, dengan waktu pemrosesan lebih lama dan biaya lebih tinggi.
Untuk detailnya, lihat Contoh dan Penagihan dan pembatasan laju.
  • Video character swap
Berikut adalah URL wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Bailian Anda. URL bervariasi 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-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"
        }
      }'

Parameter respons

output objectInformasi output tugas.

Properti

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

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
request_id stringIdentifier unik permintaan untuk pelacakan dan troubleshooting.message stringPesan error detail. Dikembalikan hanya untuk permintaan yang gagal. Lihat Kode kesalahan.code stringKode kesalahan. Dikembalikan hanya 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 memerlukan beberapa menit. Gunakan mekanisme polling dengan interval yang wajar, 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, kueri akan mengembalikan status tugas sebagai UNKNOWN.

Parameter permintaan

Header
Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
Parameter path URL
task_id string (Wajib)ID tugas.
  • Kueri hasil 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 bervariasi 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 objectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri 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. Dikembalikan hanya ketika task_status bernilai SUCCEEDED.Berlaku selama 24 jam. Video dalam format MP4 dengan encoding H.264.
code stringKode kesalahan. Dikembalikan hanya untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan error detail. Dikembalikan hanya untuk permintaan yang gagal. Lihat Kode kesalahan.
usage objectDikembalikan hanya untuk tugas yang berhasil.

Properti

video_duration floatDurasi video yang dihasilkan, dalam satuan detik.video_ratio stringMode layanan yang digunakan untuk permintaan ini. Mengembalikan standard untuk mode wan-std, atau pro untuk mode wan-pro.
request_id stringIdentifier 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

Retensi data: ID tugas dan URL video disimpan selama 24 jam. Unduh video ke perangkat lokal Anda sebelum masa berlakunya habis. Moderasi konten: Semua konten input dan output dikenai moderasi. Konten yang dilarang mengembalikan error IPInfringementSuspect atau DataInspectionFailed. Untuk detailnya, lihat Kode kesalahan.

Penagihan dan pembatasan laju

  • Untuk kuota gratis dan harga satuan, lihat harga model.
  • Untuk batas laju, lihat Seri Wan.
  • Detail penagihan:
    • Penagihan didasarkan pada durasi video output (dalam detik) hanya untuk video yang berhasil dihasilkan. Input tidak dikenai biaya.
    • Pemanggilan yang gagal dan error pemrosesan tidak dikenai biaya atau mengonsumsi kuota gratis.

Kode kesalahan

Jika pemanggilan gagal, lihat Kode kesalahan.

FAQ

T: Bagaimana cara melihat penggunaan pemanggilan model?

J: Data invokasi memiliki keterlambatan sekitar 1 jam. Lihat metrik (volume invokasi, jumlah, dan laju keberhasilan) di halaman Monitoring (Singapura atau Beijing). Untuk informasi selengkapnya, lihat Bagaimana cara melihat catatan invokasi model?

T: Bagaimana cara meningkatkan kualitas video yang dihasilkan?

J: Untuk mendapatkan hasil yang lebih baik:
  1. Pastikan framing karakter konsisten baik di gambar input maupun video referensi.
  2. Pertahankan proporsi tubuh yang konsisten antara gambar dan video.
  3. Gunakan materi sumber berdefinisi tinggi — gambar buram atau video dengan laju frame rendah mengurangi akurasi detail.

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

J: Konversi langsung tidak didukung. Backend Anda harus mengunduh video tersebut dan mengunggahnya ke Object Storage Service (OSS) untuk mendapatkan tautan akses 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() # 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 — tautan kedaluwarsa setelah 24 jam. Unduh dan simpan video di backend Anda, lalu sajikan melalui tautan permanen.

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