Qwen-Image-2.1 nutzen: Diffusers Code, transparente Ausgabe und API zum Testen

Qwen-Image-2.1 ist das quelloffene Bildmodell, das Alibaba am 20. September 2026 veröffentlicht hat: ein Generator mit 7 Milliarden Parametern, der Text-zu-Bild, Bearbeitung mit bis zu 10 Referenzbildern und native transparente (RGBA) Ausgabe unterstützt. Dieser Leitfaden führt Sie von der pip install-Anweisung zu einem funktionierenden HTTP-Endpunkt. Er behandelt die vier Referenz-Codepfade aus der GitHub README, die wichtigen Einstellungen, einen kleinen FastAPI-Wrapper, damit das Modell wie jede andere Bild-API aufrufbar ist, und wie man diesen Endpunkt in Apidog testet, damit Prompt-Änderungen und Modell-Updates Ihre Anwendung nicht beeinträchtigen.

Wenn Sie zuerst die Hintergründe wissen möchten, behandelt Was ist Qwen-Image-2.1 die Architektur und die Lizenz. Die Kurzversion der Lizenz: nur für Forschungszwecke und nicht-kommerzielle Nutzung, es sei denn, Sie erhalten eine separate kommerzielle Vereinbarung von Qwen. Alles unten Genannte ist für die Evaluierung unbedenklich.

Bevor Sie beginnen

Installation:

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

Die Diffusers-Integration landete am Starttag in einem dedizierten PR, daher wird eine PyPI-Veröffentlichung, die älter als der 20. September ist, die Pipeline-Klasse nicht enthalten.

Schritt 1: Text-zu-Bild

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")

Zwei Dinge sind zu beachten. Der Prompt setzt den Text des Schildes in Anführungszeichen; Qwens Textdarstellung ist der Grund, warum Leute diese Modellreihe wählen, und das Zitieren der wörtlichen Zeichenfolge ist die Konvention aus früheren Veröffentlichungen. Und der Seed ist explizit. Behalten Sie dies bei jeder Anfrage bei, die Sie testen möchten, denn ein fester Seed macht einen Bild-Endpunkt reproduzierbar genug, um Behauptungen aufzustellen.

Geben Sie width und height aus der unterstützten Tabelle an, wenn Sie eine nicht-quadratische Ausgabe benötigen:

Schritt 2: Transparente Ausgabe

Transparenz ist Prompt-gesteuert. Die im README empfohlene Formulierung ist wörtlich, also verwenden Sie sie:

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")

Überprüfen Sie das Ergebnis, anstatt ihm zu vertrauen:

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

Diese Behauptung ist der erste Test, den Sie später in Apidog übernehmen werden. Ein Modell, das stillschweigend RGB zurückgibt, wenn Sie RGBA angefordert haben, ist ein Fehler, den Ihre Benutzer vor Ihnen finden werden.

Schritt 3: Bearbeiten mit einem Bild oder bis zu zehn Bildern

Dieselbe Pipeline bearbeitet, wenn Sie image übergeben:

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")

Für mehrere Referenzen übergeben Sie eine Liste (das Limit des Launch-Posts sind 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")

Die lokale Bearbeitung funktioniert im Launch-Post auf drei Arten: farbige Kreise, die Sie im Prompt nach Farbe referenzieren, gemalte Anmerkungen oder das unberührte Original plus ein separates Maskenbild, das als zwei Eingaben übergeben wird. Die README enthält kein dediziertes Maskenbeispiel, daher ist die Zwei-Eingaben-Form die erste, die man ausprobieren sollte: image=[original, mask] mit einem Prompt, der beschreibt, was in den maskierten Bereich gehört [PRÜFEN Sie dies anhand der README, sobald ein Maskenbeispiel vorliegt].

Die Bearbeitung ist auch der Bereich, in dem sich 2.1s Geschwindigkeitsarbeit zeigt. Referenzbilder und die Anweisung sind über die Entrauschungsschritte hinweg statisch, sodass das Modell ihren Key-Value-Cache einmal berechnet und wiederverwendet. Zehn Referenzen kosten merklich weniger als das Zehnfache von einer.

Schritt 4: Auf Ihre GPU anpassen

Qwen hat keine VRAM-Zahlen veröffentlicht. Wenn die bf16-Pipeline nicht passt, bietet die README Folgendes an:

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

Für das Serving verweist die README auf vLLM-Omni (mit FP8), SGLang und LightX2V. ComfyUI bietet native Unterstützung mit einem Vorlagen-Workflow, wenn Sie überhaupt kein Python schreiben möchten. Und wenn Sie keine GPU haben, decken die kostenlosen Optionen die gehostete Demo und Qwen Chat ab.

Schritt 5: Als HTTP-API wrappen

Anwendungscode sollte keine Diffuser importieren. Legen Sie die Pipeline hinter einen kleinen Dienst, damit sie einen Vertrag hat, den Sie versionieren, simulieren und testen können. Dieser FastAPI-Wrapper ist etwa 40 Zeilen lang und gibt PNG-Bytes zurück:

# 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)})

Führen Sie es mit uvicorn server:app --port 8000 aus. Die beiden Antwort-Header, X-Image-Mode und X-Seed, existieren, damit ein Test Transparenz und Reproduzierbarkeit überprüfen kann, ohne das PNG zu dekodieren. Das ist die einzige produktspezifische Wahl im Wrapper; der Rest ist ein einfacher Multipart-Endpunkt.

Schritt 6: Testen des Endpunkts in Apidog

Jetzt ist es eine API, und die gleiche Disziplin, die Sie auf die gpt-image-2.5 API oder die Nano Banana 2 API anwenden würden, gilt hier. In Apidog:

1. Erstellen Sie den Endpunkt als POST {{base_url}}/v1/images mit einem Multipart-Body: prompt, aspect, transparent, seed, steps und einem wiederholbaren references-Dateifeld. Legen Sie base_url in einer Umgebung ab, sodass dieselbe Sammlung auf Ihren Laptop, die GPU-Box oder einen Mock verweist.
2. Senden Sie eine Text-zu-Bild-Anfrage mit seed=42 und dem Neon-Schild-Prompt. Bestätigen Sie 200, Content-Type: image/png und X-Image-Mode: RGB.
3. Fügen Sie Behauptungen im Post-Prozessor hinzu: Status ist 200, X-Image-Mode ist gleich RGBA, wenn transparent=true, die Größe des Antwort-Body ist über einem Mindestwert (ein 2K-PNG, das als 2 KB zurückkommt, ist ein leeres Bild), und X-Seed spiegelt wider, was Sie gesendet haben.
4. Senden Sie den Transparenzfall und eine Drei-Referenz-Bearbeitung auf die gleiche Weise und hängen Sie die Bilder im Dateifeld an. Speichern Sie jeden als Testfall.
5. Führen Sie sie als Testszenario nach einem Zeitplan oder in CI aus. Wenn Sie einen quantisierten Build oder ein zukünftiges 2.2 verwenden, sagt Ihnen die Suite in Minuten, ob Transparenz noch funktioniert und ob der Seed noch reproduzierbar ist.
6. Mocken Sie es, während die GPU beschäftigt ist. Apidogs intelligenter Mock gibt ein vorbereitetes PNG für denselben Vertrag zurück, sodass das Frontend weiterarbeitet.

Da Apidog auch die OpenAPI-Spezifikation und Dokumente vom definierten Endpunkt generiert, wird der Vertrag des Wrappers sofort nach seiner Funktion geteilt. Laden Sie Apidog herunter und importieren Sie den obigen Endpunkt, um zu beginnen.

Optional: Prompt-Umschreibung mit PE-T2I

Der Demo-Space wandelt einzeilige Anfragen in lange strukturierte Prompts um, indem er Qwen-Image-2.1-PE-T2I verwendet, ein fein abgestimmtes Qwen3.5-VL 9B, das JSON mit einem erweiterten englischen Prompt und einem empfohlenen Seitenverhältnis zurückgibt. Führen Sie es als zweiten Dienst vor /v1/images aus, oder überspringen Sie es und schreiben Sie selbst vollständige Prompts. Wenn Sie es hinzufügen, testen Sie es separat: Es ist eine Text-API mit einem JSON-Vertrag, und ein fehlerhafter Umschreiber erzeugt schlechte Bilder, die wie ein Generatorfehler aussehen.

FAQ

Führt eine Pipeline sowohl Generierung als auch Bearbeitung durch? Ja. QwenImage21Pipeline generiert, wenn es nur mit einem Prompt aufgerufen wird, und bearbeitet, wenn Sie image übergeben (ein einzelnes PIL-Bild oder eine Liste von bis zu 10 Bildern).

Wie erhalte ich ein transparentes PNG? Beginnen Sie den Prompt mit „Dies ist ein RGBA-Bild mit Transparenz“ und sagen Sie, dass der Hintergrund transparent ist. Überprüfen Sie image.mode == "RGBA" im Ergebnis.

Was sind die empfohlenen Einstellungen? 40 Inferenzschritte und bfloat16, laut README. Guidance-Werte sind für 2.1 nicht aufgeführt; frühere Qwen-Image-Versionen verwendeten true_cfg_scale=4.0, probieren Sie dies aus, wenn die Ausgaben unter-guided aussehen [PRÜFEN].

Kann ich dies in einem kommerziellen Produkt verwenden? Nicht unter der Standardlizenz. Qwen-Image-2.1 wird unter der Qwen Research License ausgeliefert; kommerzielle Nutzung erfordert eine separate Lizenz von Qwen. Details unter Was ist Qwen-Image-2.1.

Gibt es stattdessen eine gehostete API? Qwen Image 3.0 und 3.0 Pro sind Alibabas gehostete Bildmodelle mit Preisen pro Bild. Der 2.1 vs. 3.0 Vergleich behandelt, wann man selbst hosten und wann man mieten sollte.

Nächste Schritte

Sie haben jetzt vier funktionierende Aufrufe, einen Wrapper mit einem stabilen Vertrag und eine Testsuite, die die beiden wichtigsten Eigenschaften dieses Modells überprüft: Transparenz und Reproduzierbarkeit. Entscheiden Sie als Nächstes, ob die Forschungslizenz zu Ihrer Nutzung passt oder ob die gehostete 3.0 API besser geeignet ist, und halten Sie beides hinter derselben Apidog-Sammlung, sodass ein Wechsel eine Änderung der Basis-URL und keine Neuimplementierung ist.