All Products
Search
Document Center

Alibaba Cloud Model Studio:Referensi API Z-Image

Last Updated:Feb 28, 2026

Z-Image adalah model teks-ke-gambar ringan yang menghasilkan gambar dengan cepat, mendukung rendering teks dalam bahasa Tiongkok dan Inggris, serta menyesuaikan berbagai resolusi dan rasio aspek.

Akses Cepat: Pengalaman Online (Singapura | Beijing) | Blog Teknis

Contoh Gambar

Prompt Input

Gambar Output

Foto seorang wanita muda bergaya dengan rambut pendek hitam yang berdiri percaya diri di depan dinding mural bergaya kartun yang cerah. Ia mengenakan pakaian serba hitam: jaket bomber bantalan dengan kerah berkerut, celana cargo pendek, stoking jaring ikan, dan sepatu bot hitam tebal Doc Martens, dengan rantai emas menjuntai dari pinggangnya. Latar belakang menampilkan empat panel bergaya komik berwarna-warni: satu bertuliskan “GRAND STAGE” dan berisi sepatu kets serta botol Gatorade; yang lain menampilkan sepatu kets Nike hijau dan sepotong pizza; yang ketiga bertuliskan “HARAJUKU st” dengan sepatu melayang; dan yang keempat menunjukkan seekor tikus biru menaiki skateboard dengan teks “Takeshita WELCOME.” Warna-warna cerah dominan meliputi kuning, teal, oranye, pink, dan hijau. Gelembung ucapan, pola halftone, dan karakter bermain meningkatkan estetika seni jalanan urban. Cahaya siang hari menerangi adegan secara merata, dan lantai di bawah kakinya adalah ubin putih. Potret seluruh tubuh, komposisi terpusat, postur sedikit miring, kontak mata langsung dengan kamera. Detail tinggi, fokus tajam, bingkai dinamis.

b16c8008-83c1-4c80-ae22-786a2299bec3-1-转换自-png

Ikhtisar Model

Nama Model

Deskripsi Model

Spesifikasi Gambar Output

z-image-turbo

Model ringan, menghasilkan gambar dengan cepat

Resolusi gambar: Total piksel antara 512×512 hingga 2048×2048. Untuk resolusi yang direkomendasikan, lihat pengaturan parameter ukuran

Format gambar: PNG

Jumlah gambar: Tetap 1

Catatan

Sebelum memanggil API, periksa daftar model yang didukung untuk setiap wilayah.

Prasyarat

Dapatkan Kunci API, dan konfigurasikan Kunci API sebagai variabel lingkungan (akan ditinggalkan dan digabung ke Konfigurasi Kunci API).

Panggilan HTTP Sinkron

Wilayah Singapura: POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Wilayah Beijing: POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

Parameter Permintaan

Teks-ke-Gambar

Contoh ini mengembalikan gambar secara langsung dan memberikan waktu respons cepat.

Untuk mengaktifkan penalaran cerdas, atur prompt_extend=true. Saat diaktifkan, sistem akan mengembalikan prompt yang dioptimalkan beserta proses penalarannya bersama gambar, tetapi ini meningkatkan waktu respons.

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "model": "z-image-turbo",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                    }
                ]
            }
        ]
    },
    "parameters": {
        "prompt_extend": false,
        "size": "1024*1024"
    }
}'

Header Permintaan

Content-Type string (Wajib)

Tipe konten permintaan. Harus berupa application/json.

Authorization string (Wajib)

Kredensial otentikasi menggunakan Kunci API Model Studio.

Contoh: Bearer sk-xxxx

Body Permintaan

model string (Wajib)

Nama model. Harus berupa z-image-turbo.

input object (Wajib)

Informasi input dasar.

Properti

messages array (Wajib)

Array konten permintaan. Saat ini hanya mendukung percakapan satu giliran. Kirim satu set parameter role dan content. Percakapan multi-giliran tidak didukung.

Properti

role string (Wajib)

Peran pesan. Atur parameter ini ke user.

content array (Wajib)

Array konten pesan. Harus berisi tepat satu objek teks.

Properti

text string (Wajib)

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

Mendukung bahasa Tiongkok dan Inggris. Panjangnya tidak boleh melebihi 800 karakter. Setiap karakter Tiongkok, huruf, angka, atau simbol dihitung sebagai satu karakter. Konten yang melebihi batas akan dipotong secara otomatis.

Contoh: Seekor kucing oranye duduk, dengan ekspresi gembira, lincah dan imut, realistis dan akurat.

Catatan: Hanya satu objek teks yang didukung. Mengirimkan nol atau lebih dari satu akan menghasilkan error.

parameters object (Opsional)

Parameter pengeditan gambar.

Properti

size string (Opsional)

Resolusi gambar output, dalam format lebar×tinggi.

  • Nilai default: 1024*1536.

  • Batas rentang total piksel: Total piksel antara 512×512 hingga 2048×2048.

  • Rentang resolusi yang direkomendasikan: Total piksel antara 1024×1024 hingga 1536×1536 untuk hasil pembuatan gambar yang lebih baik.

Contoh: 1024*1536.

Resolusi yang direkomendasikan untuk total piksel 1024×1024:

  • 1:1: 1024*1024

  • 2:3: 832*1248

  • 3:2: 1248*832

  • 3:4: 864*1152

  • 4:3: 1152*864

  • 7:9: 896*1152

  • 9:7: 1152*896

  • 9:16: 720*1280

  • 9:21: 576*1344

  • 16:9: 1280*720

  • 21:9: 1344*576

Resolusi yang direkomendasikan untuk total piksel 1280×1280:

  • 1:1: 1280*1280

  • 2:3: 1024*1536

  • 3:2: 1536*1024

  • 3:4: 1104*1472

  • 4:3: 1472*1104

  • 7:9: 1120*1440

  • 9:7: 1440*1120

  • 9:16: 864*1536

  • 9:21: 720*1680

  • 16:9: 1536*864

  • 21:9: 1680*720

Resolusi yang direkomendasikan untuk total piksel 1536×1536:

  • 1:1: 1536*1536

  • 2:3: 1248*1872

  • 3:2: 1872*1248

  • 3:4: 1296*1728

  • 4:3: 1728*1296

  • 7:9: 1344*1728

  • 9:7: 1728*1344

  • 9:16: 1152*2048

  • 9:21: 864*2016

  • 16:9: 2048*1152

  • 21:9: 2016*864

prompt_extend bool (Opsional)

Penting

prompt_extend secara langsung memengaruhi penagihan. Mengaturnya ke true lebih mahal daripada false. Untuk detailnya, lihat harga model.

Aktifkan penulisan ulang prompt (teks) cerdas. Saat diaktifkan, Large Language Model (LLM) mengoptimalkan prompt dan mengeluarkan proses penalarannya.

  • false: Default. Menonaktifkan penulisan ulang cerdas. Mengeluarkan gambar dan prompt teks asli.

  • true: Mengaktifkan penulisan ulang cerdas. Mengeluarkan gambar, prompt teks yang dioptimalkan, dan proses penalaran.

seed integer (opsional)

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

Menggunakan nilai seed yang sama membuat hasil lebih konsisten. Jika diabaikan, algoritma menggunakan seed acak.

Catatan: Karena pembuatan gambar bersifat probabilistik, bahkan nilai seed yang identik tidak menjamin hasil yang identik.

Parameter Respons

Eksekusi tugas berhasil

Data tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan.

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.png?Expires=xxx"
                        },
                        {
                            "text": "Photo of a stylish young woman with short black hair standing confidently in front of a vibrant cartoon-style mural wall. She wears an all-black outfit: a puffed bomber jacket with a ruffled collar, cargo shorts, fishnet tights, and chunky black Doc Martens, with a gold chain dangling from her waist.  The background features four colorful comic-style panels: one reads “GRAND STAGE” and includes sneakers and a Gatorade bottle; another displays green Nike sneakers and a slice of pizza; the third reads “HARAJUKU st” with floating shoes; and the fourth shows a blue mouse riding a skateboard with the text “Takeshita WELCOME.”  Dominant bright colors include yellow, teal, orange, pink, and green. Speech bubbles, halftone patterns, and playful characters enhance the urban street-art aesthetic. Daylight evenly illuminates the scene, and the ground beneath her feet is white tiled pavement.  Full-body portrait, centered composition, slightly tilted stance, direct eye contact with the camera. High detail, sharp focus, dynamic framing."
                        }
                    ],
                    "reasoning_content": "",
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 1024,
        "image_count": 1,
        "input_tokens": 0,
        "output_tokens": 0,
        "total_tokens": 0,
        "width": 1024
    },
    "request_id": "abf1645b-b630-433a-92f6-xxxxxx"
}

Eksekusi tugas gagal

Jika tugas gagal dieksekusi, respons dikembalikan dengan detail kesalahan. Bidang code dan message menunjukkan alasan kegagalan tersebut. Untuk informasi lebih lanjut, lihat Pesan kesalahan.

{
    "request_id": "a4d78a5f-655f-9639-8437-xxxxxx",
    "code": "InvalidParameter",
    "message": "num_images_per_prompt must be 1"
}

output object

Informasi output tugas.

Properti

choices array

Output yang dihasilkan oleh model. Array ini berisi tepat satu elemen.

Properti

finish_reason string

Alasan tugas dihentikan. Untuk penyelesaian normal, nilai ini adalah stop.

message object

Pesan yang dikembalikan oleh model.

Properti

role string

Peran pesan. Nilai ini selalu assistant.

content array

Properti

image string

URL gambar yang dihasilkan. Format gambarnya adalah PNG. URL kedaluwarsa dalam 24 jam. Unduh dan simpan gambar segera.

text string

  • Saat prompt_extend=false, ini adalah prompt input.

  • Saat prompt_extend=true, ini adalah prompt yang ditulis ulang.

reasoning_content string

Proses penalaran model. Dikembalikan hanya saat prompt_extend=true.

usage object

Statistik penggunaan output. Hanya hasil yang berhasil yang dihitung.

Properti

width integer

Lebar gambar yang dihasilkan, dalam piksel.

height integer

Tinggi gambar yang dihasilkan, dalam piksel.

image_count integer

Jumlah gambar yang dihasilkan. Nilainya tetap 1.

input_tokens integer

Jumlah token input. Nilainya 0 saat prompt_extend adalah false.

output_tokens integer

Jumlah token output. Nilainya 0 saat prompt_extend adalah false.

output_tokens_details object

Detail tentang token output. Ini dikembalikan hanya saat prompt_extend adalah true.

Properti

reasoning_tokens integer

Jumlah token yang digunakan untuk inferensi.

total_tokens integer

Total jumlah token. Nilainya 0 saat prompt_extend adalah false.

request_id string

Pengidentifikasi unik untuk permintaan. Gunakan untuk pelacakan dan troubleshooting masalah.

code string

Kode kesalahan. Dikembalikan hanya saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

message string

Pesan kesalahan detail. Dikembalikan hanya saat permintaan gagal. Lihat kode kesalahan untuk detailnya.

Batasan

  • URL gambar hanya disimpan selama 24 jam. Unduh segera.

  • Moderasi konten: Prompt input dan gambar output keduanya dikenai moderasi konten. Permintaan yang berisi konten terlarang menghasilkan kesalahan IPInfringementSuspect atau DataInspectionFailed. Lihat kode kesalahan untuk detailnya.

Penagihan dan Pembatasan Laju

  • Untuk kuota gratis dan harga satuan model, lihat harga model.

  • Untuk pembatasan laju model, lihat Z-Image.

  • Penagihan didasarkan pada jumlah gambar yang berhasil dihasilkan, tergantung apakah penulisan ulang cerdas diaktifkan. Panggilan model yang gagal atau kesalahan pemrosesan tidak dikenai biaya apa pun atau menghabiskan kuota gratis.

Kode Kesalahan

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

FAQ

T: Bagaimana cara melihat metrik pemanggilan model?

J: Satu jam setelah pemanggilan model selesai, buka halaman Monitoring (Singapura) atau Monitoring (China (Beijing)) untuk melihat metrik seperti jumlah pemanggilan dan tingkat keberhasilan. Untuk informasi lebih lanjut, lihat Kueri tagihan dan manajemen biaya.

T: Bagaimana cara mendapatkan daftar putih nama domain untuk penyimpanan gambar?

J: Gambar yang dihasilkan model disimpan di OSS. API mengembalikan URL publik sementara. Untuk mengonfigurasi daftar putih firewall untuk URL unduhan ini, perhatikan hal berikut: Penyimpanan dasar dapat berubah secara dinamis. Topik ini tidak menyediakan daftar putih nama domain OSS tetap untuk mencegah masalah akses akibat informasi yang kedaluwarsa. Jika Anda memiliki persyaratan kontrol keamanan, hubungi manajer akun Anda untuk mendapatkan daftar nama domain OSS terbaru.