Alibaba

Qwen Image 2.1

qwen-image-2.1-pro

Ein einheitliches Bildmodell für Text-zu-Bild und Bildbearbeitung, das nativ 2K-Auflösung und RGBA-Ausgabe mit echtem Alpha-Kanal unterstützt; mehrere Bearbeitungsbereiche lassen sich mit Kreisen, handschriftlichen Markierungen oder Masken festlegen

qwen-image-2.1-pro qwen-image-2.1-turbo

Preise

qwen-image-2.1-pro per image

Einzelpreis	$0.050

Einordnung und Kurzprofil

Qwen Image 2.1 Pro ist die Qualitätsstufe innerhalb der Bildmodellreihe des Alibaba-Qwen-Teams und wird über die einheitliche Schnittstelle von HiAPI.ai aufgerufen; dasselbe Modell unterstützt sowohl Text-zu-Bild als auch Bildbearbeitung. Es kann anhand von 1 bis 10 Referenzbildern Farbänderungen, Austausch, partielle Neugestaltung und weitere Bearbeitungen durchführen oder rein aus Text Bilder erzeugen; die Ausgabe unterstützt verschiedene Seitenverhältnisse von 1:1 bis 9:16, Ergebnisse lassen sich per Seed fixieren, und ein transparenter Hintergrund kann über den Prompt gesteuert werden. Geeignet für Produkt- und Designprozesse, die hochpräzise Bilder und Bearbeitungen mit mehreren Referenzbildern benötigen.

Zentrale Highlights

Generierung und Bearbeitung in einem Modell – kein Wechsel der Modellgewichte zwischen Text-zu-Bild und Bild-zu-Bild nötig; eine Aufrufkette deckt beide Aufgabentypen ab.
Bis zu 10 Referenzbilder mit geordneter Referenzierung – bei mehreren Bildern wird die Reihenfolge im Array nummeriert; im Prompt kann präzise auf „Bild 1“, „Bild 2“ verwiesen werden, was die Zusammenführung mehrerer Materialien und konsistente Bearbeitungen erleichtert.
Reproduzierbar per Seed, ideal für Regressionsprüfungen – ein fester Zufalls-Seed von 0–2147483647 macht Ergebnisse relativ stabil und eignet sich für Batch-Prozesse und Debugging mit wiederholter Bilderzeugung.
Automatische Prompt-Erweiterung optional zuschaltbar – prompt_extend ist standardmäßig aktiviert und verbessert kurze Prompts deutlich; wenn eine strikte Orientierung am Originaltext gewünscht ist, lässt es sich deaktivieren, um die ursprüngliche Bedeutung zu bewahren.

Funktionsbeschreibung

Einheitlich für Text-zu-Bild und Bildbearbeitung: Dasselbe Modell erzeugt Bilder aus Prompts und kann Referenzbilder gemäß Prompt ändern, wodurch Stil- und Prozessbrüche durch die Verkettung mehrerer Modelle reduziert werden.

Eingabe mehrerer Referenzbilder: Unterstützt 1 bis 10 öffentlich zugängliche Bilder; diese werden in Array-Reihenfolge nummeriert und im Prompt referenziert, nutzbar für die Fusion mehrerer Materialien und bereichsweise Bearbeitung.

Ausgabe in mehreren Seitenverhältnissen: Fünf Formate stehen zur Wahl – 1:1, 16:9, 9:16, 4:3 und 3:4 – mit Größen bis zu 2688×1536; wird nichts angegeben, wählt das Modell anhand von Prompt und Referenzbildern automatisch.

Steuerung des transparenten Hintergrunds: Wird im Prompt „transparenter Hintergrund“ angegeben, entsteht ein Bild mit transparentem Hintergrund, sodass nachträgliches Freistellen entfällt.

Reproduzierbare Ergebnisse: Über den Parameter seed wird der Zufalls-Seed fixiert; bei gleichen Eingaben sind relativ stabile Ausgaben möglich, was Batch-Generierung und Effekt-Regression erleichtert.

Anwendungsfälle

Bildbearbeitung für E-Commerce- und Designteams – Produkt- oder Model-Referenzbilder hochladen und per Prompt Farbänderungen, das Ersetzen von Kleidungsbereichen und weitere Änderungen angeben, um direkt nutzbare Bilder für Detailseiten und Werbematerial zu erhalten.
Markenvisuals durch Zusammenführung mehrerer Materialien – mehrere Referenzbilder eingeben und in Reihenfolge referenzieren, um stilkonsistente Kompositionen für Poster, Social-Media-Grafiken und Event-Material zu erzeugen.
Icons und Produktbilder mit transparentem Hintergrund – im Prompt einen transparenten Hintergrund anfordern, um Bildassets zu erhalten, die direkt in Oberflächen oder Compositing-Ebenen eingebunden werden können, was Nachbearbeitungsschritte reduziert.
Automatisierte Pipelines für Batch-Ausgaben – Seed und Seitenverhältnis fest vorgeben und Generierungs- oder Bearbeitungsaufrufe in die Content-Produktionspipeline einbetten, um stabil serialisierte Bilder auszugeben.

Einschränkungen und Auswahlhinweise

Dieses Modell ist die Qualitätsstufe der Reihe; Dauer und Kosten pro Bild liegen über denen der turbo-Stufe derselben Reihe, daher eignet es sich für Szenarien mit hohen Anforderungen an die Bildqualität. Für umfangreiche Vorschauen oder kostengünstige Vorauswahl kann die turbo-Stufe erwogen werden. Eingabereferenzbilder müssen über öffentlich erreichbare URLs verfügbar sein, dürfen jeweils 10 MB nicht überschreiten, und das Verhältnis von langer zu kurzer Seite darf 10:1 nicht übersteigen. Der Prompt ist auf 4500 Zeichen begrenzt; wenn eine strikte Orientierung am Originaltext gewünscht ist, sollte die automatische Erweiterung deaktiviert werden. Steht eine möglichst geringe Latenz im Vordergrund oder werden nur einfache Batch-Generierungen benötigt, sollte eine leichtere Wahl geprüft werden.

Generierungsaufgabe erstellen

POST https://api.hiapi.ai/v1/tasks

Header

AuthorizationstringPflicht

Account-API-Schlüssel. Bei jeder Anfrage erforderlich. Beispiel: Bearer YOUR_HIAPI_API_KEY. API-Schlüssel holen

Content-TypestringOptional

Der Anfragekörper wird immer als JSON geparst; beim Senden ist nur application/json (optional mit charset) zulässig — andere Werte liefern 415. Beispiel: application/json.

Idempotency-KeystringOptional

Idempotenz-Schlüssel, bis 255 Bytes. Wiederholungen mit demselben Schlüssel desselben Kontos erstellen die Aufgabe nur einmal; Replays liefern die ursprüngliche taskId.

Idempotenz-Schlüssel

Bei Netzwerk-Timeouts oder Client-Wiederholungen erstellt derselbe Schlüssel die Aufgabe nur einmal — keine doppelte Abbuchung (Geltungsbereich = das Konto des API-Schlüssels). Empfohlen: geschäftsseitig eindeutige Kennung (z. B. "order-42"); Replays liefern die ursprüngliche taskId, Schlüssel laufen 24 Stunden nach der ersten Anfrage ab. Die vollständige Szenariomatrix steht in der Übersicht der Unified Async API.

Body

modelstringPflicht

Aktueller Festwert: qwen-image-2.1-pro

routestringOptional

Aktueller Festwert: default

inputobjectPflicht

Geschäftsparameter für qwen-image-2.1-pro und Route default — siehe Parametertabelle unten.

seedintegerOptionalmin 0max 2147483647

Zufälliger Startwert, ganzzahlig von 0–2147483647; wird dieser Wert festgelegt, bleibt das Generierungsergebnis relativ stabil, bei Nichtangabe wird er zufällig erzeugt.

promptstringPflichtminLength 1maxLength 4500

Beschreibt den zu generierenden Bildinhalt oder gibt an, welche Änderungen an den Referenzbildern vorgenommen werden sollen; Chinesisch oder Englisch ist möglich, zu rendernder Text muss wortwörtlich in den Prompt geschrieben werden, bei transparentem Hintergrund im Prompt „transparenter Hintergrund“ angeben.

image_urlsarrayOptionalminItems 1maxItems 10

Ein Array öffentlicher URLs von Referenzbildern oder zu bearbeitenden Bildern, 1–10 Stück; bei Nichtangabe erfolgt Text-zu-Bild-Generierung. Mehrere Bilder werden in Array-Reihenfolge nummeriert (verweisbar als „Bild 1“, „Bild 2“). Unterstützt werden JPG, JPEG, PNG, BMP, TIFF, WEBP, GIF, je maximal 10 MB, Breite und Höhe jeweils zwischen 1–8000 Pixel (empfohlen 384–2048), das Verhältnis von langer zu kurzer Seite höchstens 10:1.

Array [ string ]

aspect_ratiostringOptional

Ausgabeformat als Zeichenkette, entsprechend Größen wie 2048×2048, 2688×1536, 1536×2688, 2368×1728, 1728×2368; bei Nichtangabe wählt das Modell automatisch anhand von Prompt und Referenzbildern.

Optionen:1:116:99:164:33:4

prompt_extendbooleanOptionalStandard: true

Ob der Prompt automatisch optimiert wird, boolescher Wert, Standard true; aktiviert verbessert dies kurze Prompts deutlich, erhöht jedoch die Laufzeit um einige Sekunden; bei strikter Einhaltung des Originaltexts kann dies deaktiviert werden.

callbackobjectOptional

Konfiguration der Endzustands-Benachrichtigung. Ohne Angabe wird kein Callback gesendet — selbst abfragen.

Callbacks (Webhook)

Beim Erstellen callback.url angeben, dann POSTet HiAPI im Endzustand an Ihren Service — kein Polling nötig. Der Callback-Body entspricht der Aufgaben-Detailstruktur; Signaturprüfung, Wiederholungen und Idempotenz sind in der Übersicht der Unified Async API beschrieben.

urlstringPflicht

Pflicht, wenn callback angegeben ist. Nach dem Endzustand wird an diese URL gepostet; muss eine gültige http(s)-URL sein.

whenstringOptionalStandard: "final"

Derzeit wird nur final unterstützt — Benachrichtigung bei success und fail.

Optionen:final

storagestringOptionalStandard: "temp"

Speicherstufe für Artefakte: temp (Standard, ca. 7 Tage) oder persistent (langfristig, nach Größe abgerechnet). Bei unzureichendem Guthaben oder Überschreitung des Speicherlimits erfolgt ein stiller Downgrade auf temp; die wirksame Stufe steht in der Aufgaben-Detailantwort.

Optionen:temppersistent

Anfragebeispiele

# Asynchrone Aufgabe senden; gibt sofort eine taskId zurück (wartet nicht auf die Generierung)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "qwen-image-2.1-pro",
  "input": {
    "prompt": "…",
    "prompt_extend": true
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen-image-2.1-pro",
    input: {
      "prompt": "…",
      "prompt_extend": true
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "qwen-image-2.1-pro",
        "input": {
          "prompt": "…",
          "prompt_extend": True
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
  }
}

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Aufgabendetails abrufen

GET https://api.hiapi.ai/v1/tasks/:id

Antwortfelder

taskIdstringPflicht

Aufgaben-ID, stets mit Präfix tk-hiapi-.

modelstringPflicht

Aufgelöster vollständiger Modellname. Mit route-Parameter eingereichte Aufgaben geben base@route zurück (z. B. gpt-image-2/text-to-image@ext); sonst identisch mit dem übermittelten Namen.

routestringOptional

Erscheint nur bei explizitem route-Parameter; gibt den übermittelten Wert zurück.

statusstringPflicht

Aufgabenstatus.

Statuswerte

queued Eingereiht, noch nicht gestartet. handling In Verarbeitung. archiving Verarbeitung abgeschlossen, Artefakte werden vorbereitet. success Endzustand: abgeschlossen, Artefakte verfügbar (output wird zurückgegeben). fail Endzustand: fehlgeschlagen (error wird zurückgegeben). Nach dem Senden den status prüfen: success und fail sind Endzustände, alles andere nicht. Alle 1–3 Sekunden bis zum Endzustand pollen. Nach Erfolg Artefakte aus output[].url laden und vor expireAt übertragen; für Langzeitaufbewahrung storage: "persistent" beim Erstellen angeben.

creatednumberPflicht

Zeitpunkt der Aufgabenerstellung (Unix-Sekunden).

completednumberPflicht

Unix-Sekunden des Endzustands; vor Abschluss stets 0.

outputarrayOptional

Nur bei status == success. Artefaktliste — immer ein Array; eine Aufgabe kann mehrere Typen gleichzeitig liefern (z. B. video + first_frame).

Array [ object ]

Array-Elemente

urlstringPflicht

Artefakt-URL, direkt herunterladbar.

typestringPflicht

Aktuell mögliche Werte: video, image, audio, first_frame, last_frame, thumbnail; später können weitere folgen.

expireAtnumberPflicht

Unix-Sekunden, bis wann das Artefakt verfügbar ist; vorher herunterladen oder übertragen.

errorobjectOptional

Nur bei status == fail.

codestringPflicht

Business-Fehlercode.

messagestringPflicht

Fehlerbeschreibung.

Antwortbeispiele

Erfolg

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

In Bearbeitung (nicht final)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Fehlgeschlagen

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}