Cara Menggunakan Qwen-Image-2.1: Kode Diffusers, Output Transparan, dan Uji API

Qwen-Image-2.1 adalah model gambar dengan bobot terbuka yang dirilis Alibaba pada 20 September 2026: generator 7B-parameter yang menangani teks-ke-gambar, pengeditan dengan hingga 10 gambar referensi, dan output transparan (RGBA) bawaan. Panduan ini akan membawa Anda dari pip install ke endpoint HTTP yang berfungsi. Ini mencakup empat jalur kode referensi dari GitHub README, pengaturan yang penting, pembungkus FastAPI kecil agar model dapat dipanggil seperti API gambar lainnya, dan cara menguji endpoint tersebut di Apidog sehingga perubahan prompt dan pembaruan model tidak merusak aplikasi Anda.

Jika Anda ingin latar belakangnya terlebih dahulu, Apa itu Qwen-Image-2.1 mencakup arsitektur dan lisensinya. Versi singkat lisensi: hanya untuk penelitian dan penggunaan non-komersial kecuali Anda mendapatkan perjanjian komersial terpisah dari Qwen. Semua yang ada di bawah ini baik untuk evaluasi.

Sebelum Anda memulai

Instal:

pip install "torch>=2.4.0" "transformers>=5.17" accelerate pillow
pip install git+https://github.com/huggingface/diffusers

Integrasi diffusers masuk dalam PR khusus pada hari peluncuran, jadi rilis PyPI yang lebih lama dari 20 September tidak akan memiliki kelas pipeline tersebut.

Langkah 1: teks-ke-gambar

import torch
from diffusers import QwenImage21Pipeline

pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16
).to("cuda")

image = pipe(
    prompt='A neon shop sign that reads "QWEN IMAGE 2.1", rainy night, reflections on wet pavement',
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("t2i_example.png")

Dua hal yang perlu diperhatikan. Prompt menempatkan teks tanda kutip; rendering teks Qwen adalah alasan orang memilih jajaran model ini, dan mengutip string literal adalah konvensi dari rilis sebelumnya. Dan seed bersifat eksplisit. Pertahankan seperti itu di setiap permintaan yang ingin Anda uji, karena seed tetap adalah yang membuat endpoint gambar cukup dapat direproduksi untuk ditegaskan.

Lewatkan width dan height dari tabel yang didukung saat Anda membutuhkan output non-persegi:

Langkah 2: output transparan

Transparansi digerakkan oleh prompt. Frasa yang direkomendasikan README adalah literal, jadi gunakanlah:

image = pipe(
    prompt=(
        "This is an RGBA image with transparency. A cute cartoon dragon sticker. "
        "The image has alpha channel and the background is transparent."
    ),
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
image.save("transparent_example.png")

Periksa hasilnya daripada mempercayainya begitu saja:

assert image.mode == "RGBA", image.mode
alpha = image.getchannel("A")
print("transparent pixels:", sum(1 for p in alpha.getdata() if p == 0))

Penegasan itu adalah tes pertama yang akan Anda porting ke Apidog nanti. Model yang secara diam-diam mengembalikan RGB saat Anda meminta RGBA adalah bug yang akan ditemukan pengguna Anda sebelum Anda menemukannya.

Langkah 3: pengeditan, dengan satu gambar atau hingga sepuluh

Pipeline yang sama mengedit saat Anda melewatkan image:

from PIL import Image

input_image = Image.open("input.png")
edited = pipe(
    prompt="Change the background to a sunset beach",
    image=input_image,
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
edited.save("edit_example.png")

Untuk beberapa referensi, lewati daftar (batas posting peluncuran adalah 10):

refs = [Image.open(f"ref_{i}.png") for i in range(3)]
result = pipe(
    prompt="These three characters are sitting around a campfire in a forest",
    image=refs,
    num_inference_steps=40,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]
result.save("multi_ref_example.png")

Pengeditan lokal bekerja dalam tiga cara di postingan peluncuran: lingkaran berwarna yang Anda referensikan berdasarkan warna dalam prompt, anotasi yang dilukis, atau gambar asli yang tidak tersentuh ditambah gambar mask terpisah yang dilewatkan sebagai dua input. README tidak menyertakan contoh mask khusus, jadi bentuk dua input adalah yang pertama dicoba: image=[original, mask] dengan prompt yang menjelaskan apa yang ada di wilayah bertopeng [VERIFIKASI terhadap README setelah contoh mask tersedia].

Pengeditan juga merupakan tempat kerja kecepatan 2.1 terlihat. Gambar referensi dan instruksi bersifat statis di seluruh langkah denoising, sehingga model menghitung cache key-value mereka sekali dan menggunakannya kembali. Sepuluh referensi membutuhkan biaya yang jauh lebih sedikit daripada sepuluh kali satu.

Langkah 4: sesuaikan dengan GPU Anda

Qwen belum mempublikasikan angka VRAM. Jika pipeline bf16 tidak muat, README menawarkan:

pipe = QwenImage21Pipeline.from_pretrained("Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16)
pipe.enable_model_cpu_offload()

Untuk penyajian, README menunjuk ke vLLM-Omni (dengan FP8), SGLang, dan LightX2V. ComfyUI memiliki dukungan asli dengan alur kerja template jika Anda lebih suka tidak menulis Python sama sekali. Dan jika Anda tidak memiliki GPU, opsi gratis mencakup demo yang di-host dan Qwen Chat.

Langkah 5: bungkus sebagai API HTTP

Kode aplikasi seharusnya tidak mengimpor diffusers. Letakkan pipeline di belakang layanan kecil agar memiliki kontrak yang dapat Anda versi, mock, dan uji. Pembungkus FastAPI ini sekitar 40 baris dan mengembalikan byte PNG:

# server.py
import io, torch
from fastapi import FastAPI, UploadFile, File, Form
from fastapi.responses import Response
from PIL import Image
from diffusers import QwenImage21Pipeline

app = FastAPI()
pipe = QwenImage21Pipeline.from_pretrained(
    "Qwen/Qwen-Image-2.1", torch_dtype=torch.bfloat16
).to("cuda")

SIZES = {"1:1": (2048, 2048), "16:9": (2752, 1536), "9:16": (1536, 2752)}

@app.post("/v1/images")
async def generate(
    prompt: str = Form(...),
    aspect: str = Form("1:1"),
    transparent: bool = Form(False),
    seed: int = Form(42),
    steps: int = Form(40),
    references: list[UploadFile] = File(default=[]),
):
    if transparent and not prompt.startswith("This is an RGBA image"):
        prompt = ("This is an RGBA image with transparency. " + prompt +
                  " The image has alpha channel and the background is transparent.")
    refs = [Image.open(io.BytesIO(await f.read())) for f in references[:10]]
    w, h = SIZES.get(aspect, SIZES["1:1"])
    kwargs = dict(prompt=prompt, num_inference_steps=steps,
                  generator=torch.Generator("cuda").manual_seed(seed))
    if refs:
        kwargs["image"] = refs if len(refs) > 1 else refs[0]
    else:
        kwargs.update(width=w, height=h)
    image = pipe(**kwargs).images[0]
    buf = io.BytesIO()
    image.save(buf, format="PNG")
    return Response(buf.getvalue(), media_type="image/png",
                    headers={"X-Image-Mode": image.mode, "X-Seed": str(seed)})

Jalankan dengan uvicorn server:app --port 8000. Dua header respons, X-Image-Mode dan X-Seed, ada agar pengujian dapat memeriksa transparansi dan reproduktifitas tanpa mendekode PNG. Itu satu-satunya pilihan spesifik produk dalam pembungkus; sisanya adalah endpoint multipart biasa.

Langkah 6: uji endpoint di Apidog

Sekarang ini adalah API, dan disiplin yang sama yang akan Anda terapkan pada API gpt-image-2.5 atau API Nano Banana 2 berlaku di sini. Di Apidog:

1. Buat endpoint sebagai POST {{base_url}}/v1/images dengan badan multipart: prompt, aspect, transparent, seed, steps, dan bidang file references yang dapat diulang. Letakkan base_url dalam lingkungan sehingga koleksi yang sama menunjuk ke laptop Anda, kotak GPU, atau mock.
2. Kirim permintaan teks-ke-gambar dengan seed=42 dan prompt tanda neon. Konfirmasi 200, Content-Type: image/png, dan X-Image-Mode: RGB.
3. Tambahkan penegasan di post-processor: status adalah 200, X-Image-Mode sama dengan RGBA ketika transparent=true, ukuran badan respons di atas batas bawah (PNG 2K yang kembali sebesar 2 KB adalah gambar kosong), dan X-Seed mengulang apa yang Anda kirim.
4. Kirim kasus transparansi dan pengeditan tiga referensi dengan cara yang sama, melampirkan gambar di bidang file. Simpan masing-masing sebagai kasus uji.
5. Jalankan sebagai skenario uji sesuai jadwal atau di CI. Ketika Anda menukar dengan build terkuantisasi atau 2.2 di masa mendatang, suite akan memberi tahu Anda dalam hitungan menit apakah transparansi masih berfungsi dan apakah seed masih mereproduksi.
6. Mock itu saat GPU sedang sibuk. Mock cerdas Apidog mengembalikan PNG kalengan untuk kontrak yang sama, sehingga frontend terus membangun.

Karena Apidog juga menghasilkan spesifikasi dan dokumen OpenAPI dari endpoint yang Anda definisikan, kontrak pembungkus menjadi dapat dibagikan saat berfungsi. Unduh Apidog dan impor endpoint di atas untuk memulai.

Opsional: penulisan ulang prompt dengan PE-T2I

Demo Space mengubah permintaan satu baris menjadi prompt terstruktur panjang menggunakan Qwen-Image-2.1-PE-T2I, Qwen3.5-VL 9B yang telah disetel halus yang mengembalikan JSON dengan prompt Bahasa Inggris yang diperluas dan rasio aspek yang direkomendasikan. Jalankan sebagai layanan kedua di depan /v1/images, atau lewati saja dan tulis sendiri prompt lengkapnya. Jika Anda menambahkannya, uji secara terpisah: ini adalah API teks dengan kontrak JSON, dan penulis ulang yang rusak menghasilkan gambar yang buruk yang terlihat seperti bug generator.

FAQ

Apakah satu pipeline melakukan generasi dan pengeditan? Ya. QwenImage21Pipeline menghasilkan saat dipanggil hanya dengan prompt dan mengedit saat Anda melewatkan image (satu gambar PIL tunggal atau daftar hingga 10).

Bagaimana cara mendapatkan PNG transparan? Mulai prompt dengan "This is an RGBA image with transparency" (Ini adalah gambar RGBA dengan transparansi) dan katakan bahwa latar belakangnya transparan. Periksa image.mode == "RGBA" pada hasilnya.

Apa pengaturan yang direkomendasikan? 40 langkah inferensi dan bfloat16, sesuai README. Nilai panduan tidak tercantum untuk 2.1; rilis Qwen-Image sebelumnya menggunakan true_cfg_scale=4.0, jadi coba itu jika output terlihat kurang terpandu [VERIFIKASI].

Bisakah ini digunakan dalam produk komersial? Tidak di bawah lisensi default. Qwen-Image-2.1 didistribusikan di bawah Lisensi Penelitian Qwen; penggunaan komersial memerlukan lisensi terpisah dari Qwen. Detailnya di Apa itu Qwen-Image-2.1.

Apakah ada API yang di-host sebagai gantinya? Qwen Image 3.0 dan 3.0 Pro adalah model gambar yang di-host oleh Alibaba dengan harga per gambar. Perbandingan 2.1 vs 3.0 mencakup kapan harus melakukan self-host dan kapan harus menyewa.

Ke mana selanjutnya

Anda sekarang memiliki empat panggilan yang berfungsi, pembungkus dengan kontrak yang stabil, dan rangkaian pengujian yang memeriksa dua properti terpenting untuk model ini, transparansi dan reproduktifitas. Selanjutnya, putuskan apakah lisensi penelitian sesuai dengan penggunaan Anda, atau apakah API 3.0 yang di-host adalah pilihan yang lebih baik, dan simpan keduanya di belakang koleksi Apidog yang sama sehingga perubahan hanya pada URL dasar, bukan penulisan ulang.