All Products
Search

This Product

    Alibaba Cloud Model Studio:Referensi API PixVerse - video berbasis referensi

    Document Center

    Alibaba Cloud Model Studio:Referensi API PixVerse - video berbasis referensi

    Last Updated:Oct 22, 2026

    Model video berbasis referensi PixVerse menerima beberapa gambar referensi. Model menggunakan prompt teks untuk menjelaskan adegan dan menggabungkan karakter subjek dari aset ke dalam video yang mulus.

    PentingDokumen ini hanya berlaku untuk wilayah Singapura. Anda harus menggunakan API key dari wilayah ini.

    Aktifkan layanan

    1. Buka konsol Model Studio, cari PixVerse, temukan kartu model PixVerse, lalu klik Activate Now.
    2. Di jendela pop-up, konfirmasikan aktivasi dan otorisasi.

    Catatan penggunaan

    Agar panggilan API berhasil, gunakan model, URL endpoint, dan API key dari wilayah yang sama. Panggilan lintas wilayah akan gagal.

    CatatanContoh kode dalam topik ini berlaku untuk wilayah Singapura.

    Panggilan HTTP

    Pembuatan video berbasis referensi adalah tugas yang berjalan lama dan biasanya memerlukan 1 hingga 5 menit, sehingga API menggunakan panggilan asinkron. Alurnya terdiri dari dua langkah utama: "Buat tugas -> Lakukan polling hasil". Langkah-langkahnya sebagai berikut:

    Langkah 1: Buat tugas untuk mendapatkan ID tugas

    Wilayah Singapura: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

    Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

    Catatan

    • Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk mengueri hasil. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Gunakan polling untuk mengambil hasilnya.
    • Untuk panduan pemula, lihat Memanggil API dengan Postman atau cURL.

    Parameter permintaan

    Header

    Content-Type string (Wajib)

    Jenis konten permintaan. Harus application/json.

    Authorization string (Wajib)

    Mengautentikasi permintaan dengan API key Model Studio. Contoh: Bearer sk-xxxx.

    X-DashScope-Async string (Wajib)

    Mengaktifkan pemrosesan asinkron. Permintaan HTTP hanya mendukung panggilan asinkron. Harus enable.

    PentingJika header permintaan ini tidak ada, kesalahan "current user api does not support synchronous calls" dikembalikan.

    Isi permintaan

    model string (Wajib)

    Nama model. Untuk spesifikasi output model, lihat Daftar model.

    Nilai yang valid:

    • pixverse/pixverse-v6-r2v

    input object (Wajib)

    Informasi input dasar, termasuk gambar referensi dan prompt.

    Properti

    prompt string (Wajib)

    Prompt teks yang menjelaskan elemen dan karakteristik visual yang diinginkan dalam video yang dihasilkan.

    Bahasa Mandarin dan Inggris didukung. Setiap karakter bahasa Mandarin atau huruf dihitung sebagai satu karakter. Pengodean karakternya adalah UTF-8. Karakter yang melebihi batas dipotong secara otomatis.

    • pixverse/pixverse-v6-r2v: Maksimum 2.048 karakter.

    Instruksi referensi gambar: Saat Anda meneruskan gambar referensi dalam parameter media, Anda dapat langsung mereferensikannya dalam prompt menggunakan @ref_name.

    • ref_name yang diatur dalam media harus unik secara global dalam permintaan yang sama dan harus berkorespondensi satu-satu dengan referensi dalam prompt.
    • Aturan format: Anda harus menyisakan spasi setelah @ref_name sebagai pemisah.

    Contoh:

    • Prompt biasa: A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop.
    • Prompt dengan referensi: @man sits on a chair by the window, holding @guitar , playing a soothing American country folk song next to @coffeeshop .

    media array (Wajib)

    Daftar aset media yang menentukan gambar referensi yang diperlukan untuk pembuatan video.

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

    Properti elemen

    type string (Wajib)

    Jenis aset media. Nilai tetap:

    • image_url: URL gambar.

    Batas jumlah aset: Maksimum 7 gambar.

    url string (Wajib)

    URL gambar referensi. URL harus dapat diakses publik.

    Batasan gambar:

    • Format: JPG, PNG, atau WEBP.
    • Resolusi: Lebar dan tinggi gambar tidak boleh melebihi 10.000 piksel.
    • Ukuran file: Maksimum 20 MB.

    ref_name string (Opsional)

    Pengenal nama subjek dalam gambar referensi. Digunakan untuk mereferensikan gambar dalam prompt dengan @ref_name. Maksimum 30 karakter.

    parameters object (Wajib)

    Parameter pembuatan video, seperti resolusi video, durasi, dan apakah audio dihasilkan.

    Properti

    size string (Wajib)

    Resolusi video yang dihasilkan, dalam format width*height dalam piksel.

    Tabel berikut mencantumkan nilai yang valid untuk berbagai tingkat resolusi.

    Model pixverse/pixverse-v6-r2v

    Tingkat resolusi

    Rasio aspek

    Nilai size (lebar*tinggi)

    360P

    16:9

    640*360

    4:3

    640*480

    1:1

    640*640

    3:4

    480*640

    9:16

    360*640

    3:2

    640*432

    2:3

    432*640

    21:9

    640*288

    540P

    16:9

    1024*576

    4:3

    1024*768

    1:1

    1024*1024

    3:4

    768*1024

    9:16

    576*1024

    3:2

    1024*688

    2:3

    688*1024

    21:9

    1024*448

    720P

    16:9

    1280*720

    4:3

    1108*832

    1:1

    960*960

    3:4

    832*1108

    9:16

    720*1280

    3:2

    1200*800

    2:3

    800*1200

    21:9

    1280*560

    1080P

    16:9

    1920*1080

    4:3

    1664*1248

    1:1

    1440*1440

    3:4

    1248*1664

    9:16

    1080*1920

    3:2

    1776*1184

    2:3

    1184*1776

    21:9

    1920*832

    Contoh: 1280*720.

    duration integer (Wajib)

    PentingParameter duration memengaruhi biaya secara langsung. Sebelum memanggil API, periksa harga PixVerse - video berbasis referensi.

    Durasi video yang dihasilkan, dalam detik.

    • pixverse/pixverse-v6-r2v: Bilangan bulat dalam rentang [1, 15].

    Contoh: 5.

    audio boolean (Opsional)

    PentingParameter audio memengaruhi biaya secara langsung. Sebelum memanggil API, periksa harga PixVerse - video berbasis referensi.

    Menentukan apakah video dihasilkan dengan audio. Jika diaktifkan, model secara otomatis menghasilkan musik latar atau efek suara yang sesuai berdasarkan konten video.

    • false: Nilai default. Menghasilkan video tanpa suara.
    • true: Menghasilkan video dengan audio.

    Contoh: false.

    watermark boolean (Opsional)

    Menentukan apakah watermark ditambahkan. Watermark ditempatkan di sudut kanan bawah video dengan teks tetap "AI Generated".

    • false: Nilai default. Tidak menambahkan watermark.
    • true: Menambahkan watermark.

    Contoh: false.

    seed integer (Opsional)

    Seed bilangan acak harus berupa bilangan bulat dalam rentang [0, 2147483647].

    Jika tidak ditentukan, seed acak akan dibuat. Seed tetap meningkatkan reproduktibilitas.

    Karena pembuatan oleh model bersifat probabilistik, seed yang sama tidak menjamin hasil identik.

    Video berbasis referensi

    Teruskan gambar referensi melalui media, lalu atur size dan duration untuk mengontrol resolusi dan durasi video.

    # Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

    Video berbasis referensi (menggunakan ref_name)

    Teruskan gambar referensi dalam media, lalu teruskan ref_name untuk mengatur nama subjek setiap gambar referensi.

    # Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg",
                "ref_name": "man"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
                "ref_name": "guitar"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
                "ref_name": "coffeeshop"
            }
        ],
        "prompt": "@man sits on a chair by the window, holding @guitar , playing a soothing American country folk song next to @coffeeshop "
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

    Parameter respons

    output object

    Informasi output tugas.

    Properti

    task_id string

    ID tugas. Berlaku untuk kueri selama 24 jam.

    task_status string

    Status tugas.

    Nilai enumerasi

    • PENDING: Tugas dalam antrean.
    • RUNNING: Tugas sedang diproses.
    • SUCCEEDED: Tugas berhasil.
    • FAILED: Tugas gagal.
    • CANCELED: Tugas dibatalkan.
    • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

    request_id string

    Pengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.

    code string

    Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

    message string

    Pesan kesalahan terperinci. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

    Respons berhasil

    Simpan task_id untuk mengueri 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.

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

    Langkah 2: Kueri hasil berdasarkan ID tugas

    Wilayah Singapura: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

    Catatan

    • Rekomendasi polling: Pembuatan video dapat memerlukan beberapa menit. Gunakan mekanisme polling dan lakukan polling hasil dengan interval yang wajar, misalnya setiap 15 detik.
    • Alur status tugas: PENDING (dalam antrean) → RUNNING (diproses) → SUCCEEDED (berhasil) / FAILED (gagal).
    • Masa berlaku ID tugas: task_id berlaku selama 24 jam. Setelah itu, kueri akan gagal dan API mengembalikan status tugas UNKNOWN.
    • Batas RPS: Endpoint kueri memiliki batas default 20 RPS. Untuk kueri berfrekuensi tinggi atau notifikasi peristiwa, konfigurasikan callback tugas asinkron.
    • Operasi lainnya: Untuk melakukan kueri batch, membatalkan tugas, atau operasi lain, lihat Mengelola tugas asinkron.

    Parameter permintaan

    Header

    Authorization string (Wajib)

    Mengautentikasi permintaan dengan API key Model Studio. Contoh: Bearer sk-xxxx.

    Parameter jalur

    task_id string (Wajib)

    ID tugas.

    Kueri hasil tugas

    Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

    curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

    Parameter respons

    output object

    Informasi output tugas.

    Properti

    task_id string

    ID tugas. Berlaku untuk kueri selama 24 jam.

    task_status string

    Status tugas.

    Nilai enumerasi

    • PENDING: Tugas dalam antrean.
    • RUNNING: Tugas sedang diproses.
    • SUCCEEDED: Tugas berhasil.
    • FAILED: Tugas gagal.
    • CANCELED: Tugas dibatalkan.
    • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
    Transisi status selama polling:
    • PENDING (dalam antrean) → RUNNING (diproses) → SUCCEEDED (berhasil) / FAILED (gagal).
    • Status kueri awal biasanya PENDING (dalam antrean) atau RUNNING (diproses).
    • Ketika status berubah menjadi SUCCEEDED, respons berisi URL video yang dihasilkan.
    • Jika statusnya FAILED, periksa pesan kesalahan lalu coba lagi.
    • Jika statusnya CANCELED, tugas telah dibatalkan. Untuk melanjutkan, kirim ulang tugas.
    • Jika statusnya UNKNOWN, tugas tidak ada atau statusnya tidak diketahui. Hal ini dapat terjadi jika task_id tidak ada atau telah melewati masa berlaku 24 jam.

    submit_time string

    Waktu tugas dikirim. Format: YYYY-MM-DD HH:mm:ss.SSS.

    scheduled_time string

    Waktu tugas dijalankan. Format: YYYY-MM-DD HH:mm:ss.SSS.

    end_time string

    Waktu tugas selesai. Format: YYYY-MM-DD HH:mm:ss.SSS.

    video_url string

    URL video. Hanya dikembalikan saat task_status adalah SUCCEEDED.

    Format video adalah MP4 (pengodean H.264). Saat ini tautan video tidak kedaluwarsa, tetapi jangan mengandalkannya untuk penyimpanan jangka panjang. Segera unduh video.

    orig_prompt string

    Prompt input asli, sesuai parameter permintaan prompt.

    code string

    Kode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

    message string

    Pesan kesalahan terperinci. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.

    usage object

    Statistik penggunaan output, hanya dihitung untuk tugas yang berhasil.

    Properti

    duration integer

    Total durasi video yang dihasilkan, digunakan untuk penagihan.

    size string

    Resolusi video yang dihasilkan.

    fps integer

    Frame rate video yang dihasilkan.

    SR string

    Tingkat resolusi video yang dihasilkan.

    audio boolean

    Menunjukkan apakah video yang dihasilkan memiliki audio.

    video_count integer

    Jumlah video yang dihasilkan. Nilainya tetap 1.

    request_id string

    Pengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.

    Tugas berhasil

    {
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-10 15:03:25.848",
        "scheduled_time": "2026-03-10 15:03:25.884",
        "end_time": "2026-03-10 15:04:05.882",
        "orig_prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

    Tugas gagal

    Saat tugas gagal, task_status adalah FAILED, disertai kode dan pesan kesalahan. Lihat Kode kesalahan.

    {
    "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 itu, kueri mengembalikan kesalahan berikut.

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

    Kode kesalahan

    Jika panggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk mengatasinya.

    FAQ

    T: Bagaimana cara mengoptimalkan hasil jika prompt tidak bekerja dengan baik?

    J: Coba gunakan @ref_name sebagai alternatif.

    • Metode default: Gunakan prompt secara langsung. Model secara otomatis mengurai konten gambar referensi secara global, yang cocok untuk sebagian besar skenario umum.
    • Metode alternatif: Jika hasil yang dihasilkan menyimpang dari harapan Anda, gunakan @ref_name untuk menentukan gambar referensi dalam prompt guna meningkatkan hasil.

    T: Bagaimana cara menggunakan ref_name?

    J: ref_name membuat ikatan antara gambar referensi dan prompt. Setelah Anda mengatur ref_name untuk gambar dalam array media, Anda dapat mereferensikan subjek yang sesuai dari gambar referensi dalam prompt menggunakan sintaks @ref_name.

    • Misalnya, jika Anda mengatur "ref_name": "kitten" dalam media, gunakan @kitten dalam prompt untuk mereferensikan subjek tersebut. Catatan: Anda harus menyisakan spasi setelah @kitten.
    • Contoh: @kitten and @puppy are playing on the grass.