All Products
Search

This Product

    Alibaba Cloud Model Studio:Wanxiang - Referensi API Image-to-Video

    Document Center

    Alibaba Cloud Model Studio:Wanxiang - Referensi API Image-to-Video

    Last Updated:Apr 05, 2026

    Model image-to-video Wan mendukung input multi-modal (teks, gambar, audio, dan video) serta dapat menjalankan tiga tugas utama: pembuatan video dari frame pertama, pembuatan video dari frame pertama dan terakhir, serta kelanjutan video.

    Catatan

    API image-to-video yang baru (model wan2.7-i2v) mendukung ketiga tugas tersebut. Gunakan API baru ini.

    API image-to-video dari frame pertama versi lama (model wan2.6 dan sebelumnya) hanya mendukung pembuatan video dari frame pertama.

    Cakupan

    Agar panggilan API berhasil, gunakan wilayah yang sama untuk model, URL titik akhir, dan kunci API. Panggilan lintas-wilayah akan gagal.

    Catatan

    Kode contoh dalam topik ini berlaku untuk wilayah Singapore.

    Panggilan HTTP

    Penting

    API ini menggunakan protokol image-to-video baru dan hanya mendukung model wan2.7.

    Karena tugas image-to-video memakan waktu lama—biasanya 1 hingga 5 menit—API ini menggunakan alur pemanggilan asinkron yang terdiri dari dua langkah inti: Buat Tugas → Polling untuk Mengambil Hasil.

    Langkah 1: Buat tugas dan dapatkan ID tugas

    Singapore

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

    Beijing

    POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/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

    Pembuatan video dari frame pertama

    Buat video berdasarkan gambar frame pertama dan audio.

    curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.7-i2v",
    "input": {
        "prompt": "A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of the rap, with no other dialogue or noise.",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            },
            {
                "type": "driving_audio",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
                
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 10,
        "prompt_extend": true,
        "watermark": true
    }
}'

    Pembuatan video dari frame pertama dan terakhir

    Masukkan frame pertama dan frame terakhir untuk menghasilkan video.

    curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.7-i2v",
    "input": {
        "prompt": "Realistic style, a small black cat looks up at the sky curiously. The camera angle gradually rises from eye level, finally capturing its curious gaze from a top-down view.",
        "media": [
            {
                "type": "first_frame",
                "url": "https://wanx.alicdn.com/material/20250318/first_frame.png"
            },
            {
                "type": "last_frame",
                "url": "https://wanx.alicdn.com/material/20250318/last_frame.png"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 10,
        "prompt_extend": false,
        "watermark": true
    }
}'

    Kelanjutan video

    Buat konten lanjutan berdasarkan klip video awal.

    curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "wan2.7-i2v",
    "input": {
        "prompt": "A girl takes a selfie in the mirror, then leaves with her backpack.",
        "media": [
            {
                "type": "first_clip",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4"
            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 10,
        "prompt_extend": true,
        "watermark": true
    }
}'

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

    Body permintaan

    model string (Wajib)

    Nama model. Untuk daftar model dan harga, lihat Harga model.

    Contoh: wan2.7-i2v.

    input object (Wajib)

    Informasi input dasar, seperti prompt.

    Properti

    prompt string (Opsional)

    Prompt teks. Mendeskripsikan elemen dan karakteristik visual video yang akan dihasilkan.

    Mendukung bahasa Mandarin dan Inggris. Setiap karakter Mandarin atau huruf dihitung sebagai satu karakter. Teks yang melebihi batas akan dipotong secara otomatis. Batas panjang bervariasi tergantung versi model:

    • wan2.7-i2v: hingga 5.000 karakter.

    Contoh: Seekor anak kucing berlari di atas rumput.

    Untuk informasi lebih lanjut tentang cara menggunakan prompt, lihat Panduan prompt untuk text-to-video dan image-to-video.

    negative_prompt string (Opsional)

    Prompt negatif. Mendeskripsikan konten yang tidak ingin muncul dalam video.

    Mendukung bahasa Mandarin dan Inggris. Prompt dapat memiliki panjang maksimal 500 karakter. Teks yang melebihi batas akan dipotong secara otomatis.

    Contoh: resolusi rendah, error, kualitas terburuk, kualitas rendah, bentuk cacat, jari ekstra, proporsi buruk.

    media array (Wajib)

    Menentukan materi referensi (gambar, audio, dan video) untuk pembuatan video.

    Setiap elemen dalam array adalah objek media yang berisi bidang type dan url.

    Kombinasi aset

    Hanya kombinasi aset berikut yang didukung. Kombinasi yang tidak valid akan menghasilkan error.

    • Pembuatan video dari frame pertama:

      • Frame pertama: first_frame

      • Frame pertama + audio: first_frame+driving_audio

    • Pembuatan video dari frame pertama dan terakhir:

      • Frame pertama + frame terakhir: first_frame+last_frame

      • Frame pertama + frame terakhir + audio: first_frame+last_frame+driving_audio

    • Kelanjutan video:

      • Kelanjutan klip video pertama: first_clip

      • Kelanjutan klip video pertama + frame terakhir: first_clip+last_frame

    Properti

    type string (Wajib)

    Jenis aset media. Nilai yang valid:

    • first_frame: Frame pertama.

    • last_frame: Frame terakhir.

    • driving_audio: Audio yang digunakan sebagai pendorong.

    • first_clip: Klip video pertama.

    Batasan: Setiap type hanya boleh muncul paling banyak satu kali dalam array media. Misalnya, Anda tidak dapat mengirim dua aset first_frame.

    url string (Wajib)

    URL aset media. Contohnya termasuk gambar, audio, dan video.

    Masukkan gambar (type=first_frame atau last_frame)

    URL frame pertama atau terakhir.

    Batasan gambar:

    • Format: JPEG, JPG, PNG (saluran alpha tidak didukung), BMP, WEBP.

    • Resolusi: Lebar dan tinggi harus dalam rentang [240, 8000] piksel.

    • Rasio aspek: 1:8 hingga 8:1.

    • Ukuran file: maksimal 20 MB.

    Format input yang didukung:

    1. URL publik:

      • Protokol HTTP atau HTTPS didukung.

      • Contoh: https://xxx/xxx.png.

    Masukkan audio (type=driving_audio)

    URL file audio.

    • Masukkan audio: Model menggunakan audio sebagai sumber pendorong untuk menghasilkan video, misalnya untuk sinkronisasi bibir dan penyesuaian gerakan.

    • Tidak memasukkan audio: Model secara otomatis menghasilkan musik latar atau efek suara yang sesuai dengan konten video.

    Batasan audio:

    • Format: WAV, MP3.

    • Durasi: 2 hingga 30 detik.

    • Ukuran file: maksimal 15 MB.

    • Pemotongan: Jika durasi audio melebihi nilai duration, misalnya 5 detik, maka 5 detik pertama yang digunakan dan sisa audio dibuang. Jika audio lebih pendek daripada video, bagian video yang melebihi durasi audio akan menjadi senyap. Misalnya, jika audio berdurasi 3 detik dan video 5 detik, 3 detik pertama video hasil akan memiliki suara, sedangkan 2 detik terakhir akan senyap.

    Format input yang didukung:

    1. URL publik:

      • Protokol HTTP dan HTTPS didukung.

      • Contoh: https://xxx/xxx.mp3.

    Masukkan video (type=first_clip)

    URL file video. Model melanjutkan video berdasarkan kontennya. Durasi maksimum kelanjutan dikontrol oleh parameter duration.

    Misalnya, jika duration=15 dan video input berdurasi 3 detik, model menghasilkan kelanjutan selama 12 detik. Video output akhir berdurasi 15 detik dan ditagih selama 15 detik.

    Batasan video:

    • Format: MP4, MOV.

    • Durasi: 2 hingga 10 detik.

    • Resolusi: Lebar dan tinggi harus dalam rentang [240, 4096] piksel.

    • Rasio aspek: 1:8 hingga 8:1.

    • Ukuran file: maksimal 100 MB.

    Format input yang didukung:

    1. URL publik:

      • Protokol HTTP dan HTTPS didukung.

      • Contoh: https://xxx/xxx.mp4.

    parameters object (Opsional)

    Parameter pemrosesan video, seperti resolusi, durasi, penulisan ulang prompt, dan watermark.

    Properti

    resolution string (Opsional)

    Penting

    Resolusi berdampak langsung pada biaya. Sebelum melakukan panggilan, pastikan Harga model.

    Tier resolusi untuk video yang dihasilkan. Mengontrol jumlah total piksel.

    Model secara otomatis menskalakan video ke jumlah total piksel yang mendekati tier resolusi yang dipilih. Rasio aspek video sebaiknya konsisten dengan materi input (frame pertama atau klip video pertama). Untuk informasi lebih lanjut, lihat FAQ.

    • wan2.7-i2v: Nilai yang valid adalah 720P dan 1080P. Default: 1080P.

    Contoh: 1080P.

    duration integer (Opsional)

    Penting

    Durasi berdampak langsung pada biaya. Penagihan dilakukan per detik. Sebelum melakukan panggilan, pastikan Harga model.

    Durasi video yang dihasilkan, dalam satuan detik, bergantung pada parameter model:

    • wan2.7-i2v: bilangan bulat dari 2 hingga 15. Default: 5.

    Contoh: 5.

    prompt_extendboolean (Opsional)

    Menentukan apakah akan mengaktifkan penulisan ulang prompt. Saat diaktifkan, model bahasa besar akan menulis ulang prompt input. Ini dapat meningkatkan hasil untuk prompt pendek tetapi memperpanjang waktu eksekusi.

    • true: Mengaktifkan penulisan ulang cerdas. Ini adalah nilai default.

    • false: Menonaktifkan penulisan ulang cerdas.

    Contoh: true.

    watermark boolean (Opsional)

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

    • false: Tidak menambahkan watermark. Ini adalah nilai default.

    • true: Menambahkan watermark.

    Contoh: false.

    seed integer (Opsional)

    Seed bilangan acak. Harus berupa bilangan bulat antara 0 dan 2147483647.

    Jika tidak diberikan, seed acak akan dihasilkan. Menggunakan seed tetap meningkatkan kemampuan reproduksi, meskipun hasilnya masih dapat bervariasi karena keacakan model.

    Contoh: 12345

    Parameter respons

    Respons sukses

    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 error

    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 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. Gunakan untuk pelacakan dan troubleshooting masalah.

    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.

    Langkah 2: Kueri hasil berdasarkan ID tugas

    Singapore

    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. Gunakan 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 tersebut berlaku selama 24 jam. Setelah Anda mendapatkan URL, 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 {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri dalam waktu 24 jam.

    curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
    Header

    Authorization string (Wajib)

    Kredensial otentikasi menggunakan kunci API Model Studio.

    Contoh: Bearer sk-xxxx

    Parameter path

    task_id string (Wajib)

    ID tugas yang akan dikueri.

    Parameter respons

    Tugas berhasil

    URL video hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan video yang dihasilkan.

    {
    "request_id": "2ca1c497-f9e0-449d-9a3f-xxxxxx",
    "output": {
        "task_id": "af6efbc0-4bef-4194-8246-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-25 11:07:28.590",
        "scheduled_time": "2025-09-25 11:07:35.349",
        "end_time": "2025-09-25 11:17:11.650",
        "orig_prompt": "A scene of urban fantasy art. A dynamic graffiti art character. A boy made of spray paint comes to life on a concrete wall. He sings an English rap song at high speed while striking a classic, energetic rapper pose. The scene is set under an urban railway bridge at night. The light comes from a single street lamp, creating a cinematic atmosphere full of high energy and amazing detail. The audio of the video consists entirely of his rap, with no other dialogue or noise.",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 0,
        "output_video_duration": 15,
        "video_count": 1,
        "SR": 720
    }
}

    Tugas gagal

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

    {
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

    Kueri tugas kedaluwarsa

    task_id berlaku selama 24 jam. Setelah periode ini, kueri gagal dan mengembalikan pesan kesalahan berikut.

    {
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

    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

    Transisi status selama polling:

    • PENDING → RUNNING → SUCCEEDED atau FAILED

    • Kueri pertama biasanya mengembalikan PENDING atau RUNNING

    • Status SUCCEEDED menyertakan URL video yang dihasilkan dalam respons

    • Status FAILED memerlukan pemeriksaan pesan kesalahan dan percobaan ulang

    submit_time string

    Waktu saat tugas diajukan. 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.

    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 pengkodean H.264.

    orig_prompt string

    Prompt input asli. Ini adalah nilai dari parameter permintaan prompt.

    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 informasi output. Hanya hasil sukses yang dihitung.

    Properti

    input_video_duration integer

    Durasi video input dalam detik.

    output_video_duration integer

    Durasi video output dalam detik.

    duration integer

    Total durasi video, digunakan untuk penagihan.

    SR integer

    Tier resolusi video output. Contoh: 720.

    video_count integer

    Jumlah video output. Nilainya tetap 1.

    request_id string

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

    Kode kesalahan

    Jika panggilan model gagal dan mengembalikan pesan kesalahan, lihat Pesan kesalahan untuk menyelesaikan masalah.

    FAQ

    T: Bagaimana cara menghasilkan video dengan rasio aspek tertentu, seperti 3:4?

    J: Rasio aspek video output ditentukan oleh materi input (gambar frame pertama atau klip video pertama). Namun, rasio aspek output tidak dijamin persis sama dengan rasio input. Misalnya, mungkin tidak tepat 3:4. Deviasi kecil dapat terjadi.

    Contoh berikut menjelaskan logikanya menggunakan "gambar frame pertama input":

    • Mengapa terjadi bias?

      • Logika eksekusi: Sistem menggunakan rasio aspek gambar input sebagai referensi dasar. Ini dikombinasikan dengan total piksel target dari tier resolution. Lebar dan tinggi video harus merupakan kelipatan 16 karena spesifikasi pengkodean video. Sistem secara otomatis menyesuaikan ke resolusi valid terdekat.

      • Contoh perhitungan: Gambar frame pertama input berukuran 750 × 1000 piksel (rasio aspek 3:4 = 0,75). Resolusi diatur ke "720P" (dengan target sekitar 920.000 total piksel). Resolusi video output aktual adalah 816 × 1104 piksel (rasio aspek ≈ 0,739, total piksel sekitar 900.000).

    • Rekomendasi:

      • Kontrol input: Gunakan frame pertama atau klip video yang sesuai dengan rasio aspek target Anda.

      • Pasca-pemrosesan: Jika Anda memiliki persyaratan rasio aspek yang ketat, gunakan tool editing untuk memotong video atau menambahkan bar hitam setelah pembuatan.

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

    J: Video yang dihasilkan model disimpan di OSS. API mengembalikan URL publik sementara. Untuk mengonfigurasi daftar putih firewall untuk URL unduh 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.