Skip to main content

Referensi API PixVerse - teks ke video

Model teks ke video PixVerse menghasilkan video yang mulus berdasarkan prompt teks.

Dokumen 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.
Contoh kode dalam topik ini berlaku untuk wilayah Singapura.

Panggilan HTTP

Pembuatan video dari teks 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.
  • 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.
Jika 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-t2v
input object (Wajib)Informasi input dasar, seperti 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-t2v: Maksimum 5.000 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.
Parameter size memengaruhi biaya secara langsung. Sebelum memanggil API, periksa harga model.
Tabel berikut mencantumkan nilai yang valid untuk berbagai tingkat resolusi dan rasio aspek.

Model pixverse/pixverse-v6-t2v

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

duration integer (Wajib)
Parameter duration memengaruhi biaya secara langsung, yang ditagihkan per detik. Sebelum memanggil API, periksa harga model.
Durasi video yang dihasilkan, dalam detik.
  • pixverse/pixverse-v6-t2v: Bilangan bulat dalam rentang [1, 15].
audio boolean (Opsional)
Parameter 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-t2v.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.
  • Teks ke video
  • Teks ke video (multi-shot)
Model yang didukung: pixverse/pixverse-v6-t2v.
# 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-t2v",
    "input": {
        "prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame."
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "watermark": true
    }
}'

Parameter respons

output objectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus 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 stringPengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan terperinci. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.
  • Respons berhasil
  • Respons kesalahan
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"
}

Langkah 2: Kueri hasil berdasarkan ID tugas

Wilayah Singapura: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • 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 objectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus 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 stringWaktu tugas dikirim. Format: YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu tugas dijalankan. Format: YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu tugas selesai. Format: YYYY-MM-DD HH:mm:ss.SSS.video_url stringURL video. Hanya dikembalikan saat task_status adalah SUCCEEDED.Format video adalah MP4 (pengodean H.264). Saat ini tautan video tidak kedaluwarsa, tetapi tidak ditujukan untuk penyimpanan jangka panjang. Segera unduh video.orig_prompt stringPrompt input asli, sesuai parameter permintaan prompt.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan terperinci. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.
usage objectStatistik penggunaan output, hanya dihitung untuk tugas yang berhasil.

Properti

duration integerTotal durasi video yang dihasilkan dalam detik, digunakan untuk penagihan.size stringResolusi video yang dihasilkan.fps integerFrame rate video yang dihasilkan.SR stringTingkat resolusi video yang dihasilkan.audio booleanMenunjukkan apakah video yang dihasilkan memiliki audio.video_count integerJumlah video yang dihasilkan. Nilainya tetap 1.shot_type stringJenis shot video yang dihasilkan.
request_id stringPengidentifikasi permintaan unik untuk pelacakan dan pemecahan masalah.
  • Tugas berhasil
  • Tugas gagal
  • Kueri tugas kedaluwarsa
{
    "request_id": "19171ea5-9efb-4d35-93a1-xxxxxx",
    "output": {
        "task_id": "7ed706b7-a9a9-4319-820c-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-20 10:34:41.630",
        "scheduled_time": "2026-03-20 10:34:41.655",
        "end_time": "2026-03-20 10:35:12.725",
        "orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "shot_type": "single",
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

Panggilan DashScope SDK

Nama parameter dalam SDK sebagian besar konsisten dengan API HTTP. Struktur parameter disesuaikan dengan fitur setiap bahasa pemrograman. Karena tugas teks ke video memerlukan waktu lama (biasanya 1 hingga 5 menit), SDK merangkum proses panggilan asinkron HTTP dan mendukung metode panggilan sinkron maupun asinkron.
Waktu aktual yang diperlukan bergantung pada jumlah tugas dalam antrean dan status eksekusi layanan. Harap bersabar menunggu hasilnya.

Panggilan SDK Python

Pastikan versi DashScope Python SDK Anda tidak lebih lama dari 2.0.1 sebelum menjalankan kode berikut.Versi yang lebih lama dapat memicu kesalahan seperti "url error, please check url!". Untuk memperbarui SDK, lihat Instal SDK.
Wilayah Singapura: region="ap-southeast-1" Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
  • Panggilan sinkron
  • Panggilan asinkron
Contoh permintaan
import os
import dashscope
from dashscope.v2 import DashScopeError

# Berikut adalah konfigurasi untuk wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
    # Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan kunci API Model Studio Anda: api_key="sk-xxx"
    # Kunci API berbeda tiap wilayah. Dapatkan kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

def sample_sync_call_t2v():
    # Panggil API sinkron, yang mengembalikan hasil secara langsung.
    print('please wait...')
    # generate adalah panggilan satu langkah (kirim tugas dan tunggu hingga selesai) serta mengembalikan Job yang telah selesai
    # audio bukan bagian dari signature bernama, diteruskan melalui parameters
    try:
        job = client.videos.generate(model='pixverse/pixverse-v6-t2v',
                                     prompt='In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.',
                                     size='1280*720',
                                     duration=5,
                                     watermark=False,
                                     parameters={'audio': False})
        print(job)
        print(job.video_url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_t2v()
Contoh respons
Saat ini video_url tidak kedaluwarsa, tetapi tidak ditujukan untuk penyimpanan jangka panjang. Segera unduh video.
{
    "request_id": "2b68d32e-86c8-4383-8a18-xxxxxx",
    "task_id": "ec40bb42-02d4-44d8-bf35-xxxxxx",
    "status": "SUCCEEDED",
    "results": [
        {
            "video_url": "https://media.pixverseai.cn/xxx.mp4"
        }
    ],
    "task_metrics": {
        "TOTAL": 1,
        "SUCCEEDED": 1,
        "FAILED": 0
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "size": "1280x720",
        "fps": 24,
        "audio": false,
        "SR": "720"
    }
}

Panggilan SDK Java

Pastikan versi DashScope Java SDK Anda tidak lebih lama dari 2.22.6 sebelum menjalankan kode berikut.Versi yang lebih lama dapat memicu kesalahan seperti "url error, please check url!". Untuk memperbarui SDK, lihat Instal SDK.
Wilayah Singapura: Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"; Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
  • Panggilan sinkron
  • Panggilan asinkron
Contoh permintaan
// Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;

public class Text2Video {

    static {
        // Berikut adalah URL untuk wilayah Singapura.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan API key Model Studio Anda: api_key="sk-xxx"
    // Untuk mendapatkan API key, lihat https://www.alibabacloud.com/help/model-studio/get-api-key
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Buat tugas sintesis video dan tunggu hingga tugas selesai.
     */
    public static void text2Video() throws ApiException, NoApiKeyException, InputRequiredException {
        VideoSynthesis vs = new VideoSynthesis();
        VideoSynthesisParam param =
                VideoSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("pixverse/pixverse-v6-t2v")
                        .prompt("In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.")
                        .size("1280*720")
                        .duration(5)
                        .audio(true)
                        .watermark(true)
                        .seed(12345)
                        .build();
        System.out.println("please wait...");
        VideoSynthesisResult result = vs.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            text2Video();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}
Contoh respons
Saat ini video_url tidak kedaluwarsa, tetapi tidak ditujukan untuk penyimpanan jangka panjang. Segera unduh video.
{
    "request_id": "bd1109bd-6c63-4e62-8bb8-xxxxxx",
    "output": {
        "task_id": "72af7c13-dad5-4aaa-b85d-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://media.pixverseai.cn/xxx.mp4",
        "orig_prompt": "In a rainy cyber city, a raccoon walks on a railing. Suddenly, its eyes glow blue, and it transforms into a high-tech drone, flying quickly out of the frame.",
        "submit_time": "2026-03-20 11:21:13.227",
        "scheduled_time": "2026-03-20 11:21:13.252",
        "end_time": "2026-03-20 11:21:43.924"
    },
    "usage": {
        "video_count": 1,
        "duration": 5.0,
        "size": "1280*720",
        "input_video_duration": 0.0,
        "output_video_duration": 0.0,
        "SR": "720"
    },
    "status_code": 200,
    "code": "",
    "message": ""
}

Kode kesalahan

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