So verwendest du die wan2.7-image-standard API auf hiapi: Text-zu-Bild und Bearbeitung mit Referenzbildern

wan2.7-image-standard ist die Standardstufe des Tongyi Wanxiang Wan 2.7 Image-Modells. Der Grund, warum es eine eigene Seite verdient: Eine einzige Modell-ID unterstützt sowohl Text-zu-Bild als auch referenzbildbasierte Bildbearbeitung, bis zu 2K, zu einem Festpreis von 0,0345 $ pro Bild – günstiger als die Pro-Stufe mit 4K-Unterstützung. Dieser Leitfaden bietet eine direkt ausführbare Anfrage, das exakte Eingabe-Schema (gegen die Live-API verifiziert), den Pfad zur Referenzbildbearbeitung und die Randverhalten, die du in der Produktion zwingend behandeln musst.

Alle Inhalte im Schema- und Fehlerabschnitt unten wurden während des Schreibens durch Abfragen des Live-/v1/tasks-Endpunkts bestätigt – Enumerationslisten, akzeptierte Feldsätze und Fehlerantwortformen stammen aus echten API-Antworten, nicht aus dem Gedächtnis.

Was du baust und was du vorbereiten musst

Du reichst einen Prompt ein (optional mit Referenzbild), pollst bis zur Aufgabenfertigstellung und lädst dann das Bild herunter. Zuerst brauchst du eine Sache: einen API-Schlüssel aus dem hiapi-Schnellstart, den du als HIAPI_API_KEY exportierst. Es gibt keinen schlüsselfreien Pfad – jede Anfrage wird über Authorization: Bearer sk-<your-key> authentifiziert.

wan2.7-image-standard läuft auf der asynchronen Aufgaben-API von hiapi: Du erstellst eine Aufgabe mit POST /v1/tasks und pollst dann den Detail-Endpunkt, bis er einen Endzustand meldet.

Text-zu-Bild: minimale Anfrage

Aufgabe erstellen:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Blaue Stunde nach dem Regen, ein kleines Töpferatelier in einer ruhigen, menschenleeren Gasse, warme Papierlaternen hängen, glasierte Teekannen im Schaufenster, Lichter spiegeln sich auf feuchten Pflastersteinen, ein Fahrrad lehnt an der Wand, filmische 35-mm-Fotografie, hohe Detailgenauigkeit",
      "aspect_ratio": "16:9",
      "resolution": "2K"
    }
  }'

Die Aufgaben-ID in der Antwort befindet sich in data.taskId:

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

Dann pollst du GET /v1/tasks/<taskId>, bis data.status success ist, und liest die Bild-URL aus data.output[0].url:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

def generate(prompt, aspect_ratio="16:9", resolution="2K", image_urls=None, timeout=600):
    payload = {"model": "wan2.7-image-standard",
               "input": {"prompt": prompt,
                         "aspect_ratio": aspect_ratio,
                         "resolution": resolution}}
    if image_urls:                      # Referenzbildbearbeitung (siehe nächster Abschnitt)
        payload["input"]["image_urls"] = image_urls

    create = requests.post(API, headers=HEADERS, json=payload).json()
    if create.get("code") != 200:       # synchrone Validierungsfehler (z. B. ungültiger Enum-Wert)
        raise RuntimeError(create)
    task_id = create["data"]["taskId"]

    deadline = time.time() + timeout
    while time.time() < deadline:
        data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
        if data["status"] == "success":
            return requests.get(data["output"][0]["url"]).content
        if data["status"] == "fail":    # Endzustand Fehlgeschlagen – nicht weiter pollen
            raise RuntimeError(data.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...")   # Bytes sofort speichern – siehe Ablaufhinweis unten

aspect_ratio und resolution sind beide optional (das Modell hat Standardwerte), aber setze sie explizit – resolution akzeptiert nur 1K oder 2K, und beide kosten gleich viel, daher gibt es keinen Kostengrund, es beim Standardwert zu belassen.

Bearbeitung mit Referenzbildern: dieselbe Modell-ID, plus image_urls

Hier liegt der Unterschied zwischen der Standard- und der Pro-Stufe. Übergib Referenzbilder in image_urls (ein Array, laut Modellspezifikation bis zu 9 Referenzbilder), und das Modell bearbeitet oder komponiert sie neu, während es weiterhin deinen Text-Prompt befolgt:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-image-standard",
    "input": {
      "prompt": "Platziere dieses Produkt auf einer sonnigen Marmor-Küchenarbeitsplatte, daneben frische Kräuter, weiches Morgenlicht, Lifestyle-Produktfotografie",
      "image_urls": ["https://your-storage.example.com/product.jpg"],
      "resolution": "2K"
    }
  }'

In Python ist es der Parameter image_urls=[...], den du an die obige Hilfsfunktion übergibst – sonst ändert sich nichts. Auch bei Übergabe von Referenzbildern bleibt prompt erforderlich (die API lehnt Anfragen ohne prompt ab: missing required field "prompt").

Der Feldname ist wichtig: image_urls. Plausible Alternativnamen wie reference_image_urls, image_input oder input_urls werden vom Schema mit additional properties '<name>' not allowed abgelehnt. Wenn du Code von Bearbeitungs-Endpunkten anderer Modelle portierst, ist dies die erste Stelle, die du korrigieren musst.

Das exakte Eingabe-Schema

Das Schema ist strikt: Jedes Feld, das nicht in der folgenden Liste steht, führt zu 400 INVALID_REQUEST mit additional properties '<name>' not allowed. Dies sind alle Felder, die es akzeptiert:

Feld	Typ	Erforderlich	Beschreibung
prompt	string	Ja	Erforderlich für Text-zu-Bild und Bearbeitung. Englisch oder Chinesisch möglich.
aspect_ratio	string enum	Nein	Einer der Werte: 1:1, 16:9, 4:3, 21:9, 3:4, 9:16, 8:1, 1:8. Jeder andere Wert (z. B. 3:2) → 400.
resolution	string enum	Nein	Nur 1K oder 2K. 4K wird in dieser Stufe nicht unterstützt.
image_urls	string[]	Nein	Referenzbilder für die Bearbeitung (maximal 9). Übergabe schaltet in den Referenzmodus.
seed	integer	Nein	Für reproduzierbare Ausgaben.

Felder, die dir einfallen könnten, die dieses Modell aber nicht akzeptiert: negative_prompt, n, size und prompt_optimizer werden alle als unbekannte Eigenschaften abgelehnt. Es gibt keinen Batch-Parameter (n) – reiche eine Aufgabe pro Bild ein.

Produktionshinweise und gemessenes Verhalten

Ein 200 bei der Einreichung bedeutet nicht, dass das Bild garantiert generiert wird. wan2.7-image-standard validiert Enum-Werte synchron (ein falscher resolution- oder aspect_ratio-Wert lässt den POST sofort mit 400 INVALID_REQUEST fehlschlagen), aber es validiert Referenz-URLs nicht bei der Einreichung. Fehlerhafte oder nicht erreichbare image_urls-Einträge werden akzeptiert, es wird 200 und eine taskId zurückgegeben, und dann schlägt die Aufgabe etwa eine Sekunde später fehl. Ich habe dies direkt verifiziert: Eine mit ungültiger Referenz-URL erstellte Aufgabe gab folgenden Endzustand zurück:

{ "status": "fail", "error": { "code": "INVALID_REQUEST", "message": "invalid request parameters for this model" } }

Die praktische Konsequenz: Immer bis zum Endzustand pollen und den Zweig data.status == "fail" behandeln (lies data.error). Fehlgeschlagene Aufgaben werden als HTTP 200 mit data.status: "fail" gemeldet – die Fehlerinformationen stehen in data.error, nicht in einem HTTP-Fehler auf oberster Ebene. Stelle vor der Einreichung sicher, dass deine Referenz-URL öffentlich erreichbar ist.

Lade die Ausgabe sofort herunter. data.output[0].url ist ein temporärer Link mit einem expireAt-Zeitstempel, keine permanente CDN-Ressource. Hole die Bytes in dem Moment, in dem die Aufgabe erfolgreich ist, und übertrage sie in deinen eigenen Speicher; abgelaufene URLs liefern 404. Falls du bereits auf dieses Problem gestoßen bist, siehe warum deine hiapi-Ausgabe-URL 404 liefert und wie du damit umgehst.

Polling vs. Callback. Das obige Beispiel pollt alle fünf Sekunden, was für Skripte und kleine Mengen in Ordnung ist. Für Produktionsdurchsatz hänge callback an die Erstellungsanfrage an, damit hiapi dich bei Endzustandsereignissen benachrichtigt, statt dass du die Verbindung offen hältst – die genaue Mechanik findest du in der Dokumentation zur Aufgabenerstellung.

Standard vs. Pro: Welche Stufe du aufrufen solltest

hiapi hostet zwei Wan 2.7 Image-Stufen, die unterschiedliche Modell-IDs sind, keine Parameter:

• wan2.7-image-standard (dieser Leitfaden) – Text-zu-Bild und Referenzbildbearbeitung, 1K/2K, zu einem Festpreis von 0,0345 $ pro Bild, unabhängig von der Auflösung.
• wan2.7-image/text-to-image – Pro-Stufe: nur Text-zu-Bild, bis zu 4K, Festpreis 0,08 $ pro Bild. Siehe die Wan 2.7 Image Pro-Seite und die ausführliche Anleitung zur Erstellung von 4K-E-Commerce-Produktbildern damit.

Wähle die Standardstufe, wenn du referenzbildbasierte Bearbeitung benötigst oder 2K ausreicht und du weniger als die Hälfte des Pro-Preises pro Bild zahlen möchtest. Verwende Pro nur, wenn du speziell native 4K-Ausgabe benötigst – das ist das Einzige, was die Standardstufe nicht kann. Die aktuellen Preise beider Stufen findest du auf der Preisseite.

Häufige Fragen

Unterstützt wan2.7-image-standard Bildbearbeitung oder nur Text-zu-Bild? Beides, aus derselben Modell-ID. Füge das image_urls-Array hinzu, um zur referenzbildbasierten Bearbeitung zu wechseln; lasse es weg für reines Text-zu-Bild.

Was ist die maximale Auflösung? 2K. Das Feld resolution akzeptiert nur 1K und 2K; die Live-API lehnt jeden anderen Wert ab. Wenn du 4K benötigst, verwende die Pro-Stufe (wan2.7-image/text-to-image).

Warum hat meine Aufgabe 200 zurückgegeben und ist dann fehlgeschlagen? Referenz-URLs werden bei der Einreichung nicht geprüft – nur bei der Ausführung. Nicht erreichbare oder fehlerhafte image_urls-Einträge erstellen eine Aufgabe (HTTP 200) und schlagen dann mit dem Endzustand INVALID_REQUEST fehl. Polle data.status und verifiziere, dass deine URL öffentlich ist.

Kann ich einen negativen Prompt setzen? Nein. negative_prompt ist kein von diesem Modell akzeptiertes Feld (ebenso wenig n, size oder prompt_optimizer). Steuere über den positiven prompt und seed.