Referensi API Pembuatan Gambar Vidu - Alibaba Cloud Model Studio

Model Pembuatan Gambar Vidu mendukung tugas teks-ke-gambar, pengeditan gambar, dan gambar referensi-ke-gambar.

Ikhtisar Model

Model	Kemampuan	Modalitas Input	Spesifikasi Gambar Output
vidu/vidu-image_reference2image	Pembuatan gambar referensi, teks-ke-gambar, pengeditan gambar. Rendering teks bahasa Mandarin dan Inggris yang presisi, restorasi tingkat piksel untuk UI/grafik dan detail desain. Ideal untuk poster, infografis, dll.	Teks, Gambar	Resolusi: 1K, 2K, 4K Jumlah gambar: 1 Format gambar: PNG

Model

Kemampuan

Modalitas Input

Spesifikasi Gambar Output

vidu/vidu-image_reference2image

Pembuatan gambar referensi, teks-ke-gambar, pengeditan gambar. Rendering teks bahasa Mandarin dan Inggris yang presisi, restorasi tingkat piksel untuk UI/grafik dan detail desain. Ideal untuk poster, infografis, dll.

Teks, Gambar

Resolusi: 1K, 2K, 4K

Jumlah gambar: 1

Format gambar: PNG

Prasyarat

Aktifkan layanan: Buka konsol Model Studio, cari "Vidu", temukan kartu model yang sesuai, dan klik Activate Now untuk mengonfirmasi aktivasi dan otorisasi di jendela pop-up.
Konfigurasi API Key: Pilih wilayah dan Dapatkan kunci API.

Panggilan HTTP

Tugas pembuatan gambar memerlukan waktu tertentu dan API menggunakan panggilan asinkron. Proses ini melibatkan "Buat Tugas -> Polling Hasil" dua langkah inti, sebagai berikut:

Langkah 1: Kirim Tugas Pembuatan Gambar

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

Parameter Permintaan

Header

Content-Type string (Wajib)

Jenis konten permintaan. Harus berupa application/json.

Authorization string (Wajib)

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

X-DashScope-Async string (Wajib)

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

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

Body Permintaan

model string (Wajib)

Nama model. Nilai yang tersedia:

vidu/vidu-image_reference2image

input object (Wajib)

Objek parameter input yang berisi bidang berikut:

Properti

messages array (Wajib)

Daftar pesan. Server mengekstrak text tidak kosong pertama sebagai prompt dan mengekstrak semua bidang image sebagai gambar referensi. Array berisi tepat satu objek dengan properti role dan content.

Properti

rolestring (Opsional)

Peran pesan. Nilai yang disarankan: user.

contentarray (Wajib)

Konten pesan, berisi prompt teks (text) dan gambar referensi opsional (image, mendukung banyak gambar).

Properti

textstring(Wajib Bersyarat)

Prompt positif yang mendeskripsikan konten, gaya, dan komposisi gambar yang diinginkan.

Mendukung bahasa Mandarin dan Inggris. Panjang maksimum adalah 5,000 karakter, di mana setiap karakter (Mandarin, huruf, angka, atau simbol) dihitung sebagai satu.

Contoh: Kucing oranye yang sedang duduk dengan ekspresi bahagia, lincah dan lucu, realistis dan akurat.

Catatan: Setidaknya satu teks yang tidak kosong wajib ada dalam pesan.

image string (Opsional)

URL gambar referensi. Beberapa gambar didukung. Semua model mendukung hingga 14 gambar referensi.

Mendukung protokol HTTP atau HTTPS.
Contoh: https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png.

Batasan gambar:

Format: PNG, JPG, WEBP.
Rasio aspek: Antara 1:4 dan 4:1.
Ukuran file: Total ukuran semua gambar tidak boleh melebihi 50 MB.
Jumlah: Hingga 14 gambar referensi.

parameters object (Opsional)

Parameter pembuatan gambar.

Properti

size string (Opsional)

Ukuran gambar dalam format width*height (misalnya, 2048*2048). Defaultnya adalah 1024*1024 jika tidak ditentukan.

Lihat bagian Ukuran Gambar yang Didukung di bawah ini untuk daftar ukuran yang didukung per model.

n integer (Opsional)

Jumlah gambar yang akan dibuat. Saat ini hanya 1 yang didukung. Nilai lain akan mengembalikan kesalahan parameter.

seed integer (Opsional)

Seed angka acak. Rentang yang valid: [0,2147483647]. 0 berarti acak.

Menggunakan seed yang sama menghasilkan output yang serupa. Jika diabaikan, algoritme akan menggunakan seed acak.

watermark bool (Opsional)

Apakah akan menambahkan watermark.

false: Default. Tanpa watermark.
true: Tambahkan watermark.

Teks-ke-Gambar

Didukung oleh semua model Vidu.

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "A flower shop with exquisite windows, a beautiful wooden door, displaying flowers"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1,
        "watermark": false
    }
}'

Gambar Referensi-ke-Gambar

Didukung oleh semua model Vidu. Hingga 14 gambar referensi dapat disediakan.

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "vidu/vidu-image_reference2image",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Following the style of the reference image, generate a sitting orange cat"
                    },
                    {
                        "image": "https://cdn.wanx.aliyuncs.com/tmp/pressure/umbrella1.png"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "size": "2048*2048",
        "n": 1,
        "watermark": false
    }
}'

Parameter Respons

request_id string

Identifier permintaan unik untuk pelacakan dan pemecahan masalah.

code string

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

message string

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

Respons berhasil

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

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

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 gambar memerlukan waktu. Disarankan untuk menggunakan mekanisme polling dengan interval kueri yang wajar (misalnya, 5 detik) untuk mendapatkan hasil.
Alur status tugas: PENDING (menunggu) → RUNNING (memproses) → SUCCEEDED (berhasil) / FAILED (gagal).
Validitas tautan gambar: Tautan unduhan untuk gambar yang dibuat berlaku selama 24 jam. Harap unduh dan simpan gambar segera.

Parameter Permintaan

Header

Authorization string (Wajib)

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

task_id string (Wajib)

ID tugas.

Kueri Hasil Tugas

# Singapore region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
curl --location --request 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.

choices array

Daftar kandidat output gambar, hanya dikembalikan saat task_status=SUCCEEDED.

Properti

finish_reason string

Alasan penyelesaian. Biasanya stop saat berhasil.

message object

Pesan yang dikembalikan oleh model.

Properti

rolestring

Peran pesan, ditetapkan sebagai assistant.

contentarray

Properti

type string

Jenis konten output, ditetapkan sebagai image.

image string

Tautan unduhan untuk gambar yang dibuat dalam format PNG. Tautan ini berlaku selama 24 jam. Harap unduh dan simpan gambar segera.

finished bool

Apakah tugas telah selesai, hanya dikembalikan saat task_status=SUCCEEDED.

usage object

Informasi penggunaan sumber daya. Hanya menghitung hasil yang berhasil.

Properti

image_count integer

Jumlah gambar yang dihasilkan.

size string

Resolusi gambar yang dihasilkan dalam format width*height. Contoh: 2048*2048.

SR string

Tingkat resolusi gambar yang dihasilkan. Contoh: 2K.

request_id string

Identifier permintaan unik untuk pelacakan dan pemecahan masalah.

code string

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

message string

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

Tugas Berhasil

{
    "request_id": "f584a817-6e00-9841-961a-49f7382a03d4",
    "output": {
        "task_id": "6404d4ec-4cdf-45b5-8d7d-3d429c6baed5",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-07-13 20:27:41.291",
        "scheduled_time": "2026-07-13 20:27:41.320",
        "end_time": "2026-07-13 20:28:39.767",
        "finished": true,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://example.com/generated-image.png",
                            "type": "image"
                        }
                    ]
                }
            }
        ]
    },
    "usage": {
        "SR": "2K",
        "size": "2048*2048",
        "image_count": 1
    }
}

Tugas Gagal

Jika tugas gagal karena alasan apa pun, informasi terkait akan dikembalikan. Anda dapat mengidentifikasi penyebab kesalahan melalui bidang code dan message. Lihat Kode kesalahan untuk pemecahan masalah.

{
    "request_id": "1f015514-b04c-9190-b4dd-8ba11bb15708",
    "output": {
        "task_id": "ccae6c03-fe9f-48fd-b3d6-a524c4707f17",
        "task_status": "FAILED",
        "submit_time": "2026-07-13 20:27:50.654",
        "scheduled_time": "2026-07-13 20:27:50.689",
        "end_time": "2026-07-13 20:27:51.090",
        "code": "InvalidParameter",
        "message": "Missing required field 'parameters.n' in request body"
    }
}

Kode error

Jika pemanggilan model gagal dan mengembalikan pesan kesalahan, lihat Kode kesalahan untuk solusinya.

Ukuran Gambar yang Didukung

vidu-image

Resolusi	Ukuran yang Didukung
1K	10241024, 7201440, 1440720, 1024768, 7681024, 19201088, 10881920, 15361024, 10241536, 1920816, 816*1920
2K	20482048, 10882160, 21601088, 27362048, 20482736, 25601440, 14402560, 30722048, 20483072, 25601104, 1104*2560
4K	28802880, 14402880, 28801440, 33122480, 24803312, 38402160, 21603840, 35202352, 23523520, 38401648, 1648*3840