Panduan Cepat API Qwen Image 2512: Buat Gambar dalam Hitungan Menit (2026)

Halo, saya Dora. Saya dulu menghabiskan banyak waktu untuk membuat gambar untuk produk: mencari aset, mengubah ukuran, mengganti nama file, mengorganisir folder… setiap langkah berulang tanpa henti. Tidak ada yang sulit, tetapi sangat membosankan. Kemudian, saya mencoba Qwen Image 2512 API dan menemukan bahwa saya bisa mengotomatisasi semua ini hanya dengan beberapa baris kode.

Ini bukan iklan. Saya hanya berbagi apa yang benar-benar terjadi ketika saya mencobanya — apa yang berjalan lancar, di mana saya tersandung, dan bagaimana saya membuatnya dapat diandalkan.

Jalan Pintas WaveSpeed (Jika Anda hanya ingin hasil)

Jika Anda hanya ingin menghasilkan gambar dengan cepat, tanpa menghubungkan semuanya sendiri:

WaveSpeed sudah menyediakan Qwen Image 2512 REST API yang siap pakai (tanpa cold starts).
Gunakan endpoint WaveSpeed + API key → selesai.
Jika Anda ingin memahami alur DashScope resmi (dan jebakan umum), terus baca.

Apa yang benar-benar bisa dilakukan API ini?

Sederhananya: Anda mengetik deskripsi dalam teks, dan itu memberi Anda gambar.

Misalnya, jika Anda menulis:

“Meja rapi dengan notebook dan tanaman di bawah cahaya lembut”

beberapa detik kemudian, Anda mendapatkan gambar yang sesuai dengan deskripsi Anda — dan Anda bisa secara otomatis menyimpannya ke komputer Anda.

Hal-hal yang bagus untuk:

Membuat moodboard
Menghasilkan thumbnail dengan cepat
Menambahkan gambar placeholder ke dokumen
Membuat visual prototype untuk produk

Apa yang saya perhatikan:

Pertama kali saya menggunakannya, terasa tidak jauh lebih cepat daripada mencari gambar secara manual. Tetapi setelah dua atau tiga kali, saya menyadari bahwa saya tidak perlu repot lagi dengan “ukuran apa seharusnya ini?” atau “bagaimana cara saya memberi nama file?” lagi. Apa yang dihemat bukan hanya waktu, tetapi usaha mental.

Format gambar dan penyimpanan

Format: PNG, dihasilkan secara otomatis secara default
Di mana gambar disimpan:
- API mengembalikan tautan (URL) ke gambar
- Tautan menunjuk ke server Alibaba Cloud
- Penting: tautan hanya valid selama 24 jam; setelah itu, tautan kedaluwarsa
- Jadi Anda perlu mengunduhnya ke komputer Anda dengan segera

Catatan: API tidak langsung memberi Anda file gambar. Jika Anda ingin menyimpannya secara lokal, Anda perlu menambahkan langkah unduhan dalam kode Anda (dijelaskan nanti).

Sebelum Anda mulai: apa yang Anda butuhkan

Langkah 1: Dapatkan akun dan kunci API

Daftar untuk akun Alibaba Cloud
Buka Model Studio Console
Buat kunci API (seperti kunci yang membuktikan itu Anda)
Simpan kunci sebagai variabel lingkungan bernama DASHSCOPE_API_KEY
Variabel lingkungan:
Bayangkan sebagai tempat khusus di komputer Anda di mana kunci Anda berada, sehingga kode Anda dapat secara otomatis menemukannya tanpa perlu copy-paste setiap kali.

Tips:

Untuk pengujian, Anda dapat menyimpannya dalam file .env
Untuk penggunaan nyata, alat manajemen kunci yang aman lebih baik
Wilayah Beijing dan Singapura memiliki kunci berbeda — jangan campur

Langkah 2: Pilih alat

Ada tiga cara utama, dimulai dari yang paling sederhana:

cURL (paling sederhana)
- Bagus untuk tes cepat untuk melihat apakah API berfungsi
- Tidak perlu pemrograman, cukup tempel perintahnya
- Direkomendasikan untuk percobaan pertama
Python (paling umum)
- Bagus untuk membangun alat kecil untuk penggunaan berulang
- Saya menggunakan DashScope SDK resmi untuk menangani banyak detail secara otomatis
- Beberapa pengetahuan Python dasar membantu
Node.js (ramah untuk pengembang frontend)
- Jika Anda pengembang frontend, ini juga berfungsi
- Prinsipnya sama, meskipun saya tidak akan membahasnya di sini

Coba Playground terlebih dahulu:
Jika Anda hanya ingin menguji hasil dengan cepat, Wavespeed Playground memungkinkan Anda menghasilkan gambar di browser. Sempurna untuk penggunaan sesekali. Untuk pembuatan batch atau otomasi, terus baca untuk mempelajari cara menggunakan API.

Mulai cepat: pengujian dengan cURL

Buka terminal (Mac) atau command prompt (Windows) Anda dan tempel ini:

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --data '{
    "model": "qwen-image-max",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {"text": "Meja rapi dengan notebook dan tanaman di bawah cahaya lembut"}
          ]
        }
      ]
    },
    "parameters": {
      "size": "1024*1024"
    }
  }'

Tekan Enter, tunggu beberapa detik, dan Anda akan melihat respons JSON dengan tautan ke gambar Anda.

Jebakan yang saya hadapi

Nama model harus qwen-image-max, bukan qwen-image-2512 atau yang lain.
Format ukuran menggunakan asterisk 1024*1024, bukan 1024x1024.
Untuk wilayah Singapura, ubah URL ke: https://dashscope-intl.aliyuncs.com/api/v1/...

Jika Anda membangun sesuatu yang mirip dengan produksi, alur DashScope resmi sepenuhnya dapat digunakan — tetapi itu disertai dengan detail operasional (wilayah, masa pakai URL, percobaan ulang). Itulah tepatnya mengapa saya suka menggunakan WaveSpeed untuk pekerjaan sehari-hari: itu memberi saya Qwen Image 2512 di belakang REST API yang siap pakai, jadi saya bisa fokus pada prompt dan manajemen output daripada perpipaan.

Parameter dijelaskan

Diperlukan

model
- "qwen-image-max" adalah nama resmi untuk Qwen-Image-2512
- Ada juga "qwen-image-plus", mirip tetapi lebih murah
input.messages
- Array dengan satu elemen
- text adalah deskripsi Anda
- Maksimal 800 karakter (sekitar 400 karakter Cina)

Opsional (default digunakan jika dihilangkan)

parameters.size
- 1664*928 (landscape 16:9)
- 1472*1104 (4:3)
- 1328*1328 (1:1 persegi, default)
- 1104*1472 (3:4 potret)
- 928*1664 (9:16 potret)
parameters.negative_prompt
- Hal-hal yang tidak Anda inginkan: misalnya, "low-res, blurry, distorted, oversaturated"
- Hingga 500 karakter
parameters.prompt_extend
- Default adalah true
- Secara otomatis memperkaya deskripsi Anda
- Matikan jika Anda ingin kontrol ketat
parameters.watermark
- Default false
- Menambahkan watermark “Qwen-Image” jika true
parameters.seed
- Rentang 0–2147483647
- Seed sama + deskripsi sama = gambar sama
- Berguna untuk pengujian dan membandingkan hasil

Contoh respons API

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxxx"
            }
          ]
        }
      }
    ]
  },
  "usage": {
    "width": 1328,
    "image_count": 1,
    "height": 1328
  },
  "request_id": "xxx"
}

Poin-poin kunci

URL gambar: output.choices[0].message.content[0].image
Periksa finish_reason adalah "stop" untuk memastikan kesuksesan
Tautan berlangsung 24 jam — unduh dengan segera

Otomasi dengan Python

Jika Anda ingin pembuatan batch atau alat kecil:

import os
import time
import requests
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath

API_KEY = os.getenv("DASHSCOPE_API_KEY")
ENDPOINT = "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation"

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

def generate_image(prompt: str, size="1328*1328"):
    payload = {
        "model": "qwen-image-max",
        "input": {
            "messages": [{"role": "user", "content": [{"text": prompt}]}]
        },
        "parameters": {"size": size, "prompt_extend": True, "watermark": False}
    }
    r = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=120)
    r.raise_for_status()
    data = r.json()
    choices = data.get("output", {}).get("choices", [])
    if not choices:
        raise ValueError(f"No image generated:\n{data}")
    content = choices[0].get("message", {}).get("content", [])
    if not content:
        raise ValueError(f"Empty content:\n{data}")
    image_url = content[0].get("image")
    if not image_url:
        raise ValueError(f"No image URL:\n{data}")

    img_response = requests.get(image_url)
    img_response.raise_for_status()

    file_name = PurePosixPath(unquote(urlparse(image_url).path)).parts[-1]
    ts = int(time.time())
    path = f"qwen_image_{ts}_{file_name}"
    with open(path, "wb") as f:
        f.write(img_response.content)
    return path

if __name__ == "__main__":
    output_path = generate_image("Meja rapi dengan notebook dan tanaman di bawah cahaya lembut")
    print("Image saved at:", output_path)

Apa yang saya pelajari saat pengujian

Nama model yang salah merusaknya (qwen-image-plus → qwen-image-max)
Format ukuran yang salah (1328x1328 bukan 1328*1328)
Struktur respons sedikit berbeda dari dokumen; periksa URL gambar
Lupa mengunduh gambar membuat tautan kedaluwarsa setelah 24 jam

Menggunakan SDK resmi

import os
import json
from dashscope import MultiModalConversation

api_key = os.getenv("DASHSCOPE_API_KEY")
messages = [{"role": "user", "content": [{"text": "Meja rapi dengan notebook dan tanaman di bawah cahaya lembut"}]}]

response = MultiModalConversation.call(
    api_key=api_key,
    model="qwen-image-max",
    messages=messages,
    result_format='message',
    stream=False,
    watermark=False,
    prompt_extend=True,
    size='1328*1328'
)

if response.status_code == 200:
    print(json.dumps(response, ensure_ascii=False))
    image_url = response.output.choices[0].message.content[0]['image']
    print(f"Image URL: {image_url}")
else:
    print(f"Error: {response.code} - {response.message}")

Referensi parameter cepat

Parameter	Nilai yang Disarankan	Catatan
size	1328*1328	Persegi, keseimbangan kecepatan dan kualitas yang baik
prompt_extend	TRUE	Biarkan AI memperkaya deskripsi Anda
seed	Nomor tetap	Gunakan untuk pengujian guna membandingkan hasil
negative_prompt	Sesuai kebutuhan	Misalnya, “blurry, low quality, distorted”

Kapan mengubah seed

Seed tetap → bandingkan variasi prompt
Seed berbeda → hasilkan beberapa gambar yang berbeda

Kesalahan umum & perbaikannya

401 Unauthorized → kunci API salah, wilayah salah, atau izin gambar hilang
429 Rate limit → terlalu banyak permintaan; tambahkan penundaan atau tingkatkan kuota
Timeout / masalah jaringan → tingkatkan timeout, unduh segera

Perbaikan kecil yang saya tambahkan

Seed tetap untuk prompt pengujian → lebih mudah membandingkan hasil
Penamaan file yang konsisten: {keyword}-{size}-{seed}.png
Manajemen file konfigurasi: YAML untuk menghindari hardcoding parameter

Siapa yang bisa menggunakan ini

Playground

Pembuatan gambar sesekali
Pengujian prompt cepat
Tidak perlu otomasi

API

Pembuatan batch
Integrasi alat atau produk
Penggunaan berbasis jadwal atau sistem

Jalur akhir (pilih yang sesuai untuk Anda)

Jalur A — Cepat & praktis

Gunakan WaveSpeed Playground API untuk Qwen Image 2512
Penyiapan minimal, endpoint REST siap pakai

Jalur B — Kontrol penuh

Gunakan DashScope secara langsung jika Anda memerlukan integrasi mendalam Alibaba Cloud

Saya suka alat yang bekerja dengan tenang di latar belakang. Untuk pembelajaran dan pemahaman, alur resmi sangat bagus. Untuk pekerjaan sehari-hari dan pengiriman lebih cepat, WaveSpeed menghemat banyak gesekan bagi saya.