全部产品
Search
文档中心

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

更新时间:Dec 24, 2025

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

Tautan cepat: Blog teknis

Prasyarat

Anda harus telah memperoleh dan mengonfigurasi Kunci API serta menyetel Kunci API sebagai variabel lingkungan (langkah ini sedang ditinggalkan dan akan digabungkan ke dalam konfigurasi Kunci API).

Contoh

Masukkan prompt

Citra output

Foto seorang perempuan 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 Doc Martens hitam tebal, dengan rantai emas menjuntai dari pinggangnya. Latar belakang menampilkan empat panel bergaya komik berwarna-warni: satu bertuliskan “GRAND STAGE” dan menampilkan sepatu kets serta botol Gatorade; yang lain menampilkan sepatu Nike hijau dan sepotong pizza; yang ketiga bertuliskan “HARAJUKU st” dengan sepatu-sepatu melayang; dan yang keempat menunjukkan seekor tikus biru menaiki skateboard dengan teks “Takeshita WELCOME.” Warna-warna cerah dominan termasuk kuning, teal, oranye, merah muda, dan hijau. Gelembung ucapan, pola halftone, dan karakter lucu memperkuat 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

Model

Deskripsi

Spesifikasi citra output

z-image-turbo

Model ringan untuk pembuatan citra cepat

Resolusi citra: Total piksel antara 512×512 hingga 2048×2048. Untuk resolusi yang direkomendasikan, lihat parameter size.

Format citra: png

Jumlah citra: Tetap 1.

Catatan

Sebelum melakukan panggilan, periksa daftar model yang didukung di setiap Wilayah.

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 berikut mengembalikan citra secara langsung untuk waktu respons lebih cepat.

Untuk mengaktifkan fitur penulisan ulang cerdas, atur prompt_extend=true. Saat diaktifkan, sistem mengembalikan prompt yang dioptimalkan beserta proses penalarannya bersama citra, tetapi ini meningkatkan waktu respons.

Contoh berikut menggunakan URL dasar untuk Wilayah Singapura. Jika Anda menggunakan model dari Wilayah China (Beijing), ganti URL dasar dengan https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation.
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,
        "negative_prompt": "",
        "size": "1024*1024"
    }
}'

Header permintaan

Content-Type string (Wajib)

Tipe konten permintaan. Atur parameter ini ke application/json.

Authorization string (Wajib)

Kredensial otentikasi identitas untuk permintaan. API ini menggunakan Kunci API Model Studio untuk otentikasi identitas. Contoh: Bearer sk-xxxx.

Body permintaan

model string (Wajib)

Nama model.

Contoh: z-image-turbo.

input object (Wajib)

Input untuk model.

Properti

messages array (Wajib)

Array berisi konten permintaan. Saat ini, hanya percakapan satu giliran yang didukung, artinya array hanya boleh berisi satu objek pesan.

Properti

role string (Wajib)

Peran pesan. Parameter ini harus diatur ke user.

content array (Wajib)

Array berisi konten pesan. Harus berisi tepat satu objek teks.

Properti

text string (Wajib)

Prompt positif yang menggambarkan konten, gaya, dan komposisi citra yang dihasilkan.

Mendukung bahasa Tiongkok dan Inggris. Panjang prompt tidak boleh melebihi 800 karakter. Setiap karakter Tiongkok, huruf, angka, atau simbol dihitung sebagai satu karakter. Karakter berlebih akan dipotong secara otomatis.

Contoh: Seekor kucing oranye duduk dengan ekspresi bahagia, hidup dan imut, realistis dan akurat.

Catatan: Hanya satu objek teks yang didukung. Jika Anda tidak mengirimkan objek teks atau mengirimkan lebih dari satu, sistem akan melaporkan error.

parameters object (Opsional)

Parameter untuk pembuatan citra.

Properti

size string (Opsional)

Resolusi citra output, dalam format width*height. Nilai default dan batasan bervariasi tergantung versi model:

  • Nilai default: 1024*1536.

  • Rentang total piksel: Jumlah total piksel harus antara 512×512 hingga 2048×2048.

  • Rentang resolusi yang direkomendasikan: Untuk kualitas citra lebih baik, jumlah total piksel sebaiknya antara 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)

Penting

Parameter `prompt_extend` secara langsung memengaruhi penagihan. Mengatur parameter ini ke true lebih mahal daripada mengaturnya ke false. Untuk informasi selengkapnya, lihat Harga model.

Menentukan apakah akan mengaktifkan penulisan ulang cerdas untuk prompt teks. Jika fitur ini diaktifkan, model bahasa besar akan mengoptimalkan prompt dan mengeluarkan proses penalarannya.

  • false: (Default) Menonaktifkan penulisan ulang cerdas. Output mencakup citra dan prompt teks asli.

  • true: Mengaktifkan penulisan ulang cerdas. Output mencakup citra, prompt teks yang dioptimalkan, dan proses penalaran.

seed integer (Opsional)

Bilangan acak seed digunakan untuk mengontrol keacakan konten yang dihasilkan model, dengan rentang nilai [0, 2147483647].

Menggunakan nilai seed yang sama menghasilkan hasil yang lebih konsisten. Jika Anda tidak memberikan seed, algoritma akan menggunakan bilangan acak.

Catatan: Proses pembuatan model bersifat probabilistik. Bahkan dengan seed yang sama, hasilnya tidak dijamin identik pada setiap panggilan.

Parameter respons

Eksekusi tugas berhasil

Data tugas, seperti status tugas dan URL citra, hanya disimpan selama 24 jam dan secara otomatis dihapus setelah periode tersebut. Anda harus segera menyimpan citra 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, sistem mengembalikan informasi kegagalan tersebut. Bidang `code` dan `message` menunjukkan penyebab error. Untuk informasi selengkapnya, lihat Pesan error.

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

output object

Output dari tugas.

Properti

choices array

Konten output yang dihasilkan model. Array ini hanya berisi satu elemen.

Properti

finish_reason string

Alasan tugas dihentikan. Nilai stop menunjukkan penyelesaian normal.

messages object

Pesan yang dikembalikan oleh model.

Properti

role string

Peran pesan. Nilainya selalu assistant.

content array

Properti

image string

URL citra yang dihasilkan. Format citra adalah PNG. Tautan berlaku selama 24 jam. Unduh dan simpan citra tersebut segera.

text string

  • Jika prompt_extend=false, ini adalah prompt input.

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

reasoning_content string

Proses penalaran model. Bidang ini hanya dikembalikan saat prompt_extend diatur ke true.

usage object

Statistik penggunaan untuk tugas. Hanya tugas yang berhasil yang termasuk dalam statistik ini.

Properti

width integer

Lebar citra yang dihasilkan dalam piksel.

height integer

Tinggi citra yang dihasilkan dalam piksel.

image_count integer

Jumlah citra yang dihasilkan. Nilainya selalu 1.

input_tokens integer

Jumlah token input.

output_tokens integer

Jumlah token output.

output_tokens_details object

Detail tentang token output.

output_tokens_details.reasoning_tokens integer

Jumlah token yang digunakan untuk penalaran.

total_tokens integer

Total jumlah token.

request_id string

ID permintaan unik yang dapat digunakan untuk melacak dan memecahkan masalah.

code string

Kode error untuk permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi selengkapnya, lihat Pesan error.

message string

Informasi detail tentang permintaan yang gagal. Parameter ini tidak dikembalikan jika permintaan berhasil. Untuk informasi selengkapnya, lihat Pesan error.

Batasan

  • Validitas data: task_id dan url citra hanya disimpan selama 24 jam. Setelah periode tersebut, data tersebut tidak dapat diakses atau diunduh.

  • Moderasi konten: prompt input dan citra output keduanya dikenai tinjauan moderasi konten. Permintaan yang berisi konten terlarang akan menghasilkan error `IPInfringementSuspect` atau `DataInspectionFailed`. Untuk informasi selengkapnya, lihat Pesan error.

  • Konfigurasi akses jaringan: URL citra disimpan di Object Storage Service. Jika sistem bisnis Anda tidak dapat mengakses URL OSS eksternal karena kebijakan keamanan, Anda harus menambahkan nama domain OSS berikut ke daftar putih.

    # Daftar nama domain OSS
    dashscope-result-bj.oss-cn-beijing.aliyuncs.com
    dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com
    dashscope-result-sh.oss-cn-shanghai.aliyuncs.com
    dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com
    dashscope-result-zjk.oss-cn-zhangjiakou.aliyuncs.com
    dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com
    dashscope-result-hy.oss-cn-heyuan.aliyuncs.com
    dashscope-result-cd.oss-cn-chengdu.aliyuncs.com
    dashscope-result-gz.oss-cn-guangzhou.aliyuncs.com
    dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com

Penagihan dan pembatasan laju

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

  • Untuk batas laju model, lihat Tongyi - teks-ke-gambar - Z-Image.

  • Detail penagihan:

    • Penagihan didasarkan pada jumlah citra yang berhasil dihasilkan dan apakah penulisan ulang cerdas diaktifkan. Anda hanya dikenai biaya ketika respons API mengembalikan task_status bernilai SUCCEEDED dan citra berhasil dihasilkan.

    • Panggilan model yang gagal atau error pemrosesan tidak dikenai biaya apa pun dan tidak mengurangi kuota gratis Anda.

Kode error

Jika panggilan model gagal dan mengembalikan pesan error, lihat Pesan error untuk mengatasi masalah tersebut.

FAQ

T: Bagaimana cara melihat volume panggilan model?

J: Sekitar satu jam setelah panggilan model, Anda dapat membuka halaman Observasi Model (Singapura), atau Observasi Model (Beijing) untuk melihat metrik seperti jumlah panggilan dan tingkat keberhasilan. Untuk informasi selengkapnya, lihat Bagaimana cara melihat catatan panggilan model?