Referensi API teks-ke-gambar Z-Image - Alibaba Cloud Model Studio

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.

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.

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.

CatatanPeriksa Daftar Model untuk dukungan wilayah sebelum melakukan pemanggilan.

Prasyarat

Buat Kunci API dan tetapkan Kunci API sebagai Variabel lingkungan.

PentingAlibaba 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)

PentingMengaktifkan 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 object

Output model.

Properti

choices array

Konten output model. Array berisi satu elemen.

Properti

finish_reason string

Alasan penyelesaian. Nilai stop menunjukkan keberhasilan.

message object

Pesan respons model.

Properti

rolestring

Peran pesan. Nilainya adalah assistant.

contentarray

Properti

image string

URL gambar yang dihasilkan (PNG). Berlaku 24 jam — segera unduh.

text string

Ini mengembalikan prompt input (prompt_extend=false) atau prompt yang ditulis ulang (prompt_extend=true).

reasoning_content string

Proses reasoning model. Hanya dikembalikan saat prompt_extend=true.

usage object

Ini mencakup statistik penggunaan hanya untuk generasi yang berhasil.

Properti

width integer

Lebar gambar yang dihasilkan (piksel).

height integer

Tinggi gambar yang dihasilkan (piksel).

image_count integer

Jumlah gambar yang dihasilkan: 1.

input_tokens integer

Token input (0 saat prompt_extend=false).

output_tokens integer

Token output (0 saat prompt_extend=false).

output_tokens_detailsobject

Detail token output (hanya saat prompt_extend=true).

Properti

reasoning_tokensinteger

Token yang digunakan untuk reasoning.

total_tokensinteger

Total token (0 saat prompt_extend=false).

request_id string

Identifier unik permintaan untuk pelacakan dan troubleshooting.

code string

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

message string

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

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 gagal, sistem mengembalikan detail error di bidang code dan message. Lihat Kode error untuk troubleshooting.

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

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.