Referensi API Vidu - gambar ke video dari bingkai awal - Alibaba Cloud Model Studio

Model gambar ke video Vidu menghasilkan video yang mulus dari gambar input dan prompt teks.

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

Pembuatan video dari gambar biasanya memerlukan 1 hingga 5 menit, sehingga API menggunakan model asinkron. Alurnya terdiri dari dua langkah utama: buat tugas, lalu lakukan polling hasilnya.

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

Content-Type string (Wajib)

Jenis konten permintaan. Harus application/json.

Content-Type string (Wajib)

Jenis konten permintaan. Harus application/json.

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. Nilai yang valid:

vidu/viduq2-pro-fast_img2video

input object (Wajib)

Input dasar, termasuk prompt teks dan aset media.

Properti

prompt string (Opsional)

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

Panjang maksimum adalah 5.000 karakter (karakter bahasa Mandarin dan huruf bahasa Inggris masing-masing dihitung satu). Teks yang melebihi batas dipotong.

media array (Wajib)

Daftar aset media yang menentukan gambar untuk pembuatan video.

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

Properti

type string (Wajib)

Jenis aset media. Harus diatur ke nilai tetap berikut:

image: URL gambar.

Batas aset: Anda harus menyediakan tepat satu aset gambar.

url string (Wajib)

URL file gambar, yang harus dapat diakses publik.

Protokol yang didukung: HTTP atau HTTPS.
Contoh: https://example.com/image.jpg.

Batasan gambar:

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

parameters object (Opsional)

Parameter pemrosesan video, seperti resolusi dan durasi.

Properti

resolution string (Opsional)

PentingPengaturan resolution memengaruhi biaya secara langsung. Sebelum memanggil API, periksa harga model.

Menentukan tingkat resolusi video yang dihasilkan.

Model menyesuaikan skala video ke jumlah piksel yang mendekati tingkat pilihan sambil mempertahankan rasio aspek gambar input.

Nilai yang valid adalah 720P dan 1080P. Default: 720P.

duration integer (Opsional)

PentingPengaturan duration memengaruhi biaya secara langsung, yang ditagihkan per detik. Durasi lebih lama meningkatkan biaya. Sebelum memanggil API, periksa harga model.

Durasi video yang dihasilkan, dalam detik.

Bilangan bulat dalam rentang [1, 10]. Default: 5.

audio boolean (Opsional)

watermark boolean (Opsional)

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

false: (Default) Tidak menambahkan watermark.
true: Menambahkan watermark.

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.

Gambar ke video

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/viduq2-pro-fast_img2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible."
    },
    "parameters": {
        "duration": 5,
        "resolution": "720P",
        "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
RUNNING
SUCCEEDED
FAILED
CANCELED
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": "Invalid API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Langkah 2: Kueri hasil

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

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

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

end_time string

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

orig_prompt string

URL video. Hanya dikembalikan saat task_status adalah SUCCEEDED.

Format video adalah MP4 (pengodean H.264). Tautan 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 output, hanya dihitung untuk tugas yang berhasil.

Properti

duration integer

Total durasi video yang ditagihkan, dalam detik.

output_video_durationinteger

Durasi video output, dalam detik.

size string

Resolusi video output.

fps integer

Frame rate video output. Tetap pada 24.

SR string

Tingkat resolusi video output.

audio boolean

Menunjukkan apakah output berupa video dengan audio.

video_count integer

Jumlah video output. Tetap pada 1.

request_id string

Pengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.

Tugas berhasil

{
    "request_id": "3606f9f4-b833-44ec-8385-xxxxxx",
    "output": {
        "task_id": "2846881f-0496-4288-947f-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 14:25:32.057",
        "scheduled_time": "2026-03-27 14:25:32.084",
        "end_time": "2026-03-27 14:28:29.600",
        "orig_prompt": "The camera slowly pans up from below a sea turtle that is swimming leisurely, with clear details of its belly visible.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxxx"
    },
    "usage": {
        "duration": 5,
        "size": "990*932",
        "output_video_duration": 5,
        "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, lihat Pesan Kesalahan untuk mengatasi kesalahan.