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

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

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

Aktifkan layanan

Buka konsol Model Studio, cari PixVerse, temukan kartu model PixVerse, lalu klik Activate Now.
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.

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

CatatanContoh kode dalam topik ini berlaku untuk wilayah Singapura.

Panggilan HTTP

Pembuatan video dari gambar 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.

Nilai yang valid:

pixverse/pixverse-v6-it2v

input object (Wajib)

Informasi input dasar, seperti prompt dan aset media.

Properti

prompt string (Opsional)

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-it2v: Maksimum 5.000 karakter.

media array (Wajib)

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

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

Properti

type string (Wajib)

Jenis aset media. Nilai tetap:

image_url: URL gambar.

Batas aset: Sebaiknya sediakan satu gambar.

Jika Anda menyediakan beberapa gambar, sistem menggunakan gambar terakhir secara default. Untuk memastikan hasil yang diharapkan, selalu sediakan hanya satu gambar.

url string (Wajib)

URL file gambar. URL harus dapat diakses publik.

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

Batasan gambar:

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

parameters object (Wajib)

Parameter pemrosesan video, seperti resolusi video, durasi video, pembuatan audio, dan watermark.

Properti

resolution string (Wajib)

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

Menentukan tingkat resolusi video yang dihasilkan.

Nilai yang valid: 360P, 540P, 720P, dan 1080P.

duration integer (Wajib)

PentingParameter duration memengaruhi biaya secara langsung, yang ditagihkan per detik. Sebelum memanggil API, periksa harga model.

Durasi video yang dihasilkan, dalam detik.

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

audio boolean (Opsional)

PentingParameter audio memengaruhi biaya secara langsung. Sebelum memanggil API, periksa harga model.

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.

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.

shot_type string (Opsional)

Model yang didukung: pixverse/pixverse-v6-it2v.

Menentukan jenis shot video yang dihasilkan. Parameter ini mengontrol apakah video terdiri dari satu shot berkelanjutan atau beberapa shot.

single: Nilai default. Menghasilkan video satu shot.
multi: Multi-shot. Sistem membagi shot secara cerdas.

Saran penggunaan: Parameter prompt memiliki prioritas lebih tinggi daripada shot_type. Untuk hasil terbaik, sebaiknya pengaturan parameter ini konsisten dengan deskripsi prompt.

Untuk selalu menghasilkan video satu shot: Atur shot_type="single" dan jelaskan adegan satu shot dalam prompt.
Untuk selalu menghasilkan video multi-shot: Atur shot_type="multi" dan jelaskan adegan multi-shot dalam prompt.

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

Model yang didukung: pixverse/pixverse-v6-it2v.

# 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-it2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible."
    },
    "parameters": {
        "resolution": "720P",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

Gambar ke video (multi-shot)

Model yang didukung: pixverse/pixverse-v6-it2v.

Jelaskan adegan multi-shot dalam prompt dan atur shot_type ke multi untuk menghasilkan video multi-shot dengan audio.

# 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-it2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260121/zlpocv/wan-i2v-haigui.webp"
            }
        ],
        "prompt": "Shot 1: The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible. Shot 2: A long shot of the sea turtle surrounded by seaweed, which is also swaying from side to side."
    },
    "parameters": {
        "resolution": "720P",
        "duration": 8,
        "shot_type": "multi",
        "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.

shot_type string

Jenis shot video yang dihasilkan.

request_id string

Pengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.

Tugas berhasil

{
    "request_id": "7df19cf7-d76c-4bb8-b4c5-xxxxxx",
    "output": {
        "task_id": "5abf2c85-ea81-4cbf-8918-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 11:48:50.499",
        "scheduled_time": "2026-03-20 11:48:50.551",
        "end_time": "2026-03-20 11:49:46.462",
        "orig_prompt": "The camera slowly moves up from below the sea turtle. The sea turtle swims leisurely, and the details of its belly are clearly visible.",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "shot_type": "single",
        "size": "992*944",
        "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.