Skip to main content
Z-Image

Referensi API Z-Image

Model teks-ke-gambar ringan untuk generasi cepat, dengan dukungan rendering teks Tiongkok dan Inggris serta resolusi fleksibel.

Coba secara online: (Singapura | Beijing) | Blog teknis

Contoh

Input prompt

Output image

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.

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

Ikhtisar model

Model Name

Description

Output image specifications

z-image-turbo

A fast lightweight image generation model

Resolusi gambar: 512×512 hingga 2048×2048 piksel. Lihat resolusi yang direkomendasikan di pengaturan parameter size.

Format gambar: png

Jumlah gambar: Tetap 1.

Periksa Daftar Model untuk dukungan wilayah sebelum melakukan pemanggilan.

Prasyarat

Buat Kunci API dan tetapkan Kunci API sebagai Variabel lingkungan.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami menyarankan migrasi ke domain baru berikut:
  • China (Beijing): dari https://dashscope.aliyuncs.com ke https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari https://dashscope-intl.aliyuncs.com ke https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
{WorkspaceId} adalah ID ruang kerja Anda, yang dapat ditemukan di halaman Workspace Details pada Konsol Alibaba Cloud Model Studio. Domain lama tetap berfungsi sepenuhnya.

Pemanggilan HTTP sinkron

Singapura:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Beijing:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Parameter permintaan

Header permintaan
Content-Type string (Wajib)Tipe konten permintaan. Harus berupa application/json.Authorization string (Wajib)Mengautentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
Body permintaan
model string (Wajib)Nama model: z-image-turbo.input object (Wajib)Konten input.

Properti

messages array (Wajib)Array konten permintaan. Hanya satu giliran (single-turn) — kirim satu set role dan content. Multi-turn tidak didukung.

Properti

rolestring (Wajib)Peran pesan: user.contentarray (Wajib)Array konten pesan. Harus berisi satu objek teks.

Properti

textstring(Wajib)Prompt positif yang menjelaskan konten, gaya, dan komposisi yang diinginkan.Mendukung bahasa Tiongkok dan Inggris. Maksimal 800 karakter (setiap karakter, huruf, angka, atau simbol dihitung sebagai satu). Karakter tambahan akan dipotong.Contoh: Seekor kucing oranye duduk dengan ekspresi bahagia, lincah dan imut, realistis dan akurat.Catatan: Hanya satu objek teks yang didukung. Mengirim nol atau beberapa objek teks akan menghasilkan error.
parameters object (Opsional)Parameter generasi gambar.

Properti

size string (Opsional)Resolusi gambar output dalam format lebar×tinggi.
  • Bawaan: 1024*1536
  • Rentang: 512×512 hingga 2048×2048
  • Direkomendasikan: 1024×1024 hingga 1536×1536
Contoh: 1024*1536.

Resolusi yang direkomendasikan untuk total 1024*1024 piksel:

  • 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 1280*1280 piksel:

  • 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 1536*1536 piksel:

  • 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)
Mengaktifkan prompt_extend meningkatkan biaya. Lihat Harga model untuk detailnya.
Aktifkan penulisan ulang prompt cerdas melalui optimasi LLM dan output reasoning.
  • false (bawaan): Mengembalikan gambar dan prompt asli
  • true: Mengembalikan gambar, prompt yang dioptimalkan, dan reasoning
seed integer (opsional)Seed angka acak. Rentang valid: [0,2147483647].Menggunakan seed yang sama menghasilkan output serupa. Jika diabaikan, algoritma menggunakan seed acak.Catatan: Generasi gambar bersifat probabilistik. Bahkan dengan seed yang sama, hasilnya mungkin berbeda.
  • Teks-ke-gambar
Contoh ini mengembalikan gambar secara langsung untuk respons lebih cepat. Untuk mengaktifkan penulisan ulang cerdas, atur prompt_extend=true — sistem akan mengembalikan prompt yang dioptimalkan, alasan, dan gambar (meningkatkan waktu respons).
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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"
    }
}'

Parameter respons

output objectOutput model.

Properti

choices arrayKonten output model. Array berisi satu elemen.

Properti

finish_reason stringAlasan penyelesaian. Nilai stop menunjukkan keberhasilan.message objectPesan respons model.

Properti

rolestringPeran pesan. Nilainya adalah assistant.contentarray

Properti

image stringURL gambar yang dihasilkan (PNG). Berlaku 24 jam — segera unduh.text stringIni mengembalikan prompt input (prompt_extend=false) atau prompt yang ditulis ulang (prompt_extend=true).
reasoning_content stringProses reasoning model. Hanya dikembalikan saat prompt_extend=true.
usage objectIni mencakup statistik penggunaan hanya untuk generasi yang berhasil.

Properti

width integerLebar gambar yang dihasilkan (piksel).height integerTinggi gambar yang dihasilkan (piksel).image_count integerJumlah gambar yang dihasilkan: 1.input_tokens integerToken input (0 saat prompt_extend=false).output_tokens integerToken output (0 saat prompt_extend=false).output_tokens_detailsobjectDetail token output (hanya saat prompt_extend=true).

Properti

reasoning_tokensintegerToken yang digunakan untuk reasoning.
total_tokensintegerTotal token (0 saat prompt_extend=false).
request_id stringIdentifier unik permintaan untuk pelacakan dan troubleshooting.code stringKode error. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode error.message stringPesan error detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode error.
  • Eksekusi tugas berhasil
  • Eksekusi tugas gagal
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"
}

Batasan

  • URL gambar berlaku selama 24 jam. Segera unduh.
  • Moderasi konten: Baik prompt input maupun gambar output menjalani moderasi konten. Konten yang tidak sesuai akan mengembalikan error IPInfringementSuspect atau DataInspectionFailed. Lihat Kode error.

Penagihan dan pembatasan laju

  • Untuk harga dan kuota gratis, lihat Harga model.
  • Untuk batas laju, lihat Z-Image.
  • Penagihan didasarkan pada jumlah gambar yang berhasil dihasilkan dan status prompt_extend. Pemanggilan yang gagal tidak dikenai biaya atau mengonsumsi kuota gratis.

Kode error

Lihat Kode error untuk troubleshooting pemanggilan yang gagal.

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 selengkapnya, lihat Penagihan dan manajemen biaya.

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

J: Gambar yang dihasilkan oleh 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.
Pembuatan Gambar
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production
Referensi API Z-Image - Alibaba Cloud Model Studio