So verwendest du die Qwen Image 2.1 Turbo API: curl, Python und eine echte Testanfrage

Qwen Image 2.1 Turbo (qwen-image-2.1-turbo) ist die schnelle und günstige Variante der Bildserie 2.1 von Alibaba auf hiapi. Es nimmt einen Text-Prompt und optional 0–10 Referenzbilder entgegen und liefert ein PNG mit 2048×2048 zurück. Diese Anleitung zeigt eine direkt ausführbare Anfrage, das vom API tatsächlich erzwungene Eingabe-Schema, einen Bearbeitungsaufruf sowie die Ergebnisse, die wir beim Testen der Aussage „transparentes PNG“ gesehen haben.

Du benötigst einen hiapi-API-Schlüssel aus der Konsole. Aufrufe erfolgen über die einheitliche asynchrone Task-API, daher gibt es keine synchrone Bildantwort.

Minimale Anfrage: Text zu Bild

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "Sticker-Stil-Illustration: ein Shiba Inu mit Strohhut auf einem Surfbrett, Flachfarben, kräftige Konturen, Korallenorange und Meeresblau",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

Anschließend pollst du GET /v1/tasks/<taskId>, bis data.status den Wert success hat, und liest data.output[0].url aus.

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # Hinweis: Das Feld heißt taskId, nicht id

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # Vorübergehender Netzwerkfehler: weiter dieselbe id pollen
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

Lade die Datei sofort herunter. Die Ausgabe-URL liegt auf temp.hiapi.ai und trägt einen expireAt-Zeitstempel (in unserem Lauf etwa sieben Tage nach der Erstellung); wenn du sie länger behalten willst, speichere die Dateibytes selbst.

Eingabe-Schema (die vom API tatsächlich erzwungenen Regeln)

Die folgenden Angaben stammen aus den Validierungsfehlern, die zurückgegeben wurden, als wir absichtlich ungültige Anfragen gesendet haben; sie spiegeln daher das reale Verhalten des Live-Endpunkts wider und nicht eine Nacherzählung der Dokumentation:

Feld	Regel
prompt	Erforderlicher String (das Formular auf der Modellseite begrenzt ihn auf 4500 Zeichen)
aspect_ratio	Einer der Werte 1:1, 16:9, 9:16, 4:3, 3:4
image_urls	Array von Referenzbild-URLs, 0–10 Einträge; wird ein String direkt übergeben, wird er mit image_urls must be an array abgelehnt
prompt_extend	Boolean, Schalter für Prompt-Optimierung
seed	Integer, 0 bis 2147483647

Zwei Punkte unterscheiden sich von anderen Qwen-Modellen derselben Serie. Hier gibt es kein Feld resolution: Wird es gesendet, kommt additional properties 'resolution' not allowed zurück. Bei 1:1 ist die Ausgabe eine feste 2048×2048-Leinwand, was wir gemessen haben. Außerdem werden unbekannte Felder in der Regel abgelehnt statt ignoriert. Ein falsches aspect_ratio liefert HTTP 400 mit error_code: INVALID_REQUEST, und in message werden die erlaubten Werte aufgelistet.

Bearbeiten mit Referenzbildern

Bearbeitung und Stil-Neuzeichnung verwenden dieselbe Modell-ID. Lege die Quellbilder in image_urls ab und beschreibe die Änderung im Prompt:

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "Färbe den Strohhut dunkelviolett neu ein, der Rest bleibt unverändert",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

Was wir bei echten Läufen beobachtet haben

Wir haben am 24.10.2026 einen Text-zu-Bild-Aufruf und einen Bearbeitungsaufruf ausgeführt, beide mit seed: 42, aspect_ratio: "1:1".

• Latenz: Text zu Bild erreichte etwa 29 Sekunden nach der Erstellung success (Zeitstempel von created bis completed der Aufgabe); die Bearbeitung dauerte etwa 22 Sekunden. Der Status durchläuft vor success mehrfach archiving über mehrere Polls hinweg, daher solltest du einen nicht-terminalen Zustand nicht als Fehler werten. Das sind nur zwei Stichproben, kein Benchmark.
• Ausgabe: Beide lieferten ein 2048×2048-PNG, das Ergebnis von Text zu Bild war etwa 3,9 MB groß.
• Bearbeitungsverhalten: Wir gaben die erste Ausgabe erneut ein und baten darum, den Hut violett zu machen. Das Ergebnis behielt Hund, Pose, Wellen und Layout bei und verschob Hutband und Schleife ins Violette; der geflochtene Hauptteil des Huts blieb im Wesentlichen strohfarben. Bei Farbänderungen an texturierten Objekten kann die Befolgung der Anweisung durch die Bearbeitung nur teilweise wirken; der Prompt sollte konkret formuliert sein (z. B. „färbe das Hutband neu ein“) statt allgemein beschreibend.
• Transparenter Hintergrund: Der Alpha-Kanal ist vollständig undurchsichtig. Die Modellseite bewirbt die Ausgabe von PNGs mit transparentem Hintergrund; wir schrieben im Prompt „vollständig transparenter Hintergrund, nur Motiv und Spritzer bleiben erhalten“. Die zurückgegebene Datei war RGBA, aber der Alpha-Wert jedes Pixels war 255 (null transparente Pixel), und die Ecken waren hellgrauweiß (z. B. (241, 243, 248, 255)). Beim Betrachten des Bildes zeigte sich, dass das Modell einen schwachen schachbrettartigen Hintergrund in die Pixel gezeichnet hatte, statt diese Pixel transparent zu lassen. Die Bearbeitungsausgabe verhielt sich gleich (minimaler Alpha-Wert 241). In unserem Lauf ergab der Prompt allein also kein direkt auf eine farbige Seite legbares Freisteller-Ergebnis. Dieses Ergebnis entspricht nur einer Prompt-Formulierung; wir fanden kein Request-Feld zum Umschalten der Transparenz (transparent wird als unbekannte Eigenschaft abgelehnt). Wenn du einen echten Alpha-Kanal benötigst, plane einen Schritt zur Hintergrundentfernung ein, siehe etwa den 851-labs-Leitfaden zur Hintergrundentfernung, und verifiziere vor dem Go-live mit einer Pixelprüfung wie Image.open(f).getchannel("A").getextrema().

Hinweise für den Produktivbetrieb

• Bei hoher Last Callbacks statt Polling verwenden: Füge im Task-Request-Body "callback": {"url": "https://your.app/hook", "when": "final"} hinzu, behandle den Callback als Hinweis und bestätige das Ergebnis mit GET /v1/tasks/<taskId>.
• taskId behalten: Wenn das Polling wegen eines Netzwerkfehlers fehlschlägt, pollst du dieselbe id erneut, statt neu einzureichen. Eine erneute Einreichung erstellt einen zweiten Task und wird berechnet.
• seed fixieren, um beim Anpassen des Prompts vergleichbare Ausgaben zu erhalten; behandle dies als Best-Effort und nicht als harte Garantie.
• Vor der Abrechnung validieren: Schemafehler (HTTP 400, INVALID_REQUEST) werden bei der Erstellung zurückgegeben, zu diesem Zeitpunkt wurde noch kein Bild generiert.

Welche Stufe wählen

In derselben Serie gibt es außerdem Qwen Image 2.1 Pro, das auf der Preisseite mit einem höheren Preis pro Bild als Turbo angegeben ist. Beide werden als unterstützend für Text zu Bild, Bearbeitung und 0–10 Referenzbilder beschrieben; wir haben nur Turbo ausgeführt und treffen daher keine Aussage über die relative Bildqualität. Der Vorteil von Turbo liegt im niedrigeren Preis und der Geschwindigkeit von 8 Schritten; wenn bei deinem Material die Ausgabequalität wichtiger ist, führe beide mit demselben Prompt und Seed aus und vergleiche. Für die neuere Qwen-3.0-Generation siehe den Qwen Image 3.0 API-Leitfaden und den Qwen Image 3.0 Pro-Leitfaden.

Verwandte Inhalte

• Qwen Image 2.1 Turbo Modellseite
• Preise
• Qwen Image 3.0 API-Leitfaden
• Dokumentation

Häufige Fragen

Wie lautet die Modell-ID? qwen-image-2.1-turbo, gesendet über POST /v1/tasks.

Kann man die Ausgabeauflösung wählen? In diesem Schema nicht: Es gibt kein Feld resolution. Wähle aus den fünf erlaubten Werten ein aspect_ratio.

Wird Bearbeitung unterstützt? Ja: Übergib 1–10 Quellbilder in image_urls zusammen mit einem Anweisungs-Prompt. In unserem Test wirkte die Farbbearbeitung texturierter Bereiche nur teilweise.

Wird ein transparentes PNG zurückgegeben? In unserem Test nicht: Die Datei ist im RGBA-Modus, aber der Alpha-Kanal ist vollständig undurchsichtig und enthält einen gezeichneten Hintergrund. Verifiziere das Alpha selbst und füge einen Schritt zur Hintergrundentfernung hinzu, wenn du echte Transparenz benötigst.

Wie hoch ist der Preis? Siehe die Preisseite; zum Zeitpunkt des Verfassens ist es die günstigere der beiden 2.1-Stufen.