Referensi API video berbasis referensi Vidu - Alibaba Cloud Model Studio

Model video berbasis referensi Vidu menggunakan gambar referensi dan prompt teks. Model menggabungkan subjek dari gambar ke dalam adegan yang dijelaskan prompt untuk menghasilkan video yang mulus.

Catatan penggunaan

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

Pilih model: Pastikan wilayah tempat model Anda berada.
Pilih URL: Pilih URL endpoint yang sesuai. URL HTTP maupun DashScope SDK didukung.
Konfigurasikan API key: Pilih wilayah, dapatkan API key, lalu konfigurasikan API key sebagai variabel lingkungan.

CatatanContoh kode dalam topik ini berlaku untuk wilayah Singapura.

Panggilan HTTP

Karena tugas video berbasis referensi biasanya memerlukan 1 hingga 5 menit, API menggunakan panggilan asinkron. Prosesnya terdiri dari dua langkah utama: "Buat tugas -> Lakukan polling hasil".

Langkah 1: Buat tugas

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

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 permintaan

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)

Model yang digunakan. Nilai yang valid:

vidu/viduq3-ad_reference2video
vidu/viduq3-drama_reference2video
vidu/viduq3-mix_reference2video

Panduan pemilihan model

Video iklan: Gunakan viduq3-ad. Dirancang untuk industri periklanan, model ini menyediakan transisi shot cerdas untuk pemasaran, gerakan kamera, dan output audio langsung. Unggah gambar produk untuk membuat video iklan.
Drama premium / komik AI: Gunakan viduq3-drama. Konsistensi karakter yang kuat, efek yang halus, dan ekspresi emosi yang realistis menjadikannya ideal untuk produksi konten naratif.
Penggunaan umum: Gunakan viduq3-mix. Kualitas visual dan efek dinamis yang seimbang cocok untuk sebagian besar skenario video berbasis referensi.

input object (wajib)

Input dasar yang mencakup gambar referensi dan prompt.

Properti

prompt string (wajib)

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

Bahasa Mandarin dan Inggris didukung. Panjang maksimum adalah 5.000 karakter. Teks yang melebihi batas otomatis dipotong.

Contoh: Seorang pria duduk di kursi dekat jendela sebuah kafe, memegang gitar dan memainkan lagu folk country Amerika yang menenangkan.

media array (wajib)

Daftar aset media yang menentukan materi referensi untuk pembuatan video.

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

Properti elemen

type string (wajib)

Jenis aset media. Nilai yang valid bergantung pada model yang dipilih.

Sediakan hanya gambar referensi

Model yang didukung: vidu/viduq3-ad_reference2video, vidu/viduq3-drama_reference2video, vidu/viduq3-mix_reference2video

Nilainya tetap sebagai berikut:

image: Gambar referensi.

Batas aset: 1 hingga 7 gambar.

url string (wajib)

URL aset media.

Sediakan gambar (type=image)

URL gambar referensi. URL harus dapat diakses publik.

Protokol HTTP dan HTTPS didukung.
Contoh: https://xxx/xxx.png

Batas gambar:

Format: JPEG, JPG, PNG, dan WEBP.
Rasio aspek: 1:4 hingga 4:1.
Ukuran file: Maksimum 50 MB.

parameters object (wajib)

Parameter pembuatan video, seperti resolusi dan durasi video.

Properti

resolution string (opsional)

PentingResolusi memengaruhi penagihan secara langsung. Sebelum memanggil API, periksa harga model.

Resolusi video yang dihasilkan. Nilai yang valid bergantung pada model yang dipilih:

vidu/viduq3-ad_reference2video: 720P atau 1080P. Default: 720P.
vidu/viduq3-drama_reference2video: 720P atau 1080P. Default: 1080P.
vidu/viduq3-mix_reference2video: 720P atau 1080P. Default: 720P.

size string (opsional)

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

Nilai default bergantung pada resolution:

Jika resolution=720P, nilai default size adalah 1280*720.
Jika resolution adalah 1080P, nilai default size adalah 1920*1080.

Rasio aspek yang didukung berbeda menurut model:

vidu/viduq3-drama_reference2video: Hanya 16:9 dan 9:16 yang didukung.
Model lain: 16:9, 4:3, 1:1, 3:4, dan 9:16 didukung.

Nilai size yang valid menurut tingkat resolusi:

720P
- 16:9: 1280*720
- 4:3: 1280*960
- 1:1: 1280*1280
- 3:4: 960*1280
- 9:16: 720*1280
1080P
- 16:9: 1920*1080
- 4:3: 1920*1440
- 1:1: 1920*1920
- 3:4: 1440*1920
- 9:16: 1080*1920

duration integer (wajib)

PentingDurasi memengaruhi penagihan secara langsung, yang dihitung per detik. Sebelum memanggil API, periksa harga model.

Durasi video yang dihasilkan, dalam detik.

vidu/viduq3-ad_reference2video: Bilangan bulat dalam rentang [3, 15]. Default: 5.
vidu/viduq3-drama_reference2video: Bilangan bulat dalam rentang [2, 15]. Default: 5.
- Jika jumlah shot terlalu banyak atau jauh lebih sedikit dibandingkan durasi, model dapat menyesuaikan panjang video secara otomatis untuk menjaga keutuhan cerita. Durasi video sebenarnya bisa lebih panjang atau lebih pendek daripada nilai yang ditentukan.
- Penagihan dihitung berdasarkan durasi output sebenarnya.
vidu/viduq3-mix_reference2video: Nilainya berupa bilangan bulat dalam rentang [1, 16]. Default: 5.

audio boolean (opsional)

Model yang didukung: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video.

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

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

Catatanvidu/viduq3-drama_reference2video tidak mendukung parameter ini. Secara default, model ini menghasilkan video dengan audio.

watermark boolean (opsional)

Menentukan apakah watermark ditambahkan di sudut kanan bawah video. Teks watermark ditetapkan sebagai "Content generated by AI".

false: Nilai default. Watermark tidak ditambahkan.
true: Menambahkan watermark.

seedinteger(opsional)

Seed. Rentang nilainya adalah [0, 2147483647].

Jika seed tidak ditentukan, sistem membuatnya secara acak. Untuk meningkatkan reproduktibilitas hasil, sebaiknya tetapkan nilai seed tetap.

Karena sifat probabilistik model, penggunaan seed yang sama tidak menjamin hasil identik pada setiap eksekusi.

Contoh: 12345

Iklan (hanya gambar)

Model yang didukung: vidu/viduq3-ad_reference2video.

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": "vidu/viduq3-ad_reference2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/dtnctw/ad-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/bspdpd/ad-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mhsjyy/ad-3.png"
            }
        ],
        "prompt": "A yoga pants advertisement. The product is a pair of black high-waisted yoga pants with one pocket on each side. An Asian model happily says I will never wear yoga pants without pockets again. The video remains clear, stable, and easy to understand."
    },
    "parameters": {
        "duration": 8,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Drama (hanya gambar)

Model yang didukung: vidu/viduq3-drama_reference2video.

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": "vidu/viduq3-drama_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/eelcsu/daram-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/adglrn/drama-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/fmofkp/drama-3.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mktdht/drama-4.png"
            }
        ],
        "prompt": "Hotel banquet hall. Wang Guilan (Image 3) sits on the right side of the frame. Su Wenbo (Image 1) and Xu Xiangnuan (Image 2) are in the distance on the left, making toasts. The wedding venue is packed with guests. Su Wenbo mother Wang Guilan sits at her seat, brow furrowed tightly, visibly displeased. The camera is fixed, capturing her frowning expression. The camera pushes in on Wang Guilan face - her gaze is dark, corners of her mouth turned down, showing disdain and dissatisfaction."
    },
    "parameters": {
        "duration": 9,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

Hanya gambar

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": "vidu/viduq3-mix_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe."
    },
    "parameters": {
        "duration": 5,
        "size": "1280*720",
        "resolution": "720P",
        "watermark": true
    }
}'

Parameter respons	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": "Invalid API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` Data output tugas. Properti task_id `string` ID tugas. Berlaku untuk kueri selama 24 jam. task_status `string` Status tugas. Nilai enumerasi PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
request_id `string` Pengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.

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

Langkah 2: Kueri hasil 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. Sebaiknya gunakan mekanisme polling dengan interval kueri yang wajar (misalnya 15 detik) untuk mengambil hasil.
Transisi status tugas: PENDING (dalam antrean) → RUNNING (diproses) → SUCCEEDED (berhasil) / FAILED (gagal).
Masa berlaku task_id: 24 jam. Setelah masa berlaku berakhir, hasil tidak dapat dikueri lagi dan API mengembalikan status tugas UNKNOWN.
Batas RPS: API kueri memiliki batas RPS default 20. Untuk kueri lebih sering atau notifikasi peristiwa, sebaiknya konfigurasikan callback tugas asinkron.
Operasi lainnya: Untuk operasi seperti kueri tugas batch atau pembatalan tugas, lihat Mengelola tugas asinkron.

Parameter permintaan

Header permintaan

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

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

Parameter respons

outputobject

Data output tugas.

Properti

task_id string

ID tugas. Berlaku untuk kueri selama 24 jam.

task_status string

Status tugas.

Nilai enumerasi

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.

Transisi status selama polling:

PENDING → RUNNING → SUCCEEDED atau FAILED.
Status kueri awal biasanya PENDING atau RUNNING.
Ketika status berubah menjadi SUCCEEDED, respons berisi URL video yang dihasilkan.
Jika statusnya FAILED, periksa pesan kesalahan lalu coba ulang tugas.

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_urlstring

URL video. Parameter ini hanya dikembalikan saat task_status adalah SUCCEEDED.

Video berformat MP4 (pengodean H.264). URL video berlaku selama 24 jam. 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 (hanya dihitung untuk tugas yang berhasil).

Properti

duration integer

Total durasi video yang dihasilkan, digunakan untuk penagihan.

size string

Menentukan resolusi video yang dihasilkan.

fps integer

Menentukan frame rate video yang dihasilkan. Nilainya tetap 24.

SR string

Menentukan tingkat resolusi video yang dihasilkan.

audio boolean

Menunjukkan apakah video yang dihasilkan menyertakan audio.

video_count integer

Menentukan jumlah video yang dihasilkan. Nilainya tetap 1.

reference_type string

Menentukan jenis materi referensi yang digunakan.

request_id string

Pengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.

Tugas berhasil

URL video hanya berlaku 24 jam lalu otomatis dihapus. Segera simpan video yang dihasilkan.

{
    "request_id": "8f240644-efe8-43bf-86ff-xxxxxx",
    "output": {
        "task_id": "b7e05baa-c318-440d-b293-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 15:10:42.723",
        "scheduled_time": "2026-03-27 15:10:42.754",
        "end_time": "2026-03-27 15:11:17.388",
        "orig_prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "reference_type": "image,video",
        "SR": "540"
    }
}

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

FAQ

T: Apakah `size` dan `resolution` harus diberikan bersamaan?

J: Tidak. Keduanya opsional, tetapi kami menyarankan untuk memberikan keduanya agar rasio aspek video dapat dikontrol secara presisi. Lihat Nilai size yang valid.

Jika keduanya tidak diberikan, sistem menangani permintaan sebagai berikut:

Hanya size yang diberikan: Parameter size diabaikan, dan sistem menggunakan resolution=720P default serta nilai size default yang sesuai (1280*720).

Contoh: API mengembalikan size="1280*720" dan SR=720.
Jika hanya resolution yang diberikan: Output menggunakan tingkat resolusi yang ditentukan.

Misalnya, jika resolution=540P, API mengembalikan size="960*528" dan SR=540. Jika resolution=1080P, API mengembalikan size="1920*1080" dan SR=1080.

Catatan penggunaan

Panggilan HTTP

Langkah 1: Buat tugas

Parameter permintaan

Header permintaan

Isi permintaan

Iklan (hanya gambar)

Drama (hanya gambar)

Hanya gambar

Parameter respons

Respons berhasil

Respons kesalahan

Langkah 2: Kueri hasil tugas

Parameter permintaan

Header permintaan

Parameter jalur

Kueri hasil tugas

Parameter respons

Tugas berhasil

Tugas gagal

Kueri tugas kedaluwarsa

Kode kesalahan

FAQ

T: Apakah size dan resolution harus diberikan bersamaan?

T: Apakah `size` dan `resolution` harus diberikan bersamaan?