Qwen Image Edit Kurzanleitung zum Bearbeiten von Bildern mit Textanweisungen

Die Qwen Image Edit API auf Novita AI modifiziert ein vorhandenes Bild mithilfe einer natürlichsprachlichen Anweisung, unterstützt durch das 20B Qwen-Image-Modell. Dieser Schnellstart behandelt den gesamten asynchronen Workflow: Senden Sie eine Bearbeitungsanfrage mit Ihrem Quellbild und Prompt, erhalten Sie eine Aufgaben-ID, fragen Sie ab, bis die Bearbeitung abgeschlossen ist, und rufen Sie die URL des bearbeiteten Bildes ab. Der Endpunkt ist POST https://api.novita.ai/v3/async/qwen-image-edit.

Inhaltsverzeichnis

Wann Sie diesen Schnellstart verwenden sollten

Verwenden Sie diese Anleitung, wenn Sie Folgendes benötigen:

• Ein vorhandenes Bild durch eine Textanweisung modifizieren – Hintergründe ändern, Stile tauschen, Elemente entfernen, Objekte drehen oder Kleidung anpassen, ohne das Bild von Grund auf neu zu erstellen.
• Unberührte Bereiche intakt lassen, während gezielte Änderungen vorgenommen werden. Die Dual-Path-Architektur des Modells (Qwen2.5-VL für semantisches Verständnis + VAE-Encoder für die Wahrung des Aussehens) wurde speziell entwickelt, um zu verhindern, dass Änderungen in Bereiche übergreifen, die Sie nicht beschrieben haben.
• Text in Bildern präzise bearbeiten. Qwen Image Edit beherrscht zweisprachige englische und chinesische Textersetzungen auf Schildern, Postern und Markenmaterialien – unter Beibehaltung von Schriftart, Größe und umgebendem visuellen Stil, was bei den meisten Bildgeneratoren fehlschlägt.

Wenn Sie ein neues Bild nur aus einem Prompt generieren (kein Eingabebild erforderlich), verwenden Sie stattdessen die Qwen Image txt2img-Schnellstartanleitung. Eine vollständige Übersicht über die Fähigkeiten, Benchmarks und Architektur des Modells finden Sie im Qwen-Image auf Novita AI Launch-Beitrag.

Schritt 1: Holen Sie sich Ihren Novita-API-Schlüssel

Erstellen Sie ein Novita AI-Konto und navigieren Sie zur API-Schlüsselverwaltung. Generieren Sie einen Schlüssel und speichern Sie ihn als Umgebungsvariable, bevor Sie eines der folgenden Codebeispiele ausführen:

export NOVITA_API_KEY="your_api_key_here"

Halten Sie den Schlüssel aus clientseitigem Code, Frontend-Bundles und Versionskontrolle fern. Falls der Schlüssel kompromittiert wird, rotieren Sie ihn auf derselben Einstellungsseite.

Schritt 2: Bestätigen Sie den Endpunkt und das Modell

Element	Wert
Bearbeitungsendpunkt	POST https://api.novita.ai/v3/async/qwen-image-edit
Polling-Endpunkt für Ergebnisse	GET https://api.novita.ai/v3/async/task-result?task_id=<id>
Modell	Qwen Image Edit (20B MMDiT, Dual-Path-Architektur)
API-Dokumentation	Novita AI Qwen Image Edit Referenz

Die API ist asynchron. Der Bearbeitungsaufruf gibt sofort eine task_id zurück; Sie fragen den Ergebnis-Endpunkt ab, bis der Status TASK_STATUS_SUCCEED ist. Dies ist das gleiche Zwei-Schritt-Muster, das von allen Novita AI-Bildgenerierungs-Endpunkten verwendet wird, einschließlich des txt2img-Endpunkts.

Die Preisgestaltung beträgt 0,02 $ pro Bild. Überprüfen Sie den aktuellen Tarif auf der Novita AI-Preisseite, bevor Sie ein Kostenmodell erstellen.

Schritt 3: Senden Sie Ihre erste Bearbeitungsanfrage

Senden Sie eine POST-Anfrage an den Bearbeitungsendpunkt mit Ihrem Quellbild und der Bearbeitungsanweisung:

curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Change the background to a snowy mountain landscape",
    "image": "https://example.com/my-portrait.jpg"
  }'

Eine erfolgreiche 200-Antwort gibt Folgendes zurück:

{
  "task_id": "abc123..."
}

Speichern Sie die task_id – Sie benötigen sie, um das bearbeitete Bild abzurufen.

Schritt 4: Fragen Sie Ihr Ergebnis ab

Senden Sie eine GET-Anfrage an den Ergebnis-Endpunkt mit der task_id als Query-Parameter:

curl -s "https://api.novita.ai/v3/async/task-result?task_id=abc123..." \
  -H "Authorization: Bearer $NOVITA_API_KEY"

Fragen Sie weiter ab, bis das Feld task_status den Wert TASK_STATUS_SUCCEED hat:

{
  "task_status": "TASK_STATUS_SUCCEED",
  "images": [
    {
      "image_url": "https://...",
      "image_url_ttl": "86400",
      "image_type": "JPEG"
    }
  ]
}

Die image_url läuft nach dem TTL-Zeitraum (in der Regel 24 Stunden) ab. Laden Sie das Ergebnis herunter und speichern Sie es in Ihrem eigenen Objektspeicher, wenn Sie einen langfristigen Zugriff benötigen.

Zu behandelnde Statuswerte:

Status	Bedeutung
TASK_STATUS_QUEUED	Anfrage wartet in der Warteschlange; weiter abfragen
TASK_STATUS_PROCESSING	Bearbeitung läuft; weiter abfragen
TASK_STATUS_SUCCEED	Abgeschlossen; lesen Sie das bearbeitete Bild von images[0].image_url
TASK_STATUS_FAILED	Generierung fehlgeschlagen; überprüfen Sie das Fehlerfeld auf den Grund

Schritt 5: Preise, Limits und häufige Fehler prüfen

Preise: 0,02 $ pro Bild (überprüfen Sie auf der Preisseite).

Ratenlimits: Überprüfen Sie die API-Referenz auf aktuelle Ratenlimits. Wenn Sie einen 429 erhalten, reduzieren Sie Ihre Anfragrate und implementieren Sie einen exponentiellen Backoff bei Wiederholungsversuchen.

Häufige HTTP-Fehler:

Statuscode	Wahrscheinliche Ursache
400	Fehlerhafter Anforderungstext – fehlender prompt oder image, ungültiges Bildformat oder nicht unterstützte Eingabegröße
401	Fehlender oder ungültiger API-Schlüssel – überprüfen Sie das Format Authorization: Bearer <key>
429	Ratenlimit überschritten – Backoff und Wiederholungslogik hinzufügen
500	Serverseitiger Fehler – nach kurzer Verzögerung erneut versuchen

Wenn der Aufgabenstatus TASK_STATUS_FAILED ist, enthält die Antwort in der Regel eine Fehlermeldung. Häufige Gründe sind nicht unterstützte Bildformate, Bilder, die die Größenbeschränkungen überschreiten, oder Prompts, die Inhaltsfilter auslösen.

Python-Beispiel

Dieses Skript sendet eine Bearbeitungsanfrage, fragt ab, bis sie abgeschlossen ist, und gibt die URL des Ausgabebildes aus:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai/v3/async"


def submit_edit(image: str, prompt: str, seed: int | None = None) -> str:
    payload: dict = {"prompt": prompt, "image": image}
    if seed is not None:
        payload["seed"] = seed
    response = requests.post(
        f"{BASE_URL}/qwen-image-edit",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
    )
    response.raise_for_status()
    return response.json()["task_id"]


def poll_result(task_id: str, interval: float = 2.0, timeout: float = 120.0) -> dict:
    deadline = time.time() + timeout
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/task-result",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"task_id": task_id},
        )
        response.raise_for_status()
        data = response.json()
        status = data.get("task_status", "")
        if status == "TASK_STATUS_SUCCEED":
            return data
        if status == "TASK_STATUS_FAILED":
            raise RuntimeError(f"Edit task failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    task_id = submit_edit(
        image="https://example.com/product-photo.jpg",
        prompt="Change the jacket to a red leather jacket, preserve the background",
    )
    print(f"Task ID: {task_id}")

    result = poll_result(task_id)
    for img in result["images"]:
        print(img["image_url"])

cURL-Beispiel

Zweischrittiger Workflow mit jq für JSON-Parsing:

#!/bin/bash
# Schritt 1: Bearbeitungsanfrage senden
TASK_ID=$(curl -s -X POST https://api.novita.ai/v3/async/qwen-image-edit \
  -H "Authorization: Bearer $NOVITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Convert to watercolor painting style, preserve the subject and composition",
    "image": "https://example.com/landscape.jpg"
  }' | jq -r '.task_id')

echo "Task ID: $TASK_ID"

# Schritt 2: Abfragen, bis abgeschlossen
while true; do
  RESULT=$(curl -s "https://api.novita.ai/v3/async/task-result?task_id=$TASK_ID" \
    -H "Authorization: Bearer $NOVITA_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.task_status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "TASK_STATUS_SUCCEED" ]; then
    echo "$RESULT" | jq -r '.images[].image_url'
    break
  elif [ "$STATUS" = "TASK_STATUS_FAILED" ]; then
    echo "Task failed:"
    echo "$RESULT" | jq .
    exit 1
  fi
  sleep 2
done

Installieren Sie jq mit apt install jq (Debian/Ubuntu) oder brew install jq (macOS), falls es nicht bereits vorhanden ist.

Wichtige Parameter

Parameter	Typ	Erforderlich	Standard	Beschreibung
prompt	string	Ja	—	Natürlichsprachliche Anweisung, die die gewünschte Bearbeitung beschreibt
image	string	Ja	—	Quellbild als URL oder base64-codierter String
seed	integer	Nein	zufällig	Fester Seed für reproduzierbare Ausgaben über mehrere Durchläufe
output_format	string	Nein	jpeg	Ausgabeformat – siehe API-Dokumentation für akzeptierte Werte

Effektive Prompts schreiben: Spezifität ist wichtig. „Ändere den Text auf der Werbetafel zu ‘Summer Sale’" gibt dem Modell eine klare, abgegrenzte Aufgabe. „Verbessere das Bild" tut dies nicht. Wenn Sie ein Element ändern und alles andere intakt lassen möchten, nennen Sie, was Sie erhalten möchten: „Ändere die Jackenfarbe auf Rot, behalte den Hintergrund und das Gesicht unverändert." Dies hilft dem VAE-Encoder-Pfad, seine Aufgabe zu erfüllen, unberührte Regionen zu sichern.

Verwendung von seed für Iterationen: Wenn Sie einen Prompt verfeinern, ermöglicht das Fixieren des Seeds einen direkten Vergleich der Ergebnisse – die Ausgabevariation stammt von Ihrer Prompt-Änderung, nicht vom zufälligen Sampling. Sobald Sie einen funktionierenden Prompt gefunden haben, entfernen Sie die Seed-Einschränkung, wenn Sie Ausgabevielfalt über mehrere Bearbeitungen hinweg wünschen.

Typische Anwendungsfälle

Hintergrundersetzung: „Ersetze den Hintergrund durch ein minimalistische weißes Studio" – Qwen Image Edit erhält die Kanten und die Beleuchtung des Motivs, während die Umgebung ausgetauscht wird. Funktioniert zuverlässig, wenn das Motiv eine klare Abgrenzung zum ursprünglichen Hintergrund hat.

Text in Bildern: Ersetzen von Ladenschildern, Plakatüberschriften oder Produktbeschriftungen durch neuen Text – einschließlich Chinesisch und Englisch. Das Modell erhält Schriftstil und umgebenden visuellen Kontext besser als generative Inpainting-Ansätze, die tendenziell die gesamte Region neu generieren.

Stilkonvertierung: „Konvertiere in Ölgemälde-Stil" oder „lass dies wie eine Bleistiftskizze aussehen", angewendet auf ein Quellbild anstatt von Grund auf beschrieben. Der VAE-Encoder-Pfad erhält die ursprüngliche Komposition und Objektplatzierung, während der Prompt die Stiltransformation antreibt.

Objektbezogene Änderungen: Kleidung tauschen, Farben bestimmter Gegenstände ändern, Accessoires hinzufügen oder entfernen. Die Anweisung sollte das spezifische Element nennen, das geändert wird, um zu verhindern, dass die Bearbeitung benachbarte Regionen beeinflusst.

IP-Konvertierung und Objektrotation: Das Modell unterstützt Ansichtssyntheseänderungen (z. B. Drehen eines Objekts, um einen anderen Winkel zu zeigen) und Konvertierung zwischen visuellen Stilen für Charakter- oder Produktdarstellungen – Anwendungsfälle dokumentiert im Qwen-Image-Edit auf Novita AI Überblick.

Fehlerbehebung

Ausgabe sieht unverändert aus: Die Anweisung ist wahrscheinlich zu ungenau. Machen Sie expliziter, welches Element anvisiert werden soll: „Ändere die Farbe des Autos von Blau auf Rot" anstatt „mach es rot."

Ungewollte Änderungen breiten sich in unbeabsichtigte Bereiche aus: Fügen Sie bei sehr spezifischen lokalen Änderungen explizite Erhaltungssprache in Ihren Prompt ein: „ändere nur X, lasse Y intakt." Zu offene Prompts geben dem Modell Spielraum, die gesamte Komposition neu zu interpretieren.

Aufgabe abgeschlossen, aber Bild-URL gibt 403 oder 404 zurück: Das Feld image_url_ttl (in Sekunden) sagt Ihnen, wie lange die URL gültig ist. Wenn Sie die URL später als das TTL abfragen, ist die URL abgelaufen. Laden Sie das Bild sofort nach erfolgreicher Abfrage herunter.

401 Unauthorized: Überprüfen Sie, ob das Format des Authorization-Headers genau Bearer <key> mit einem Leerzeichen nach Bearer ist. Bestätigen Sie, dass der Schlüssel aktiv und nicht in der Novita AI-Konsole widerrufen wurde.

Aufgaben laufen durchgehend in ein Timeout: Die Bildbearbeitung dauert länger als die Textgenerierung – typischerweise 15–60 Sekunden unter normaler Last. Wenn Aufgaben regelmäßig Ihr Timeout überschreiten, erhöhen Sie das Polling-Fenster, bevor Sie es als Fehler behandeln.

FAQ

Bleibt das Quellbild auf Novitas Servern?

Ihr Bild wird über HTTPS an die API von Novita AI hochgeladen und auf deren Infrastruktur verarbeitet. Überprüfen Sie die Datenverarbeitungsrichtlinien von Novita AI, bevor Sie Bilder mit sensiblen persönlichen Daten, privaten Gesundheitsdaten oder vertraulichem Inhalt senden.

Kann ich base64-codierte Bilder anstelle einer URL verwenden?

Ja. Übergeben Sie den rohen base64-String im Feld image. Konsultieren Sie die API-Referenz für etwaige Größenbeschränkungen von base64-Nutzdaten.

Gibt es einen Seed-Parameter für Konsistenz?

Ja – der optionale Parameter seed fixiert den Zufallszustand, sodass derselbe Prompt und dasselbe Bild konsistente Ergebnisse liefern. Nützlich, um an der Formulierung des Prompts zu iterieren, ohne Ausgabestörungen durch erneutes Sampling zu erhalten.

Kann ich diesen Endpunkt für Batch-Jobs verwenden?

Ja. Senden Sie mehrere Bearbeitungsanfragen parallel und sammeln Sie die task_id-Werte, fragen Sie sie dann gleichzeitig ab. Jede Anfrage ist unabhängig.

Was ist der Unterschied zwischen diesem und dem Qwen Image txt2img-Endpunkt?

Der Bearbeitungsendpunkt erfordert ein Quellbild und erstellt eine modifizierte Version davon. Der txt2img-Endpunkt generiert ein Bild vollständig aus einem Text-Prompt – kein Eingabebild. Verwenden Sie den Bearbeitungsendpunkt, wenn Sie vorhandene Inhalte modifizieren möchten; verwenden Sie txt2img, wenn Sie von Grund auf neu erstellen.

Empfohlene Artikel

• Qwen Image Text-zu-Bild Schnellstart für die Generierung von Bildern aus Prompts
• Qwen-Image-Edit auf Novita AI: Professionelle Bearbeitung für nur 0,02 $
• Novita AI bietet jetzt Qwen-Image: Fortschrittliches 20B Text-zu-Bild-Modell