Model Qwen Image Generation and Editing 3.0 mendukung baik teks-ke-gambar (T2I) maupun gambar-ke-gambar/pengeditan gambar (I2I). Model ini dapat menghasilkan gambar langsung dari prompt teks atau mengedit gambar berdasarkan 1–3 gambar referensi yang dikombinasikan dengan instruksi pengeditan.
Ikhtisar model
Model | Deskripsi | Spesifikasi gambar output |
|---|---|---|
qwen-image-3.0-pro | Model Qwen Image Generation and Editing 3.0 yang mendukung teks-ke-gambar (T2I) dan gambar-ke-gambar/pengeditan gambar (I2I). | Resolusi gambar:
Format gambar: PNG |
qwen-image-3.0 | Model standar Qwen Image Generation and Editing 3.0 yang mendukung teks-ke-gambar (T2I) dan gambar-ke-gambar/pengeditan gambar (I2I). Menyeimbangkan kualitas dan kecepatan. |
Ketersediaan
Model, URL titik akhir, dan Kunci API harus berada dalam wilayah yang sama. Panggilan lintas-wilayah akan gagal.
- Pilih model: Pastikan model tersedia di wilayah target Anda.
- Pilih URL: Pilih URL titik akhir yang sesuai dengan wilayah model Anda. Baik URL HTTP maupun SDK DashScope didukung.
- Konfigurasikan Kunci API: Dapatkan Kunci API untuk wilayah tersebut, lalu konfigurasikan Kunci API sebagai Variabel lingkungan.
- Instal SDK: Untuk melakukan panggilan API menggunakan SDK, instal SDK DashScope.
API Sinkron (direkomendasikan)
HTTP
- Singapura
- China (Beijing)
- China (Hong Kong)
- Jerman (Frankfurt)
- Jepang (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation{WorkspaceId} dengan ID ruang kerja aktual Anda.
Parameter permintaanHeaderContent-Typestring (Wajib)Tipe konten permintaan. Harus berupa application/json.Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.Body permintaanmodelstring (Wajib)Nama model. Nilai yang tersedia: qwen-image-3.0-pro dan qwen-image-3.0.input object (Wajib)Objek parameter input, yang berisi bidang-bidang berikut:
Properti messages array (Wajib)Array konten permintaan. Hanya percakapan satu putaran yang didukung, sehingga array harus berisi tepat satu objek dengan properti role dan content.
Properti role string (Wajib)Peran pengirim pesan. Harus diatur ke user.contentarray (Wajib)Array konten pesan, dengan kombinasi berbeda tergantung kasus penggunaan:
Properties image string (Wajib untuk I2I)URL atau data terenkripsi Base64 dari gambar input. Dalam skenario I2I, 1–3 gambar didukung. Saat beberapa gambar disediakan, urutannya ditentukan oleh urutan array.Persyaratan gambar:
string(Wajib)Petunjuk positif yang menjelaskan konten, gaya, dan komposisi gambar yang ingin Anda hasilkan atau edit. Mendukung Bahasa Mandarin dan Bahasa Inggris. Jumlah maksimum yang direkomendasikan: 4.500 token.Catatan: Hanya satu objek teks yang diizinkan. Menghilangkannya atau menyediakan beberapa objek teks akan menghasilkan error.object (Opsional)Parameter tambahan untuk mengontrol pembuatan gambar.
Properti prompt_extend boolean (Opsional)Apakah akan mengaktifkan penulisan ulang prompt cerdas. Bawaan: true (direkomendasikan). Saat diaktifkan, model mengoptimalkan prompt positif menggunakan metode yang ditentukan oleh prompt_extend_mode, yang secara signifikan meningkatkan hasil untuk deskripsi sederhana.prompt_extend_mode string (Opsional)Metode penulisan ulang prompt. Bawaan: direct. Opsi:
boolean (Opsional)Mengaktifkan mode berpikir. Bawaannya adalah true. Ini meningkatkan penalaran model untuk memperbaiki kualitas gambar, tetapi memperpanjang waktu pembuatan. Memerlukan prompt_extend=true. Didukung untuk Direct T2I, Direct I2I, dan Agent T2I. Tidak didukung untuk I2I Agent.n integer (Opsional)Jumlah gambar output. Rentang nilai: 1 hingga 6. Bawaan: 1.size string (Opsional)Resolusi gambar output dalam format width*height, misalnya "1024*1024". Jika tidak ditentukan, model secara otomatis merekomendasikan resolusi berdasarkan prompt.
string (Opsional)Prompt negatif yang menjelaskan konten yang tidak ingin muncul dalam gambar.seed integer (Opsional)Seed acak. Rentang nilai: [0, 2147483647]. Jika dihilangkan, layanan menghasilkan seed acak. Gunakan seed tetap untuk hasil yang dapat direproduksi.watermark boolean (Opsional)Apakah akan menambahkan Watermark. Bawaan: false. |
Parameter responsoutputobjectBerisi hasil generasi model.
Properti rewrite_status stringStatus penulisan ulang prompt. Nilainya bergantung pada apakah penulisan ulang diaktifkan dalam permintaan dan hasil penulisannya.choices arrayDaftar opsi hasil.
Properti finish_reason stringAlasan tugas dihentikan. Nilainya adalah stop saat tugas selesai secara normal.message objectPesan yang dikembalikan oleh model.
Properti role stringPeran pesan. Tetap sebagai assistant.contentarrayKonten pesan yang berisi informasi gambar yang dihasilkan.
Properti image stringURL gambar yang dihasilkan dalam format PNG. Tautan ini berlaku selama 24 jam. Harap segera unduh dan simpan gambarnya.objectPenggunaan sumber daya dari panggilan ini. Hanya dikembalikan saat berhasil.
Properti output_width integerLebar gambar output akhir dalam piksel.output_height integerTinggi gambar output akhir dalam piksel.input_image_count integerJumlah gambar input dalam permintaan. Mengembalikan 0 untuk teks-ke-gambar (T2I), dan jumlah aktual untuk gambar-ke-gambar (I2I).input_image_type stringTingkat penagihan gambar input. Ditentukan berdasarkan area piksel resolusi output: qima_input_1k jika area ≤ 2.250.000, atau qima_input_2k jika area > 2.250.000.output_image_count integerJumlah aktual gambar output yang dikembalikan.output_image_type stringTingkat penagihan gambar output. Ditentukan berdasarkan area piksel resolusi output: qima_output_1k jika area ≤ 2.250.000, atau qima_output_2k jika area > 2.250.000.stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. |
Data tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan. |
SDK
Contoh berikut menunjukkan cara memanggil API menggunakan SDK Python dan Java untuk gambar-ke-gambar / pengeditan gambar (I2I).
API Asinkron
Selain panggilan sinkron yang dijelaskan di atas, Qwen Image Generation and Editing 3.0 juga mendukung panggilan asinkron. API asinkron memiliki struktur parameter permintaan yang sama dengan API sinkron. Anda hanya perlu menambahkan header X-DashScope-Async: enable. Setelah layanan menerima permintaan, layanan akan mengembalikan ID tugas (task_id), yang kemudian Anda gunakan untuk melakukan polling ke API kueri guna mendapatkan hasil akhir.
HTTP
Panggilan asinkron menggunakan alur kerja dua langkah:
- Buat tugas untuk mendapatkan ID tugas: Kirim permintaan untuk membuat tugas. Respons berisi ID tugas (task_id).
- Lakukan polling hasil menggunakan ID tugas: Gunakan task_id untuk memeriksa status tugas hingga tugas selesai dan URL gambar dikembalikan.
Langkah 1: Buat tugas untuk mendapatkan ID tugas
- Singapura
- China (Beijing)
- China (Hong Kong)
- Jerman (Frankfurt)
- Jepang (Tokyo)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image-generation/generationParameter permintaanHeaderContent-Typestring (Wajib)Tipe konten permintaan. Harus berupa application/json.Authorization string (Wajib)Mengotentikasi 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.Body permintaanmodelstring (Wajib)Nama model. Nilai yang tersedia: qwen-image-3.0-pro dan qwen-image-3.0.input object (Wajib)Objek parameter input, yang berisi bidang-bidang berikut:
Properti messages array (Wajib)Array konten permintaan. Hanya percakapan satu putaran yang didukung, sehingga array harus berisi tepat satu objek dengan properti role dan content.
Properti role string (Wajib)Peran pengirim pesan. Harus diatur ke user.contentarray (Wajib)Array konten pesan, dengan kombinasi berbeda tergantung kasus penggunaan:
Properti image string (Wajib untuk I2I)URL atau data terenkripsi Base64 dari gambar input. Dalam skenario I2I, 1–3 gambar didukung. Saat beberapa gambar disediakan, urutannya ditentukan oleh urutan array.Persyaratan gambar:
string(Wajib)Prompt positif yang menjelaskan konten, gaya, dan pencampuran aliran gambar yang ingin Anda hasilkan atau edit. Bahasa Tionghoa dan Inggris didukung. Maksimum yang direkomendasikan: 4.500 token.Catatan: Hanya satu objek teks yang diizinkan. Menghilangkannya atau menyediakan beberapa objek teks akan menghasilkan error.object (Opsional)Parameter tambahan untuk mengontrol pembuatan gambar.
Properti prompt_extend boolean (Opsional)Apakah akan mengaktifkan penulisan ulang prompt cerdas. Bawaan: true (direkomendasikan). Saat diaktifkan, model mengoptimalkan prompt positif menggunakan metode yang ditentukan oleh prompt_extend_mode, yang secara signifikan meningkatkan hasil untuk deskripsi sederhana.prompt_extend_mode string (Opsional)Metode penulisan ulang prompt. Bawaan: direct. Opsi:
boolean (Opsional)Mengaktifkan mode berpikir. Bawaannya adalah true. Ini meningkatkan penalaran model untuk memperbaiki kualitas gambar, tetapi memperpanjang waktu pembuatan. Memerlukan prompt_extend=true. Didukung untuk Direct T2I, Direct I2I, dan Agent T2I. Tidak didukung untuk I2I Agent.n integer (Opsional)Jumlah gambar output. Rentang nilai: 1 hingga 6. Bawaan: 1.size string (Opsional)Resolusi gambar output dalam format width*height, misalnya "1024*1024". Jika tidak ditentukan, model secara otomatis merekomendasikan resolusi berdasarkan prompt.
string (Opsional)Prompt negatif yang menjelaskan konten yang tidak ingin muncul dalam gambar.seed integer (Opsional)Seed acak. Rentang nilai: [0, 2147483647]. Jika dihilangkan, layanan menghasilkan seed acak. Gunakan seed tetap untuk hasil yang dapat direproduksi.watermark boolean (Opsional)Apakah akan menambahkan Watermark. Bawaan: false. |
Parameter responsoutputobjectInformasi penerimaan tugas.
Properti task_id stringID tugas asinkron, digunakan untuk menanyakan status dan hasil tugas. Pastikan untuk menyimpannya.task_status stringStatus tugas. Biasanya PENDING saat tugas diajukan, yang hanya menunjukkan bahwa tugas telah diterima, bukan bahwa gambar telah dihasilkan.stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. |
Simpan task_id untuk menanyakan status tugas dan hasilnya. |
Langkah 2: Lakukan polling hasil menggunakan ID tugas
- Singapura
- China (Beijing)
- China (Hong Kong)
- Jerman (Frankfurt)
- Jepang (Tokyo)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Parameter permintaanHeaderAuthorizationstring (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.Parameter path URLtask_idstring (Wajib)ID tugas tersebut. |
Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk kueri selama 24 jam, Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. |
Parameter responsoutputobjectInformasi output tugas.
Properti task_id stringID tugas. Berlaku untuk kueri selama 24 jam.task_status stringStatus tugas.
Nilai enumerasi
stringWaktu saat tugas diajukan. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.scheduled_time stringWaktu saat tugas dieksekusi. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.end_time stringWaktu saat tugas selesai. Waktu dalam UTC+8 dan formatnya YYYY-MM-DD HH:mm:ss.SSS.rewrite_status stringStatus penulisan ulang prompt. Nilainya bergantung pada apakah penulisan ulang diaktifkan dalam permintaan dan hasil penulisannya.choices arrayDaftar opsi hasil.
Properti finish_reason stringAlasan tugas dihentikan. Nilainya adalah stop saat tugas selesai secara normal.message objectPesan yang dikembalikan oleh model.
Properti role stringPeran pesan. Tetap sebagai assistant.contentarrayKonten pesan yang berisi informasi gambar yang dihasilkan.
Properti image stringURL gambar yang dihasilkan dalam format PNG. Tautan ini berlaku selama 24 jam. Harap segera unduh dan simpan gambarnya.objectPenggunaan sumber daya dari panggilan ini. Hanya dikembalikan saat berhasil.
Properti output_width integerLebar gambar output akhir dalam piksel.output_height integerTinggi gambar output akhir dalam piksel.input_image_count integerJumlah gambar input dalam permintaan. Mengembalikan 0 untuk teks-ke-gambar (T2I), dan jumlah aktual untuk gambar-ke-gambar (I2I).input_image_type stringTingkat penagihan gambar input. Ditentukan berdasarkan area piksel resolusi output: qima_input_1k jika area ≤ 2.250.000, atau qima_input_2k jika area > 2.250.000.output_image_count integerJumlah aktual gambar output yang dikembalikan.output_image_type stringTingkat penagihan gambar output. Ditentukan berdasarkan area piksel resolusi output: qima_output_1k jika area ≤ 2.250.000, atau qima_output_2k jika area > 2.250.000.stringIdentifier permintaan unik untuk pelacakan dan troubleshooting.code stringKode kesalahan. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan.message stringPesan kesalahan detail. Hanya dikembalikan untuk permintaan yang gagal. Lihat Kode kesalahan. |
Data tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan. |