Skip to main content
Qwen - model gambar lawas

Referensi API Qwen-Image

Qwen-Image adalah model generasi gambar serbaguna yang mendukung berbagai gaya artistik dan unggul dalam complex text rendering . Model ini menangani tata letak multi-baris, generasi teks tingkat paragraf, dan rendering detail halus.

Akses cepat: Panduan pengguna| Coba online(Singapura | Beijing)| Blog teknis (lebih banyak contoh)

Contoh

Prompt

Gambar yang dihasilkan

A healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” appears prominently at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.

image

Ikhtisar model

ModelDeskripsiSpesifikasi gambar output
qwen-image-2.0-pro Recommended
Kemampuan sama dengan qwen-image-2.0-pro-2026-04-22
Seri Pro Qwen untuk generasi dan pengeditan gambar. Menawarkan rendering teks lebih kuat, tekstur realistis, dan kepatuhan semantik.
Untuk pengeditan gambar, lihat Qwen-Image Editing.
Resolusi: Atur lebar dan tinggi secara bebas. Total piksel harus antara 512×512 dan 2048×2048. Resolusi default adalah 2048×2048.Format: PNGJumlah gambar: 1–6
qwen-image-2.0-pro-2026-06-22 Recommended
qwen-image-2.0-pro-2026-04-22
qwen-image-2.0-pro-2026-03-03
qwen-image-2.0 Recommended
Kemampuan sama dengan qwen-image-2.0-2026-03-03
Seri akselerasi Qwen untuk generasi dan pengeditan gambar. Menyeimbangkan kualitas dan kecepatan respons.
Untuk pengeditan gambar, lihat Qwen-Image Editing.
qwen-image-2.0-2026-03-03 Recommended
qwen-image-max
Kemampuan sama dengan qwen-image-max-2025-12-30
Seri Max Qwen untuk generasi gambar. Memberikan realisme dan naturalitas lebih tinggi, dengan lebih sedikit artefak generasi AI.Resolusi: Lihat pengaturan parameter size untuk resolusi dan rasio aspek yang didukung.Format: PNGJumlah gambar: Tetap 1
qwen-image-max-2025-12-30
qwen-image-plus
Kemampuan sama dengan qwen-image
Seri Plus Qwen untuk generasi gambar. Unggul dalam berbagai gaya artistik dan rendering teks.
qwen-image-plus-2026-01-09
qwen-image
Hanya qwen-image-plus dan qwen-image yang mendukung panggilan asinkron.
Sebelum memanggil API, periksa daftar model yang didukung untuk wilayah Anda.

Prasyarat

Sebelum melakukan panggilan, dapatkan Kunci API dan ekspor Kunci API sebagai variabel lingkungan. Untuk melakukan panggilan menggunakan SDK, instal SDK DashScope.
Wilayah China (Beijing) dan Singapura memiliki Kunci API dan titik akhir permintaan yang terpisah. Keduanya tidak dapat saling dipertukarkan. Panggilan lintas wilayah menyebabkan kegagalan autentikasi atau kesalahan layanan.

API Sinkron (disarankan)

HTTP

Panggilan sinkron mengembalikan hasil dalam satu permintaan. Singapura:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Beijing:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda.

Parameter permintaan

  • Text-to-image
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": "qwen-image-2.0-pro",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."
            }
          ]
        }
      ]
    },
    "parameters": {
      "negative_prompt": "Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
      "prompt_extend": true,
      "watermark": false,
      "size": "2048*2048"
    }
}'
Header permintaan
Content-Type string (Wajib)Tipe konten permintaan. Harus application/json.
Authorization string (Wajib)Mengotentikasi permintaan dengan Kunci API Model Studio. Contoh: Bearer sk-xxxx.
Body permintaan
model string (wajib)Nama model. Contoh: qwen-image-2.0-pro.
input object (wajib)Informasi input.

Properti

messages array (wajib)Array objek pesan. Hanya percakapan satu giliran yang didukung, sehingga array harus berisi tepat satu elemen.

Properti

rolestring (wajib)Peran pesan. Diatur ke user.contentarray (wajib)Array objek konten pesan.

Properti

textstring(wajib)Petunjuk positif yang menjelaskan konten, gaya, dan komposisi gambar yang Anda inginkan.Mendukung bahasa Tionghoa dan Inggris. Seri qwen-image-2.0 menerima hingga 1.300 token. Model lain menerima hingga 800 token. Sistem memotong token berlebih.Catatan: Hanya satu bidang teks yang diizinkan. Menghilangkannya atau memberikan lebih dari satu mengembalikan kesalahan.
parameters object (opsional)Parameter pemrosesan gambar.

Properti

negative_prompt string (opsional)Prompt negatif yang menjelaskan apa yang tidak Anda inginkan dalam gambar.Mendukung bahasa Tionghoa dan Inggris. Panjang maksimum 500 karakter. Karakter berlebih dipotong secara otomatis.Contoh: resolusi rendah, kualitas buruk, anggota tubuh terdistorsi, jari-jari cacat, warna terlalu jenuh, tampilan seperti lilin, wajah tanpa detail, permukaan terlalu halus, kesan buatan AI, komposisi kacau, serta teks buram atau terdistorsi.size string (opsional)Resolusi gambar output, diformat sebagai width*height.Model seri qwen-image-2.0: Total piksel harus antara 512×512 dan 2048×2048. Resolusi default adalah 2048×2048. Resolusi yang direkomendasikan:
  • 2688*1536: 16:9
  • 1536*2688: 9:16
  • 2048*2048 (default): 1:1
  • 2368*1728: 4:3
  • 1728*2368: 3:4
Model seri qwen-image-max dan qwen-image-plus: Resolusi default adalah 1664*928. Resolusi yang didukung dan rasio aspeknya:
  • 1664*928 (default): 16:9
  • 1472*1104: 4:3
  • 1328*1328: 1:1
  • 1104*1472: 3:4
  • 928*1664: 9:16
n integer (opsional)Jumlah gambar output. Default adalah 1.Untuk model seri qwen-image-2.0, Anda dapat memilih 1–6 gambar.Untuk model seri qwen-image-max dan qwen-image-plus, nilai ini tetap 1. Mengatur nilai lain mengembalikan kesalahan.prompt_extend bool (opsional)Aktifkan penulisan ulang prompt cerdas. Model mengoptimalkan petunjuk positif. Tidak memengaruhi prompt negatif.
  • true: Default. Mengaktifkan penulisan ulang. Gunakan ini untuk konten gambar lebih beragam; model menambahkan detail.
  • false: Menonaktifkan penulisan ulang. Gunakan ini untuk kontrol lebih ketat atas detail gambar. Untuk hasil terbaik, optimalkan prompt Anda berdasarkan Panduan prompt text-to-image.
Hanya panggilan asinkron yang mengembalikan prompt yang ditulis ulang sebenarnya.
Prompt asli (orig_prompt): A sitting ginger cat with a joyful expression, looking lively, adorable, and incredibly lifelike.Prompt aktual (actual_prompt): Potret satwa liar fotorealistis: seekor kucing jahe duduk dengan bulu lebat yang berkilau terkena sinar matahari dan ekspresi ceria penuh semangat; matanya berbinar menunjukkan rasa ingin tahu dan kehangatan. Kepalanya sedikit miring, telinga terangkat ke depan, dan mulutnya sedikit terbuka dalam pose puas yang hidup—memancarkan pesona menggemaskan serta detail luar biasa yang tampak nyata. Pencahayaan alami yang lembut menonjolkan tekstur setiap helai kumis dan bulu, dengan sorotan halus pada moncong dan bagian dalam telinga. Latar belakang: taman musim gugur dengan efek buram lembut pada golden hour—nuansa hangat daun ambar, cahaya matahari yang menembus sela-sela pepohonan, dan sedikit petunjuk anak tangga batu berlumut. Komposisi menempatkan kucing sebagai fokus utama, ditangkap dalam fokus tajam dengan kedalaman bidang yang dangkal. Gaya: fotografi ultra-realistis, detail setara National Geographic, resolusi 8K, Canon EOS R5, bukaan f/1.2, pencahayaan sinematik, gradasi warna akurat, dan post-processing minimal. Tanpa teks atau hamparan.
watermark bool (opsional)Menambahkan watermark “Qwen-Image” di pojok kanan bawah gambar. Default: false. Gaya watermark: 1seed integer (opsional)Bibit angka acak. Rentang valid: [0,2147483647].Menggunakan seed yang sama menghasilkan output serupa. Jika dihilangkan, algoritma menggunakan seed acak.Catatan: Generasi gambar bersifat probabilistik. Bahkan dengan seed yang sama, hasilnya mungkin berbeda.

Parameter respons

  • Tugas berhasil
  • Tugas gagal
URL gambar hanya berlaku selama 24 jam lalu secara otomatis dihapus. Simpan gambar yang dihasilkan segera.
{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "content": [
                        {
                            "image": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "height": 2048,
        "image_count": 1,
        "width": 2048
    },
    "request_id": "d0250a3d-b07f-49e1-bdc8-6793f4929xxx"
}
output objectInformasi output tugas.

Properti

choices arrayOutput model. Array ini berisi tepat satu elemen.

Properti

finish_reason stringAlasan tugas dihentikan. Nilainya stop untuk penghentian alami.message objectPesan respons model.

Properti

rolestringPeran pesan. Nilai tetap: assistant.contentarray

Properti

image stringURL gambar yang dihasilkan (format PNG). Kedaluwarsa setelah 24 jam. Unduh dan simpan segera.
task_metric objectStatistik hasil tugas. Tidak dikembalikan untuk model seri qwen-image-2.0.

Properti

TOTAL integerTotal jumlah tugas.SUCCEEDED integerJumlah tugas yang berhasil.FAILED integerJumlah tugas yang gagal.
usage object
Bidang ini hanya dikembalikan dalam panggilan asinkron. Panggilan SDK ImageSynthesis sinkron tidak mengembalikan bidang ini.
Statistik output. Hanya menghitung hasil yang berhasil.

Properti

image_count integerJumlah gambar yang dihasilkan. Untuk model seri qwen-image-2.0 ini sama dengan n yang diminta (1–6); untuk seri qwen-image-max dan qwen-image-plus tetap 1.width integerLebar gambar yang dihasilkan, dalam piksel.height integerTinggi gambar yang dihasilkan, dalam piksel.
request_id 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.

Panggilan SDK DashScope

SDK DashScope mendukung Python dan Java. Nama parameter dalam SDK sangat mirip dengan parameter HTTP, dan struktur parameter mengikuti konvensi khas bahasa pemrograman. Untuk parameter panggilan sinkron, lihat HTTP.
  • Python
  • Java
Instal SDK Python DashScope versi terbaru untuk menghindari kesalahan waktu proses: Instal SDK.
Contoh permintaan
import json
import os
import dashscope
from dashscope import MultiModalConversation

# Wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. URL berbeda berdasarkan wilayah.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

messages = [
    {
        "role": "user",
        "content": [
            {"text": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."}
        ]
    }
]

# Kunci API berbeda antara wilayah Beijing dan Singapura. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika Anda belum mengatur variabel lingkungan, ganti baris di bawah ini dengan: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-2.0-pro",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=False,
    prompt_extend=True,
    negative_prompt="Low resolution, low quality, distorted limbs, malformed fingers, oversaturated colors, wax-figure appearance, lack of facial detail, excessive smoothness, AI-looking artifacts, chaotic composition, blurry or warped text.",
    size='2048*2048'
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
else:
    print(f"Kode status HTTP: {response.status_code}")
    print(f"Kode kesalahan: {response.code}")
    print(f"Pesan kesalahan: {response.message}")
    print("Lihat dokumentasi: https://www.alibabacloud.com/help/en/model-studio/error-code")
Contoh respons
URL gambar kedaluwarsa setelah 24 jam. Unduh gambar segera.
{
    "status_code": 200,
    "request_id": "d2d1a8c0-325f-9b9d-8b90-xxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": null,
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "role": "assistant",
                    "content": [
                        {
                            "image": "https://dashscope-result-wlcb.oss-cn-wulanchabu.aliyuncs.com/xxx.png?Expires=xxx"
                        }
                    ]
                }
            }
        ]
    }
}

Asynchronous API

Hanya qwen-image-plus dan qwen-image yang mendukung panggilan asinkron.

HTTP

Panggilan asinkron menggunakan alur kerja HTTP dua langkah:
  1. Buat tugas untuk mendapatkan task ID: Kirim permintaan untuk membuat tugas. Respons-nya mengembalikan task ID (task_id).
  2. Lakukan polling hasil menggunakan task ID: Lakukan polling status tugas dengan task_id hingga selesai dan mengembalikan URL gambar.

Langkah 1: Buat tugas untuk mendapatkan task ID

Singapura:POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis Beijing:POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
  • Setelah tugas dibuat, gunakan task_id yang dikembalikan untuk menanyakan hasilnya. task_id berlaku selama 24 jam. Jangan membuat tugas duplikat. Sebagai gantinya, gunakan polling untuk mengambil hasilnya.
  • Untuk panduan pemula, lihat Panggil API dengan Postman atau cURL.
Parameter permintaan
  • Text-to-image
Hanya qwen-image-plus dan qwen-image yang mendukung panggilan asinkron.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "qwen-image-plus",
    "input": {
        "prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."
    },
    "parameters": {
        "negative_prompt":" ",
        "size": "1664*928",
        "n": 1,
        "prompt_extend": true,
        "watermark": false
    }
}'
Header permintaan
Content-Type string (Wajib)Tipe konten dari 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 diatur ke enable.
Jika header permintaan ini tidak disertakan, kesalahan "current user api does not support synchronous calls" akan dikembalikan.
Body permintaan
model string (wajib)Nama model. Hanya qwen-image-plus dan qwen-image yang mendukung panggilan asinkron.Contoh: qwen-image-plus.
input object (wajib)Informasi input.

Properti

prompt string (wajib)Petunjuk positif yang menjelaskan elemen visual dan karakteristik yang Anda inginkan dalam gambar yang dihasilkan.Mendukung bahasa Tionghoa dan Inggris. Panjang maksimum adalah 800 karakter. Setiap karakter Tionghoa, huruf, angka, atau simbol dihitung sebagai satu karakter. Karakter berlebih dipotong secara otomatis.Contoh: Seekor kucing oranye duduk dengan ekspresi gembira, hidup dan menggemaskan, sangat realistis.negative_prompt string (opsional)Prompt negatif yang menjelaskan hal-hal yang tidak Anda inginkan dalam gambar.Mendukung bahasa Tionghoa dan Inggris. Panjang maksimum adalah 500 karakter. Karakter berlebih dipotong secara otomatis.Contoh: Resolusi rendah, kualitas rendah, anggota tubuh terdistorsi, jari cacat, warna terlalu jenuh, penampilan seperti lilin, tidak ada detail wajah, permukaan terlalu halus, tampilan hasil AI. Komposisi kacau. Teks buram atau terdistorsi.
parameters object (opsional)Parameter pemrosesan gambar.

Properti

size string (opsional)Resolusi gambar output, diformat sebagai width*height.Model seri qwen-image-2.0: Total piksel harus berada di antara 512×512 dan 2048×2048. Resolusi default adalah 2048×2048. Resolusi yang direkomendasikan:
  • 2688*1536: 16:9
  • 1536*2688: 9:16
  • 2048*2048 (default): 1:1
  • 2368*1728: 4:3
  • 1728*2368: 3:4
Model seri qwen-image-max dan qwen-image-plus: Resolusi default adalah 1664*928. Resolusi yang didukung beserta rasio aspeknya:
  • 1664*928 (default): 16:9
  • 1472*1104: 4:3
  • 1328*1328: 1:1
  • 1104*1472: 3:4
  • 928*1664: 9:16
n integer (opsional)Jumlah gambar yang dihasilkan. Nilai ini tetap 1. Mengatur nilai lain akan mengembalikan error.prompt_extend bool (opsional)Aktifkan penulisan ulang prompt cerdas. Model mengoptimalkan prompt positif. Tidak memengaruhi prompt negatif.
  • true: Default. Mengaktifkan penulisan ulang. Gunakan ini untuk konten gambar yang lebih beragam; model menambahkan detail.
  • false: Menonaktifkan penulisan ulang. Gunakan ini untuk kontrol lebih ketat atas detail gambar. Untuk hasil terbaik, optimalkan prompt Anda berdasarkan Panduan prompt text-to-image.
Hanya panggilan asinkron yang mengembalikan prompt yang ditulis ulang sebenarnya.
Prompt asli (orig_prompt): Seekor kucing jahe duduk dengan ekspresi gembira, terlihat hidup, menggemaskan, dan sangat mirip aslinya.Prompt aktual (actual_prompt): Potret satwa liar fotorealistik: Seekor kucing jahe duduk dengan bulu lebat yang terkena sinar matahari dan ekspresi gembira yang hidup, matanya berkilau penuh rasa ingin tahu dan kehangatan. Kepalanya sedikit miring, telinga tegak ke depan, mulut terbuka perlahan dalam pose puas—memancarkan pesona menggemaskan dan detail yang sangat mirip aslinya. Pencahayaan alami yang lembut menonjolkan tekstur setiap kumis dan helai bulu, dengan sorotan halus pada moncong dan telinga bagian dalam. Latar belakang: taman musim gugur yang kabur lembut pada golden hour—nuansa hangat daun amber, sinar matahari yang menembus pepohonan, dan jejak samar anak tangga batu berlumut. Komposisi menempatkan kucing sebagai fokus utama, diambil dengan fokus tajam dan depth of field dangkal. Gaya: fotografi ultra-realistis, detail tingkat National Geographic, resolusi 8K, Canon EOS R5, aperture f/1.2, pencahayaan sinematik, gradasi warna sesuai kenyataan, post-processing minimal. Tidak ada teks atau overlay.
watermark bool (opsional)Menambahkan watermark “Qwen-Image” di pojok kanan bawah gambar. Default: false. Gaya watermark: 1seed integer (opsional)Seed angka acak. Rentang valid: [0,2147483647].Menggunakan seed yang sama menghasilkan output serupa. Jika dihilangkan, algoritma menggunakan seed acak.Catatan: Pembuatan gambar bersifat probabilistik. Bahkan dengan seed yang sama, hasilnya dapat bervariasi.
Parameter respons
  • Respons sukses
  • Respons error
Simpan task_id untuk menanyakan status dan hasil tugas.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}
outputobjectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk penanyakan selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
request_id stringIdentifier unik permintaan 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.

Langkah 2: Lakukan polling hasil menggunakan task ID

  • Singapura
  • Tiongkok (Beijing)
GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Saat memanggil, ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.
  • Rekomendasi polling: Pembuatan gambar memakan waktu. Gunakan mekanisme polling dengan interval yang masuk akal, misalnya 10 detik.
  • Transisi status tugas: PENDING → RUNNING → SUCCEEDED atau FAILED.
  • Tautan hasil: Setelah tugas berhasil, URL gambar yang berlaku selama 24 jam dikembalikan. Unduh dan simpan gambar ke penyimpanan permanen, seperti OSS.
Parameter permintaan
  • Lakukan polling hasil tugas
Ganti {task_id} dengan nilai task_id yang dikembalikan oleh panggilan API sebelumnya. task_id berlaku untuk penanyakan selama 24 jam, Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Header permintaan
Authorization string (Wajib)Mengotentikasi permintaan dengan kunci API Model Studio. Contoh: Bearer sk-xxxx.
Parameter path URL
task_id string (Wajib)ID tugas.
Parameter respons
  • Tugas berhasil
  • Tugas gagal
Data tugas (status tugas dan URL gambar) hanya disimpan selama 24 jam, lalu secara otomatis dihapus. Segera simpan gambar yang dihasilkan.
{
    "request_id": "7434edb2-3cba-44e6-a772-xxxxxx",
    "output": {
        "task_id": "878f591e-ebdf-4e45-97eb-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-09 11:38:54.741",
        "scheduled_time": "2025-09-09 11:38:54.781",
        "end_time": "2025-09-09 11:39:19.484",
        "results": [
            {
                "orig_prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.",
                "actual_prompt": "Childhood-inspired hand-drawn poster design: Three playful puppies joyfully interact with a colorful ball on a vibrant patch of lush green grass. Delicate decorative elements including fluttering birds and twinkling stars are scattered throughout. At the top center, the bold, blue cartoon-style title “Come Play Ball!” stands out prominently. Directly beneath, the subtitle “Come [Show Off Your Skills]!” is rendered in cheerful green lettering. A whimsical speech bubble near one of the puppies contains the playful text: “Hehe, watch me amaze my little friends next!” At the bottom edge, smaller supplementary text reads: “We get to play ball with our friends again!” The color palette is centered on fresh greens and sky blues, accented with pops of bright pink and sunny yellow, enhancing the cheerful, childlike atmosphere. Style evokes nostalgic, hand-inked illustrations with soft textures, gentle linework, and a whimsical, storybook-like composition.",
                "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/7d/xxx.png?Expires=xxxx"
            }
        ]
    },
    "usage": {
        "image_count": 1
    }
}
outputobjectInformasi output tugas.

Properti

task_id stringID tugas. Berlaku untuk penanyakan selama 24 jam.task_status stringStatus tugas.

Nilai enumerasi

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: Tugas tidak ada atau statusnya tidak diketahui.
submit_time 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.results arrayDaftar hasil tugas, termasuk URL gambar, prompt, dan pesan kesalahan untuk tugas yang gagal.

Properti

orig_prompt stringPrompt input asli, sesuai dengan parameter permintaan prompt.actual_prompt stringPrompt yang dioptimalkan yang digunakan saat penulisan ulang prompt diaktifkan. Tidak dikembalikan jika dinonaktifkan.url stringURL gambar yang dihasilkan. Kedaluwarsa setelah 24 jam. Segera unduh dan simpan gambarnya.
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.
usage objectStatistik output. Hanya menghitung hasil yang sukses.

Properti

image_count integerJumlah gambar yang dihasilkan. Untuk model seri qwen-image-2.0 jumlah ini sama dengan n yang diminta (1–6); untuk model seri qwen-image-max dan qwen-image-plus nilainya tetap 1.
request_id stringIdentifier unik permintaan untuk pelacakan dan troubleshooting.

DashScope SDK

DashScope SDK mendukung Python dan Java. Nama parameter SDK sangat mirip dengan padanannya di HTTP. Struktur parameter mengikuti konvensi khas bahasa pemrograman masing-masing. Untuk parameter panggilan asinkron, lihat HTTP. Model gambar memerlukan waktu pemrosesan yang lebih lama, sehingga layanan dasarnya menggunakan eksekusi asinkron. SDK menyediakan dua mode:
  • Panggilan sinkron (mode blocking): SDK menunggu hingga tugas selesai dan mengembalikan hasil akhir. Ini sesuai dengan perilaku standar panggilan sinkron.
  • Panggilan asinkron (mode non-blocking): Panggilan langsung mengembalikan ID tugas. Lakukan polling status tugas dan hasil akhir menggunakan ID tersebut.

Python SDK

Instal DashScope Python SDK versi terbaru untuk menghindari error waktu proses: Install SDK.
  • Sinkron
  • Asinkron
Contoh permintaan
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
import dashscope

# Wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya. URL berbeda-beda tergantung wilayah.
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

prompt = "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere."

# Kunci API berbeda antara wilayah Beijing dan Singapura. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika Anda belum mengatur variabel lingkungan, ganti baris di bawah ini dengan: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

print('----Panggilan sinkron, harap tunggu sebentar----')
rsp = ImageSynthesis.call(api_key=api_key,
                          model="qwen-image-plus", # Hanya qwen-image-plus dan qwen-image yang mendukung panggilan asinkron
                          prompt=prompt,
                          negative_prompt=" ",
                          n=1,
                          size='1664*928',
                          prompt_extend=True,
                          watermark=False)
print(f'response: {rsp}')
if rsp.status_code == HTTPStatus.OK:
    # Simpan gambar di direktori saat ini
    for result in rsp.output.results:
        file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
        with open('./%s' % file_name, 'wb+') as f:
            f.write(requests.get(result.url).content)
else:
    print(f'Panggilan sinkron gagal, status_code: {rsp.status_code}, code: {rsp.code}, message: {rsp.message}')
Contoh respons
URL kedaluwarsa setelah 24 jam. Unduh gambar segera.
{
    "status_code": 200,
    "request_id": "a47b1a65-7041-4565-9068-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "91093132-475e-43cf-b94e-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxxxx",
                "orig_prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.",
                "actual_prompt": "Childhood-inspired hand-drawn poster design: Three playful puppies joyfully interact with a colorful ball on a vibrant patch of lush green grass. Delicate decorative elements including fluttering birds and twinkling stars are scattered throughout. At the top center, the bold, blue cartoon-style title “Come Play Ball!” stands out prominently. Directly beneath, the subtitle “Come [Show Off Your Skills]!” is rendered in cheerful green lettering. A whimsical speech bubble near one of the puppies contains the playful text: “Hehe, watch me amaze my little friends next!” At the bottom edge, smaller supplementary text reads: “We get to play ball with our friends again!” The color palette is centered on fresh greens and sky blues, accented with pops of bright pink and sunny yellow, enhancing the cheerful, childlike atmosphere. Style evokes nostalgic, hand-inked illustrations with soft textures, gentle linework, and a whimsical, storybook-like composition."
            }
        ],
        "submit_time": "2025-09-09 13:39:20.659",
        "scheduled_time": "2025-09-09 13:39:20.717",
        "end_time": "2025-09-09 13:39:45.233"
    },
    "usage": {
        "image_count": 1
    }
}

Java SDK

Anda harus menginstal DashScope Java SDK versi terbaru. Jika tidak, error waktu proses dapat terjadi: Install SDK.
  • Sinkron
  • Asinkron
Contoh permintaan
// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
import java.util.HashMap;
import java.util.Map;

public class Text2Image {
    static {
        // Wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya. URL berbeda-beda tergantung wilayah.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
    }

    // Kunci API berbeda antara wilayah Beijing dan Singapura. Dapatkan Kunci API Anda: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    // Jika Anda belum mengatur variabel lingkungan, ganti baris di bawah ini dengan: static String apiKey = "sk-xxx"
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    public static void basicCall() throws ApiException, NoApiKeyException {
        String prompt = "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.";
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);
        parameters.put("watermark", false);
        parameters.put("negative_prompt", " ");
        ImageSynthesisParam param =
                ImageSynthesisParam.builder()
                        .apiKey(apiKey)
                        // Hanya qwen-image-plus dan qwen-image yang mendukung panggilan asinkron
                        .model("qwen-image-plus")
                        .prompt(prompt)
                        .n(1)
                        .size("1664*928")
                        .parameters(parameters)
                        .build();

        ImageSynthesis imageSynthesis = new ImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            System.out.println("---Panggilan sinkron, harap tunggu sebentar----");
            result = imageSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args){
        try{
            basicCall();
        }catch(ApiException|NoApiKeyException e){
            System.out.println(e.getMessage());
        }
    }
}
Contoh respons
URL kedaluwarsa setelah 24 jam. Unduh gambar segera.
{
    "request_id": "9f3044ba-528f-4606-8830-xxxxxx",
    "output": {
        "task_id": "fecf4c7f-3508-45f4-8454-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "orig_prompt": "Healing-style hand-drawn poster featuring three puppies playing with a ball on lush green grass, adorned with decorative elements such as birds and stars. The main title “Come Play Ball!” is prominently displayed at the top in bold, blue cartoon font. Below it, the subtitle “Come [Show Off Your Skills]!” appears in green font. A speech bubble adds playful charm with the text: “Hehe, watch me amaze my little friends next!” At the bottom, supplementary text reads: “We get to play ball with our friends again!” The color palette centers on fresh greens and blues, accented with bright pink and yellow tones to highlight a cheerful, childlike atmosphere.",
                "actual_prompt": "Childhood-inspired hand-drawn poster design: Three playful puppies joyfully interact with a colorful ball on a vibrant patch of lush green grass. Delicate decorative elements including fluttering birds and twinkling stars are scattered throughout. At the top center, the bold, blue cartoon-style title “Come Play Ball!” stands out prominently. Directly beneath, the subtitle “Come [Show Off Your Skills]!” is rendered in cheerful green lettering. A whimsical speech bubble near one of the puppies contains the playful text: “Hehe, watch me amaze my little friends next!” At the bottom edge, smaller supplementary text reads: “We get to play ball with our friends again!” The color palette is centered on fresh greens and sky blues, accented with pops of bright pink and sunny yellow, enhancing the cheerful, childlike atmosphere. Style evokes nostalgic, hand-inked illustrations with soft textures, gentle linework, and a whimsical, storybook-like composition.",
                "url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
            }
        ]
    },
    "usage": {
        "image_count": 1
    }
}

Penggunaan dengan OpenAI Agents SDK

Model pembuatan gambar seperti Qwen-Image dipanggil melalui API native DashScope dan tidak mendukung mode kompatibel OpenAI (compatible-mode), sehingga tidak dapat digunakan secara langsung sebagai model penalaran suatu Agent dalam OpenAI Agents SDK. Dalam kerangka kerja agent seperti OpenAI Agents SDK, Anda dapat membungkus pembuatan gambar sebagai tool (function tool) dan membiarkan model chat teks yang mendukung mode kompatibel OpenAI (misalnya qwen-plus) bertindak sebagai inti penalaran Agent untuk mengoordinasikannya. Contohnya: Sebelum menjalankan, instal dependensi: pip install openai-agents dashscope.
import os
import asyncio
import dashscope
from openai import AsyncOpenAI
from dashscope import MultiModalConversation
from agents import Agent, Runner, function_tool, OpenAIChatCompletionsModel

# Baca Kunci API Model Studio dari variabel lingkungan
# (atau ganti dengan api_key="sk-xxx")
API_KEY = os.getenv("DASHSCOPE_API_KEY")

# Wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya. URL berbeda-beda tergantung wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
# Model chat teks (inti penalaran Agent) diakses melalui mode kompatibel OpenAI
client = AsyncOpenAI(api_key=API_KEY, base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1")

# Bungkus pembuatan gambar sebagai function tool agar dapat dipanggil oleh Agent
@function_tool
def generate_image(prompt: str) -> str:
    """Generate an image from a text description and return its URL. prompt: the text description of the image."""
    rsp = MultiModalConversation.call(
        api_key=API_KEY,
        model="qwen-image",
        messages=[{"role": "user", "content": [{"text": prompt}]}],
        result_format="message",
    )
    if rsp.status_code != 200:
        return f"Generation failed: {rsp.code} {rsp.message}"
    return rsp.output.choices[0].message.content[0]["image"]

agent = Agent(
    name="Image Assistant",
    instructions="You are an image generation assistant. When the user wants an image, call the generate_image tool and return the image URL to the user.",
    model=OpenAIChatCompletionsModel(model="qwen-plus", openai_client=client),
    tools=[generate_image],
)

async def main():
    result = await Runner.run(agent, "Draw a corgi running on the grass")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Billing and rate limiting

  • Untuk kuota gratis dan informasi harga, lihat Model pricing.
  • Untuk batas laju (rate limits), lihat Qwen-Image.
  • Detail Tagihan: Setiap successfully generated image akan dikenai biaya. Panggilan yang gagal atau error pemrosesan tidak dikenai biaya maupun mengurangi new user free quota Anda.

Kode error

Jika pemanggilan model gagal dan mengembalikan pesan error, lihat Kode error untuk resolusi.

FAQ

T: Haruskah saya mengaktifkan atau menonaktifkan parameter prompt_extend?

J: Aktifkan opsi ini (default) jika Anda menginginkan konten gambar yang lebih beragam dan agar model menambahkan detail. Nonaktifkan jika Anda memerlukan kontrol yang lebih ketat terhadap detail gambar, dan optimalkan prompt Anda menggunakan Text-to-Image Prompt Guide.

T: Apa perbedaan antara qwen-image, qwen-image-plus, qwen-image-max, qwen-image-2.0, dan qwen-image-edit?

J:
  • Model gabungan untuk pembuatan dan pengeditan gambar: Mendukung teks-ke-gambar dan Pengeditan gambar.
    • qwen-image-2.0-pro dan qwen-image-2.0-pro-2026-03-03: Kemampuan sama. Seri Pro memberikan rendering teks yang lebih profesional, tekstur realistis yang lebih halus, adegan realistis yang lebih detail, serta kepatuhan semantik yang lebih kuat. Hanya mendukung panggilan sinkron.
    • qwen-image-2.0 dan qwen-image-2.0-2026-03-03: Kemampuan sama. Versi akselerasi ini menyeimbangkan kinerja dan kualitas model. Hanya mendukung panggilan sinkron.
  • Model teks-ke-gambar: Menghasilkan gambar dari deskripsi teks.
    • qwen-image-max dan qwen-image-max-2025-12-30: Kemampuan sama. Dibandingkan dengan qwen-image-plus, model ini menghasilkan realisme dan naturalitas yang lebih baik, dengan hasil unggul pada tekstur karakter, detail, dan rendering teks.
    • qwen-image dan qwen-image-plus: Kemampuan sama, tetapi qwen-image-plus lebih hemat biaya.
    • qwen-image-plus-2026-01-09: Versi Snapshot baru dari Qwen-Image. Ini merupakan versi yang telah disuling dan dipercepat dari qwen-image-max yang mendukung pembuatan gambar berkualitas tinggi secara cepat.
  • Model pengeditan gambar:qwen-image-edit: Melakukan transformasi gambar-ke-gambar, inpainting, dan operasi lainnya berdasarkan gambar input dan instruksi teks. Untuk informasi selengkapnya, lihat Qwen - image editing.

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

J: Gambar yang dihasilkan oleh model disimpan di OSS. API mengembalikan URL publik temporary. Untuk mengonfigurasi daftar putih firewall untuk URL unduh 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 account manager Anda untuk mendapatkan daftar Nama domain OSS terbaru.
Pembuatan Gambar
Video Generation
Model Dunia
Audio
  • Pembuatan audio
Realtime API
Penyematan Teks
TokenPlan
Model production