Cara Menggunakan Qwen Image 3 Pro API melalui DashScope: Tutorial Pengembang

Cara Menggunakan Qwen Image 3 Pro API melalui DashScope: Tutorial Pengembang

qwen-image-3.0-pro Alibaba adalah model pembuatan gambar unggulan yang disajikan melalui Model Studio, juga dikenal sebagai DashScope atau Bailian. Ini menargetkan pengembang backend yang membutuhkan endpoint text-to-image yang andal dengan harga yang dapat diprediksi. ID model resmi qwen-image-3.0-pro didokumentasikan dalam katalog Model Studio Alibaba (Alibaba Cloud Model Studio docs, 2026), dan Anda dapat memanggilnya dari klien HTTP mana pun.

Tutorial ini membahas integrasi penuh. Pada akhirnya, Anda akan memiliki kunci API, panggilan cURL yang berfungsi, cuplikan Python, dan gambaran yang jelas tentang struktur biaya per gambar.

Poin Penting

• ID Model: qwen-image-3.0-pro, disajikan di Alibaba Cloud Model Studio / DashScope di https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026).
• Autentikasi: atur DASHSCOPE_API_KEY sebagai variabel lingkungan, lalu kirim sebagai token Bearer (Promptfoo, 2026).
• Harga referensi: pendahulu qwen-image-2.0-pro berharga $0,075 per gambar yang dihasilkan pada harga resmi Alibaba (Alibaba Cloud pricing, 2026).
• Setiap model gambar memiliki kuota gratis untuk pengujian sebelum Anda membayar sepeser pun (Alibaba Image API FAQ, 2026).

Prasyarat

Sebelum Anda menulis kode apa pun, konfirmasikan bahwa Anda memiliki akun Alibaba Cloud dengan akses Model Studio. Panduan resmi "Panggilan API Pertama ke Qwen" mencantumkan tiga hal yang dibutuhkan setiap pengembang: Kunci API yang dihasilkan di konsol Model Studio, ID Ruang Kerja yang terikat pada proyek Anda, dan akses ke endpoint HTTP DashScope (Alibaba Cloud, 2026).

Anda juga membutuhkan alat dasar. Terminal dengan cURL, Python 3.9 atau yang lebih baru, dan pustaka requests mencakup semua yang ada dalam tutorial ini. Tidak ada SDK berpemilik yang diperlukan. Jika Anda pernah memanggil OpenAI API dari skrip, pola DashScope akan terasa familiar, karena keduanya menggunakan token Bearer dan badan permintaan JSON.

Pola yang direkomendasikan adalah menyimpan satu Ruang Kerja khusus per lingkungan, sehingga kunci staging tidak pernah menyentuh kuota produksi. Pemisahan ini juga membuat atribusi biaya lebih bersih di akhir bulan.

Langkah 1: Dapatkan Kunci API dan ID Ruang Kerja Anda

Kunci API adalah kredensial yang mengotorisasi setiap panggilan yang Anda buat ke qwen-image-3.0-pro. Panduan memulai Alibaba menginstruksikan pengembang untuk membuat kunci di dalam konsol Model Studio dan kemudian menyalin ID Ruang Kerja dari dasbor yang sama (Alibaba Cloud, 2026). Perlakukan kedua nilai tersebut sebagai rahasia.

Untuk mengambilnya:

1. Masuk ke konsol Model Studio di portal Alibaba Cloud.
2. Buka bagian API Keys dan klik Create API Key.
3. Salin kunci yang dihasilkan segera. Konsol menyembunyikan nilai penuh setelah pembuatan.
4. Catat Workspace ID yang ditampilkan di bagian atas dasbor.

Simpan kunci di pengelola kata sandi atau backend rahasia tim Anda. Jangan tempelkan ke file sumber. ID Ruang Kerja kurang sensitif tetapi tetap layak disimpan dalam konfigurasi daripada sebaris.

Kapsul Kutipan: Panduan resmi Alibaba "Panggilan API Pertama ke Qwen" menginstruksikan pengembang untuk membuat Kunci API di konsol Model Studio, menyalin ID Ruang Kerja dari dasbor yang sama, dan memanggil model melalui endpoint DashScope di https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026).

Langkah 2: Atur Variabel Lingkungan DASHSCOPE_API_KEY

Memuat kunci ke dalam variabel lingkungan menjauhkannya dari kode Anda dan dari kontrol versi. Pola komunitas yang didokumentasikan oleh Promptfoo adalah mengatur variabel bernama DASHSCOPE_API_KEY sebelum menjalankan skrip Anda, yang kemudian dibaca oleh klien HTTP pada waktu permintaan (Promptfoo, 2026).

Di macOS dan Linux:

export DASHSCOPE_API_KEY="sk-your-key-here"

Di Windows PowerShell:

$env:DASHSCOPE_API_KEY = "sk-your-key-here"

Untuk pengaturan permanen, tambahkan baris ekspor ke ~/.zshrc, ~/.bashrc, atau variabel lingkungan pengguna Windows Anda. Mulai ulang terminal Anda setelahnya. Verifikasi variabel dimuat sebelum melanjutkan:

echo $DASHSCOPE_API_KEY

Pengaturan umum adalah file .env ditambah pemuat seperti python-dotenv, sehingga konfigurasi yang sama berfungsi di seluruh pengembangan lokal, CI, dan penyebaran kontainer. Ingatlah untuk menambahkan .env ke .gitignore agar kunci tidak pernah dikomit.

Langkah 3: Lakukan Panggilan Pembuatan Gambar Pertama Anda dengan cURL

Endpoint DashScope di https://dashscope-us.aliyuncs.com/api/v1 adalah titik masuk untuk setiap model Qwen, termasuk qwen-image-3.0-pro (Alibaba Cloud, 2026). Panggilan menggunakan token Bearer di header Authorization dan badan JSON yang menamai model ditambah prompt Anda.

Di bawah ini adalah permintaan cURL ilustratif berdasarkan endpoint dan pola autentikasi yang didokumentasikan. Nama bidang dan jalur permintaan yang tepat mengikuti konvensi DashScope, tetapi Anda harus mengonfirmasi skema saat ini terhadap referensi API resmi di Qwen API via DashScope sebelum mengirim ke produksi.

# Contoh ilustratif. Konfirmasikan nama bidang dan jalur yang tepat terhadap:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
curl -X POST "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-DashScope-Async: enable" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "prompt": "A cozy bookstore cafe in autumn, warm light, highly detailed"
    },
    "parameters": {
      "size": "1024*1024",
      "n": 1
    }
  }'

Beberapa catatan praktis:

• Beberapa endpoint gambar DashScope bersifat asinkron, artinya respons pertama mengembalikan ID tugas, dan Anda melakukan polling URL kedua untuk mengambil gambar yang sudah selesai. Periksa referensi API untuk perilaku pasti qwen-image-3.0-pro.
• Pertahankan prompt di bawah batas token yang didokumentasikan. Prompt yang panjang dapat terpotong secara diam-diam.
• Gunakan parameter size yang cocok dengan salah satu rasio aspek yang didukung, jika tidak, panggilan mungkin kembali ke default.

Kapsul Kutipan: Endpoint resmi DashScope di https://dashscope-us.aliyuncs.com/api/v1 melayani qwen-image-3.0-pro, dengan referensi parameter input dan output lengkap yang didokumentasikan oleh Alibaba Cloud (Alibaba Cloud, 2026).

Langkah 4: Mengurai Respons di Python

Python adalah bahasa yang paling umum untuk membungkus API gambar karena pustaka requests membuat penguraian JSON menjadi mudah. Setelah panggilan kembali, Anda mengekstrak URL gambar yang dihasilkan, mengunduhnya, dan menyimpannya ke disk atau penyimpanan objek.

Berikut adalah skrip ilustratif singkat. Seperti halnya cURL, konfirmasikan nama bidang respons terhadap referensi API resmi sebelum mengandalkannya.

# Contoh ilustratif. Konfirmasikan skema respons terhadap:
# https://www.alibabacloud.com/help/en/model-studio/qwen-api-via-dashscope
import os
import requests

API_KEY = os.environ["DASHSCOPE_API_KEY"]
ENDPOINT = "https://dashscope-us.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

payload = {
    "model": "qwen-image-3.0-pro",
    "input": {
        "prompt": "A cozy bookstore cafe in autumn, warm light, highly detailed"
    },
    "parameters": {
        "size": "1024*1024",
        "n": 1
    }
}

response = requests.post(ENDPOINT, headers=headers, json=payload)
response.raise_for_status()
data = response.json()

# Nama bidang di bawah ini bersifat ilustratif. Verifikasi terhadap referensi API resmi.
image_url = data["output"]["results"][0]["url"]
print("Generated image URL:", image_url)

# Unduh file
img = requests.get(image_url)
with open("output.png", "wb") as f:
    f.write(img.content)

Beberapa tips tingkat produksi:

• Bungkus panggilan dalam retry dengan backoff eksponensial. Gangguan jaringan bisa terjadi.
• Tambahkan batas waktu. Pembuatan gambar dapat memakan waktu beberapa detik.
• Catat ID permintaan lengkap, biasanya dikembalikan dalam header respons, sehingga dukungan Alibaba dapat melacak kegagalan.

Membantu untuk menambahkan lapisan abstraksi tipis antara klien API dan logika bisnis. Dengan begitu, menukar model nanti (misalnya ke endpoint edit atau rilis Qwen yang lebih baru) hanya mengubah satu modul.

Berapa Biaya Qwen Image 3 Pro?

Harga per gambar yang dihasilkan, dan Alibaba hanya menagih Anda untuk generasi yang berhasil. Halaman harga resmi mencantumkan qwen-image-2.0-pro seharga $0,075 per gambar (Alibaba Cloud pricing, 2026). Penyedia pihak ketiga menawarkan model gambar Qwen dengan harga berbeda: Fal mencantumkan model gambar Qwen dengan harga sekitar $0,021 per gambar, dan Replicate mengenakan biaya sekitar $0,030 per gambar pada 1024x1024 (Puter pricing breakdown, 2026; pricepertoken, 2026).

Untuk qwen-image-3.0-pro secara khusus, perlakukan harga 2.0-pro sebagai referensi resmi terdekat, lalu verifikasi angka saat ini di halaman harga Model Studio sebelum membuat anggaran.

Kapsul Kutipan: Model Studio Alibaba mematok harga qwen-image-2.0-pro sebesar $0,075 per gambar yang dihasilkan, hanya menagih generasi yang berhasil, sementara penyedia pihak ketiga seperti Fal dan Replicate mencantumkan model gambar Qwen masing-masing sekitar $0,021 dan $0,030 per gambar (Alibaba Cloud, 2026; Puter, 2026).

Anggaran bulanan kasar untuk aplikasi kecil mungkin terlihat seperti ini:

Harga per Juli 2026.

Kuota Gratis dan Batasan

Setiap model gambar di Model Studio dilengkapi dengan kuota gratis, sehingga Anda dapat menguji sebelum Anda berkomitmen untuk mengeluarkan biaya (Alibaba Image API FAQ, 2026). Kuota diatur ulang sesuai jadwal yang didokumentasikan dalam FAQ.

Beberapa petunjuk praktis:

• Gunakan kuota gratis untuk memvalidasi template prompt dan kombinasi parameter.
• Pantau penggunaan di dasbor Model Studio untuk menghindari tagihan kejutan setelah Anda beralih ke tingkatan berbayar.
• Jika pengujian Anda tiba-tiba mulai gagal dengan kesalahan kuota, periksa kembali apakah tingkat gratis telah kedaluwarsa atau apakah Anda beralih Ruang Kerja.

Di Luar Text-to-Image: API Edit

Keluarga Qwen juga mencakup endpoint pengeditan gambar khusus. Ini mendukung input dan output multi-gambar, pengeditan teks dalam gambar, penambahan, penghapusan, dan pemindahan objek, serta perubahan pose (Qwen-Image Edit API, 2026).

Ini penting karena panggilan edit menggunakan bentuk permintaan yang berbeda dari panggilan text-to-image. Jika produk Anda membutuhkan penggantian latar belakang atau penghapusan objek, Anda akan mengakses endpoint terpisah dengan parameter dan harga sendiri. Rencanakan dua jalur integrasi: satu untuk pembuatan, satu untuk pengeditan.

FAQ

Apa ID model untuk Qwen Image 3 Pro?

ID model resmi adalah qwen-image-3.0-pro, disajikan di Alibaba Cloud Model Studio / DashScope di https://dashscope-us.aliyuncs.com/api/v1 (Alibaba Cloud, 2026). Gunakan string persis ini di bidang model pada badan permintaan Anda.

Bagaimana cara mengautentikasi panggilan DashScope API?

Atur variabel lingkungan DASHSCOPE_API_KEY, lalu kirim sebagai token Bearer di header Authorization setiap permintaan (Promptfoo, 2026). Jangan pernah mengkodekan kunci di file sumber atau mengkomitnya ke kontrol versi.

Berapa biaya Qwen Image 3 Pro per gambar?

Alibaba mematok harga pendahulu qwen-image-2.0-pro sebesar $0,075 per gambar dan hanya menagih generasi yang berhasil (Alibaba Cloud pricing, 2026). Penyedia pihak ketiga seperti Fal dan Replicate mencantumkan model gambar Qwen masing-masing sekitar $0,021 dan $0,030 per gambar. Verifikasi harga 3.0-pro saat ini di halaman resmi.

Apakah ada kuota gratis?

Ya. Setiap model gambar di Model Studio memiliki kuota gratis yang dapat Anda gunakan untuk pengujian sebelum penagihan berbayar dimulai (Alibaba Image API FAQ, 2026). Periksa FAQ untuk irama reset dan batasan, yang bervariasi per model.

Apakah Qwen Image 3 Pro mendukung pengeditan gambar?

Pengeditan ditangani oleh endpoint terpisah bernama Qwen-Image Edit, yang mendukung IO multi-gambar, pengeditan teks di dalam gambar, penambahan, penghapusan, dan pemindahan objek, serta perubahan pose (Qwen-Image Edit API, 2026). API text-to-image dan edit memiliki bentuk permintaan yang berbeda.

Kesimpulan

Anda sekarang memiliki jalur lengkap untuk panggilan qwen-image-3.0-pro pertama Anda: Kunci API dari konsol Model Studio, variabel lingkungan DASHSCOPE_API_KEY dimuat, permintaan cURL yang berfungsi, dan cuplikan Python yang mengurai dan mengunduh hasilnya. Model harga per gambar, mulai dari $0,075 pada harga resmi Alibaba, membuat biaya dapat diprediksi saat Anda melakukan penskalaan.

Dua langkah selanjutnya akan mempertajam integrasi Anda. Pertama, konfirmasikan nama bidang permintaan dan respons yang tepat terhadap referensi API resmi di Qwen API via DashScope, karena detail skema dapat berubah antara versi model. Kedua, jika produk Anda membutuhkan pengeditan daripada pembuatan murni, jelajahi Qwen-Image Edit API, yang membuka penghapusan objek, pengeditan teks, dan perubahan pose melalui endpoint khusus.

Bangun kecil, pantau kuota Anda, dan luncurkan.