So rufen Sie seedream-5.0-lite/text-to-image über die HiAPI API auf: curl- und Python-Leitfaden

Was diese Integration tatsächlich tut

Einen Text-zu-Bild-Aufruf auf HiAPI auszulösen, ist ein kurzes Gespräch zwischen Ihrem Code und einer asynchronen Aufgabenwarteschlange. Sie senden eine Anfrage, die das gewünschte Bild beschreibt; die Plattform validiert die Anfrage, nimmt die Aufgabe an und gibt einen Bezeichner zurück. Das Bild ist nicht in der ersten Antwort enthalten – es wird danach erzeugt. Anschließend überwacht Ihr Code die Aufgabe, bis sie den Abschluss meldet, und lädt schließlich das Bild von der von der Aufgabe bereitgestellten URL herunter.

Diese Form ist wichtig, weil sie bestimmt, wie Sie die Integration schreiben. Es gibt drei unterschiedliche Momente: Übermittlung, Polling und Abruf. Jeder hat seine eigenen Fehlermodi. Die Übermittlung schlägt fehl, wenn die Nutzlast fehlerhaft formatiert ist oder der Modellpfad ungültig ist. Das Polling schlägt fehl, wenn die Schleife falsch geschrieben ist – zu schnell, zu kurz oder unfähig, zwischen „läuft noch“ und „abgeschlossen“ zu unterscheiden. Der Abruf schlägt fehl, wenn Sie die Ausgabe-URL als permanente Adresse behandeln oder vergessen, die Bytes auf die Festplatte zu schreiben.

Im Kern ist seedream-5.0-lite/text-to-image ein universelles Text-zu-Bild-Modell auf der HiAPI-Plattform. Sie rufen es über diesen exakten Modellbezeichner auf. Die von Ihnen gesendeten Parameter sind die üblichen Parameter für solche Aufrufe: Modellname, Prompt sowie alle in der Endpunkt-Dokumentation beschriebenen Steuerungsparameter für Ausgabegröße oder -anzahl. Sie benötigen kein spezielles SDK; ein gewöhnlicher HTTPS-Client reicht aus.

Nach diesem Walkthrough verfügen Sie über eine Anfrage, die Sie mit curl reproduzieren können, eine Python-Funktion darum herum, einen Trick zur Formulierung von Prompts, damit gerenderter Text klar lesbar ist, und eine Polling-Schleife, die tatsächlich beendet wird. Alles läuft über denselben HiAPI-Endpunkt, sodass nach einem erfolgreichen Aufruf nur noch die Parameterabstimmung bleibt.

Die Anfrage mit curl erstellen

Beginnen Sie in der Kommandozeile. Ein lauffähiger curl-Aufruf ist die Referenz für die Nutzlast – sobald er funktioniert, ist jede andere Sprache nur eine Übersetzungsübung.

Vor dem ersten Aufruf benötigen Sie zwei Dinge: Ihren HiAPI-API-Schlüssel und die Basis-URL der API. Der Schlüssel wird als Bearer-Token im Authorization-Header übergeben. Halten Sie ihn möglichst aus Ihrer Shell-Historie heraus; Umgebungsvariablen sind die einfachste Gewohnheit.

export HIAPI_API_KEY="your_api_key_here"

Die Anfrage selbst ist ein POST mit JSON-Body. Der Modellbezeichner ist das Pfadsegment, das Sie aufrufen, und der Prompt beschreibt das Bild:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-lite/text-to-image",
    "prompt": "A minimalist poster for a coffee shop called North Roast, warm cream background, bold dark lettering"
  }'

Setzen Sie HIAPI_BASE_URL auf den Text-zu-Bild-Übermittlungsendpunkt, der in der Plattformdokumentation angezeigt wird; der Pfad variiert je nach Produktoberfläche, also kopieren Sie ihn, statt zu raten.

Lesen Sie die Antwort, bevor Sie weiteren Code schreiben. Eine erfolgreiche Übermittlung gibt ein JSON-Objekt mit einem Aufgabenbezeichner und einem Statusfeld zurück. Der Status zeigt normalerweise an, dass die Aufgabe in der Warteschlange steht oder in Bearbeitung ist – noch nicht abgeschlossen. Das ist erwartetes Verhalten. Notieren Sie sich die genauen Feldnamen, die zurückgegeben werden; Sie werden sie in den nächsten beiden Abschnitten referenzieren.

Zwei Fehler auf curl-Ebene verursachen die meisten ersten Fehlschläge. Der erste ist ein fehlender oder falsch berechtigter Schlüssel: Die Antwort ist ein Authentifizierungsfehler, kein Modellfehler. Der zweite ist ein fehlerhaft formatierter Body – nicht maskierte Anführungszeichen im Prompt, ein abschließendes Komma, einfache Anführungszeichen, wo JSON doppelte erfordert. Wenn die Plattform die Nutzlast ablehnt, formatieren Sie sie mit jq hübsch und validieren Sie sie separat, bevor Sie das Modell beschuldigen.

Wenn die Übermittlung einen Bezeichner zurückgibt, haben Sie eine gültige Anfrage. Alles danach ist Warten und Abrufen.

Portierung nach Python

Die Python-Version sollte eine kleine, wiederverwendbare Funktion sein – kein Skript mit einem fest einprogrammierten Prompt. Verwenden Sie requests (oder httpx, wenn Sie das bevorzugen); der Aufruf selbst benötigt keinen speziellen Client.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_image(prompt: str, **params) -> dict:
    payload = {
        "model": "seedream-5.0-lite/text-to-image",
        "prompt": prompt,
        **params,
    }
    response = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=30)
    response.raise_for_status()
    return response.json()

Hier gibt es drei bewusste Entscheidungen. Schlüssel und Basis-URL kommen aus der Umgebung, sodass die Funktion sicher eingecheckt werden kann. Der Catch-all-Parameter **params ermöglicht es Ihnen, Ausgabegröße oder andere dokumentierte Optionen zu übergeben, ohne die Funktion zu bearbeiten. Und raise_for_status() wandelt HTTP-Fehler sofort in Ausnahmen um, was genau das ist, was Sie wollen – ein 4xx bei der Übermittlung wird nie eine gültige Aufgabe, daher ist schnelles Scheitern besser als die Prüfung eines verwirrenden Antwortbodys.

Das zurückgegebene Dictionary ist Ihr Aufgabendatensatz. Drucken Sie ihn während der Entwicklung einmal aus, um die genauen Schlüsselnamen für Bezeichner und Status zu kennen. Indexieren Sie ihn nicht blind; ein kleiner Accessor hält den restlichen Code lesbar:

job = submit_image("A flat illustration of a paper plane over a city map")
print(job)

Wenn es eine in die Warteschlange gestellte Aufgabe ausgibt, ist die Portierung von curl korrekt. Wenn es eine Ausnahme auslöst, sagt Ihnen die Meldung von raise_for_status(), ob Sie auf ein Authentifizierungs- oder ein Nutzlastproblem gestoßen sind – dieselben zwei Kategorien von Problemen, die Sie in der Shell antreffen würden.

Prompts für Weltwissen und gerenderten Text schreiben

Text-zu-Bild-Modelle sind am stärksten, wenn der Prompt beschreibt, was sichtbar sein soll, und am schwächsten, wenn er Wissen andeutet, das das Modell ableiten muss. seedream-5.0-lite/text-to-image kann allgemeinen Weltkontext nutzen – erkennbare Objekte, gängige Designkonventionen, Typografie-Stile – aber Sie müssen ihm trotzdem genug Inhalt geben, um diesen Kontext zu verankern.

Beschreiben Sie bei Szenen-Prompts das Motiv, die Komposition und den visuellen Stil. 'A cozy reading nook by a window, soft afternoon light, three-quarter view, muted earth tones' sagt dem Modell sowohl, was es zeichnen soll, als auch, wie es stilisiert werden soll. Vage Prompts erzeugen durchschnittliche Bilder; konkrete Prompts erzeugen brauchbare Bilder.

Gerenderter Text ist der Bereich, in dem Prompts üblicherweise scheitern. Wenn Sie Text im Bild benötigen, befolgen Sie einige Regeln:

• Zitieren Sie die exakte Zeichenkette. Schreiben Sie den gewünschten Text in Anführungszeichen, damit er eindeutig wörtlich ist und nicht beschreibend.
• Halten Sie ihn kurz. Kurze Überschriften oder Markennamen lassen sich zuverlässig rendern; Absätze nicht.
• Geben Sie Position und Stil an. 'The word "North" centered at the top in a bold sans-serif' ist besser als 'some text at the top'.
• Vermeiden Sie konkurrierenden Text. Mehrere unterschiedliche Textelemente in einem Bild führen leicht zu Kauderwelsch. Wenn Sie mehrere benötigen, halten Sie sie kurz und weit voneinander entfernt.
• Iterieren Sie jeweils nur eine Variable. Ändern Sie die Formulierung, nicht gleichzeitig Formulierung, Layout und Stil, sonst erfahren Sie nicht, was das Problem gelöst hat.

Benennen Sie alles, was erkennbaren Kontext betrifft – Produktkategorie, Postertyp, Schildertyp – ausdrücklich. Das Vorwissen des Modells ist am nützlichsten, wenn der Prompt ihm einen Anknüpfungspunkt gibt. 'A vintage travel poster for a coastal town' trägt mehr nutzbaren Kontext als 'a poster'.

Erfinden Sie keine Parameter. Wenn der Prompt nicht die gewünschte Textplatzierung erzeugt, justieren Sie zuerst die Formulierung des Prompts selbst und probieren Sie erst dann Optionen aus, die Sie nicht dokumentiert gesehen haben.

Asynchrone Aufgaben behandeln und die Ausgabe herunterladen

Polling ist der Ort, an dem die Integration still schiefgeht. Die Aufgabe ist asynchron, daher benötigen Sie eine Schleife, die den Status prüft, zwischen den Prüfungen wartet, schließlich aufgibt und genau weiß, welche Statuswerte „abgeschlossen“ bedeuten.

import time

def wait_for_job(job_id: str, poll_interval: float = 3.0, timeout: float = 180.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/{job_id}", headers=HEADERS, timeout=30
        )
        response.raise_for_status()
        job = response.json()

        status = job.get("status")
        if status in {"succeeded", "completed"}:
            return job
        if status in {"failed", "error", "cancelled"}:
            raise RuntimeError(f"Job {job_id} ended with status {status}")

        time.sleep(poll_interval)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

Passen Sie den Polling-Pfad und die Statusstrings an das an, was die Plattformdokumentation zeigt – diese beiden Details weichen am wahrscheinlichsten von der obigen Skizze ab. Die Struktur ist entscheidend: eine monotone Frist, ein Sleep zwischen den Prüfungen, explizite Erfolgs- und Fehlermengen und ein Timeout, der eine Ausnahme auslöst, statt eine halbfertige Aufgabe zurückzugeben.

Sobald die Aufgabe Erfolg meldet, enthält die Antwort die URL der Ausgabe. Behandeln Sie diese URL als temporär. Laden Sie die Bytes sofort herunter, statt den Link zu speichern:

def download_image(url: str, path: str) -> None:
    response = requests.get(url, timeout=60)
    response.raise_for_status()
    with open(path, "wb") as f:
        f.write(response.content)

job = wait_for_job(job_id)
download_image(job["output"]["url"], "out.png")

Bevor Sie weitermachen, vergewissern Sie sich, dass die Datei ein echtes Bild ist – öffnen Sie sie, prüfen Sie die Abmessungen oder prüfen Sie zumindest, ob die Byte-Länge ungewöhnlich klein ist. Wenn der Server ordnungsgemäß schließt, erscheint ein abgeschnittener Download für requests wie ein Erfolg.

Häufige Fehler und wie man sie behebt

Die meisten Fehlschläge bei ersten Integrationen fallen in vier Kategorien. Gehen Sie sie der Reihe nach an.

Übermittlung abgelehnt

Wenn der erste Aufruf ein 4xx zurückgibt, drucken Sie den Antwortbody. Ein Authentifizierungsfehler bedeutet, dass der Schlüssel fehlt, abgelaufen ist oder nicht als Bearer-Token gesendet wurde. Ein Schemafehler bedeutet, dass die Nutzlast fehlerhaft formatiert ist – falsches Modellfeld, fehlender Prompt oder falsch geschriebener dokumentierter Parameter. Validieren Sie das JSON separat und vergleichen Sie es mit dem lauffähigen curl-Beispiel.

Aufgabe wird nie fertig

Die Schleife dreht sich endlos oder läuft in ein Timeout. Prüfen Sie zuerst das Polling-Intervall: Wenn Sie den Endpunkt ohne Sleep hämmern, können Sie Ratenbegrenzungen auslösen, die eine gesunde Aufgabe blockiert erscheinen lassen. Prüfen Sie dann Ihren Statusvergleich – wenn die Plattform success zurückgibt und Sie auf succeeded prüfen, sieht jede Aufgabe unvollendet aus. Protokollieren Sie einmal den rohen Statuswert, statt zu raten.

Ausgabe-URL gibt 404 oder 403 zurück

Die Ausgabe-URL ist signiert und zeitlich begrenzt. Wenn Sie lange gepollt haben und erst dann abrufen, kann der Link abgelaufen sein. Rufen Sie ihn direkt nach Abschluss ab, und wenn Sie das Ergebnis behalten müssen, speichern Sie die Datei statt des Links.

Bild wird gerendert, aber Text ist Kauderwelsch

Das ist ein Prompt-Problem, kein Code-Problem. Verkürzen Sie den Text, zitieren Sie ihn exakt, reduzieren Sie die Anzahl der Textelemente und machen Sie die Stilangaben expliziter. Führen Sie den Lauf mit jeweils nur einer Änderung erneut aus, damit Sie wissen, welche Anpassung geholfen hat.

Anfrage hängt oder läuft in ein Timeout

Setzen Sie immer explizite Timeouts bei Übermittlungs- und Polling-Aufrufen. Anfragen ohne Timeout können Arbeitsprozesse unbegrenzt blockieren, und eine Polling-Schleife ohne Frist verwandelt eine vorübergehende Unterbrechung in einen hängenden Prozess.

Wenn unerwartetes Verhalten auftritt, reduzieren Sie es auf den minimalen curl-Aufruf, der noch fehlschlägt. Wenn die rohe HTTP-Anfrage sich seltsam verhält, ist die Python-Schicht nicht das Problem – sobald curl wieder funktioniert, ist die Portierung zurück nach Python mechanisch. Die Modellseite von seedream-5.0-lite/text-to-image listet die aktuellen Parameter und die Antwortform auf, also schauen Sie dort nach, bevor Sie Feldnamen annehmen.