Alibaba

Qwen Image 2.1

qwen-image-2.1-turbo

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-turbo per image

Einzelpreis	$0.020

Kurzprofil

qwen-image-2.1-turbo ist ein Modell der Qwen Image 2.1-Serie für die häufig aufgerufene Bilderzeugung und -bearbeitung. Es unterstützt zwei Aufgabentypen: Text-zu-Bild und Bild-zu-Bild – entweder wird aus einer Eingabeaufforderung direkt ein Bild erzeugt oder es werden bis zu 10 Referenzbilder übergeben, um gezielte lokale Änderungen an einem bestimmten Bild per Nummernverweis vorzunehmen. Die Ausgabe ist ein statisches Bild, das in Seitenverhältnissen wie 1:1 oder 16:9 erzeugt werden kann; ein fester Zufallsseed ermöglicht die Reproduktion der Ergebnisse. Geeignet für Entwickler, die visuelle Assets in großem Umfang produzieren, Prompts schnell iterieren und Prototypen validieren möchten.

Kernhighlights

Erzeugung und Bearbeitung nutzen dieselben Aufrufparameter – bei Text-zu-Bild werden keine Referenzbilder übergeben, bei der Bildbearbeitung 1–10 Bild-URLs; Prompt und übrige Parameterstruktur bleiben identisch, der Integrationsaufwand ist gering.
Mehrere Referenzbilder lassen sich per Nummer referenzieren – mehrere Eingabebilder werden in Array-Reihenfolge nummeriert; im Prompt kann mit „Bild 1“, „Bild 2“ präzise das Bearbeitungsobjekt angegeben werden, was Mehrdeutigkeiten reduziert.
Kontrollierbare Zufälligkeit – der Seed deckt 0–2147483647 ab; nach dem Fixieren sind die Ergebnisse relativ stabil, was Regressionstests und die Reproduzierbarkeit von Batch-Aufgaben erleichtert.

Funktionsbeschreibung

Einheitlicher Aufruf für Text-zu-Bild und Bild-zu-Bild: prompt ist Pflichtfeld; wird image_urls nicht übergeben, erfolgt reine Textgenerierung, werden 1–10 öffentlich erreichbare Bilder übergeben, wird daraus eine Bearbeitungsaufgabe – dieselbe Schnittstelle deckt beide Anforderungen ab.

Mehrere Referenzbilder und referenzierte Bearbeitung: Es können bis zu 10 Referenzbilder gleichzeitig eingebunden und automatisch nummeriert werden; der Prompt kann gezielte lokale Änderungen an einem bestimmten Bild vornehmen, geeignet für die Kombination mehrerer Materialien oder bereichsweise Bearbeitung.

Kontrolliertes Bildformat und Größe: aspect_ratio bietet fünf Stufen – 1:1, 16:9, 9:16, 4:3, 3:4 – mit entsprechenden festen Pixelgrößen von 2048×2048 bis 2688×1536; wird nichts übergeben, wählt das Modell automatisch anhand von Prompt und Referenzbildern.

Schalter für Prompt-Erweiterung: prompt_extend ist standardmäßig aktiviert und kann kurze Prompts automatisch optimieren, kostet dafür einige Sekunden zusätzliche Zeit; wenn eine strikte Layouttreue oder das Rendern vorgegebener Texte erforderlich ist, kann er deaktiviert werden, um die Kontrollierbarkeit zu gewährleisten.

Lange Prompts und Textrendering: prompt umfasst maximal 4500 Zeichen, Chinesisch und Englisch sind beide möglich; Texte, die im Bild erscheinen sollen, können Zeichen für Zeichen in den Prompt geschrieben werden, auch ein transparenter Hintergrund kann im Prompt angegeben werden.

Anwendungsszenarien

Design-Teams produzieren in großem Umfang erste visuelle Entwürfe – aus einer Textbeschreibung wird ein fertiges Bild erzeugt, das Bildformat wird nach Bedarf gewählt; für die schnelle Massenproduktion von Erstentwürfen für Event-Materialien, Social-Media-Grafiken und ähnliche Szenarien.
E-Commerce-Betreiber ändern die Farbe von Produktbildern lokal – das Originalproduktbild wird hochgeladen und der zu ändernde Bereich beschrieben; die Ausgabe bleibt in der Komposition konsistent und kann direkt zum Austausch auf Detailseiten und zur Darstellung farbiger SKUs verwendet werden.
Kombination mehrerer Materialien und Bearbeitung mit Referenzbildern – mehrere Referenzbilder werden gleichzeitig übergeben und per Nummer referenziert; die Ausgabe ist ein einzelnes Bild nach Zusammenführung oder Ersetzung, geeignet für Kompositing-Szenarien und Materialintegration.
Batch-Pipelines mit reproduzierbaren Ergebnissen – bei fixiertem Seed und festem Prompt werden wiederholte Aufrufe relativ stabile Ergebnisse liefern, was die Einbindung in automatisierte Tests und Rollback-Prozesse für Assets erleichtert.

Einschränkungen und Auswahlhinweise

Dieses Modell gibt ausschließlich statische Bilder aus und unterstützt keine Videos oder dynamischen Inhalte. Referenzbilder müssen über öffentlich erreichbare URLs verfügbar sein, dürfen je Bild maximal 10 MB groß sein, eine Breite und Höhe zwischen 1 und 8000 Pixeln aufweisen und ein Verhältnis von langer zu kurzer Seite von höchstens 10:1 haben; außerhalb dieses Bereichs liegende Bilder müssen vorab selbst aufbereitet werden. Das Bildformat kann nur aus den fünf festen Stufen gewählt werden, eine beliebige Auflösung ist nicht möglich. Die aktivierte Prompt-Erweiterung verursacht einige Sekunden zusätzlichen Zeitaufwand; bei Anforderungen an striktes Layout beim Textrendering sollte sie deaktiviert und das Ergebnis selbst geprüft werden. Geeignet für Aufgaben mittleren Umfangs bei Erzeugung und Bearbeitung, bei denen Geschwindigkeit und Kosten priorisiert werden; wenn höhere Bildqualität oder mehr Aufrufkontingent benötigt wird, kann die pro-Version derselben Serie gewählt 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-turbo

routestringOptional

Aktueller Festwert: default

inputobjectPflicht

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

seedintegerOptionalmin 0max 2147483647

Zufälliger Startwert, ganzzahlig von 0 bis 2147483647; ein fester Startwert macht die Generierungsergebnisse relativ stabil, wird kein Wert übergeben, bleibt er zufällig.

promptstringPflichtminLength 1maxLength 4500

Beschreibt das zu generierende Bild oder erläutert, welche Änderungen am Referenzbild vorgenommen werden sollen; Chinesisch oder Englisch sind möglich. Text, der gerendert werden soll, muss zeichengenau 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; wird nichts übergeben, handelt es sich um Text-zu-Bild. Mehrere Bilder werden in Array-Reihenfolge nummeriert und können im Prompt mit „Bild1“, „Bild2“ referenziert werden; unterstützt werden JPG, JPEG, PNG, BMP, TIFF, WEBP, GIF, pro Bild maximal 10 MB, Breite und Höhe jeweils zwischen 1 und 8000 Pixeln (empfohlen 384–2048), das Verhältnis von langer zu kurzer Seite darf 10:1 nicht überschreiten.

Array [ string ]

aspect_ratiostringOptional

Ausgabe-Seitenverhältnis, entsprechend 2048×2048, 2688×1536, 1536×2688, 2368×1728, 1728×2368; wird nichts übergeben, wählt das Modell die Größe automatisch anhand von Prompt und Referenzbild.

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

prompt_extendbooleanOptionalStandard: true

Ob der Prompt automatisch optimiert werden soll, Standard true. Aktiviert bringt es bei kurzen Prompts deutliche Verbesserungen, erhöht aber die Laufzeit um einige Sekunden; soll das Original-Layout strikt eingehalten werden, kann es 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-turbo",
  "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-turbo",
    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-turbo",
        "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"
    }
  }
}