recraft-v4-styles/text-to-image API-Tutorial: curl, Python und asynchrones Polling

Was recraft-v4-styles/text-to-image für dich tun kann

recraft-v4-styles/text-to-image ist ein Endpoint zur Bilderzeugung mit Stilreferenz. Du gibst ihm einen Text-Prompt, der beschreibt, was du sehen möchtest, sowie ein oder mehrere Referenzbilder, die den visuellen Stil beschreiben. Das Modell verschmilzt beides: Der Prompt trägt Inhalt und Kompositionsabsicht, die Referenzbilder tragen den visuellen Stil.

Bei der Wahl des Endpoints ist dieser Unterschied wichtig. Wenn das Aussehen vollständig in Worten ausgedrückt werden kann – etwa „eine flache Vektorillustration einer Kaffeetasse, zweifarbig, kräftige Konturen“ –, dann ist die Bilderzeugung direkt aus dem Prompt das richtige Werkzeug. In der praktischen Produktarbeit betrifft jedoch die Mehrzahl der Szenarien ein Markenaussehen, das schwer zu beschreiben, aber leicht zu zeigen ist. Ein fertiges Key Visual, ein zuvor freigegebenes Rendering oder ein Design-System-Sample definiert die Stilspezifikation weit präziser als ein Absatz voller Adjektive. Genau diese Lücke füllt dieser Endpoint.

Aus Entwicklersicht lässt er sich als zweistufige Eingabe-Transformation betrachten: Prompt + Stilreferenz -> Bild. Alles, was die Integration betrifft, ergibt sich aus dieser Form. Du serialisierst nicht einfach einen String, sondern stellst eine kleine Payload aus mehreren Teilen zusammen, in der Referenzbilder Eingaben erster Klasse sind. Dein Code zur Request-Erstellung sollte sie entsprechend behandeln, und deine Validierungsschicht sollte Aufgaben ablehnen, die nur einen Prompt ohne brauchbare Stilreferenz enthalten, bevor sie deinen Service verlassen.

Der Endpoint ist asynchron. Das Absenden einer Anfrage liefert eine Aufgabe zurück, die du anschließend abfragst; das fertige Bild kommt schließlich als URL an, nicht als Inline-Bytes. Das ist eine bewusste Designentscheidung für Bild-Workloads: Die Generierung dauert lange genug, dass eine offen gehaltene HTTP-Verbindung sowohl verschwenderisch als auch fragil wäre. Sobald du den Lebenszyklus „Senden – Abfragen – Herunterladen“ akzeptiert hast, ist der Rest der Integration gewöhnliche API-Pipeline-Arbeit.

Anatomie einer funktionierenden Anfrage

Bevor du irgendwelchen Code schreibst, ordne die Felder in Gruppen. Eine Anfrage an recraft-v4-styles/text-to-image besteht aus drei logischen Teilen.

Der Prompt

Der Prompt ist deine Inhaltsanweisung. Formuliere ihn rund um das, was im Bild enthalten sein soll – Motiv, Komposition, Bildausschnitt, Anzahl der Objekte, Hintergrundbehandlung. Vermeide es, dein Prompt-Budget für Stiladjektive auszugeben, die die Referenzbilder bereits vermitteln; widersprüchliche Signale zwischen Prompt und Referenz führen oft zu unscharfen Ergebnissen. Halte den Prompt kurz, konkret und testbar.

Stilreferenz-Eingaben

Dies ist der Teil, der diesen Endpoint von einem gewöhnlichen Text-zu-Bild-Aufruf unterscheidet. Stilreferenzen sind Bilder, die zusammen mit dem Prompt übergeben werden und die visuelle Sprache definieren. Beim Zusammenstellen solltest du sie als kuratierte Sammlung behandeln, nicht als losen Haufen von Bildern:

• Konsistenz schlägt Quantität. Einige wenige Referenzbilder mit einem kohärenten Aussehen vermitteln dem Modell mehr als viele Referenzen mit unterschiedlichen Stilen.
• Auflösung und Bildausschnitt zählen. Referenzbilder sollten die gewünschte Ausgabe repräsentieren, keine Thumbnails oder stark beschnittenen Fragmente.
• Sie müssen erreichbar sein. Wenn du deine Referenzbilder als URL übergibst, müssen diese URLs zum Zeitpunkt der Anfrage öffentlich abrufbar sein. Ein signierter Link, der nach sechzig Sekunden abläuft, lässt langsame Aufgaben scheitern.

Bewahre deine Referenzbild-Sammlung in der Konfiguration auf, nicht verstreut im Code, damit du sie zusammen mit den Marken-Assets versionieren kannst.

Ausgabeoptionen

Die übrigen Felder beschreiben das Artefakt, das du zurückerhalten möchtest – Stellschrauben, die das zurückgegebene Bild beeinflussen, nicht dessen Inhalt. Die genauen Parameternamen und zulässigen Werte sind auf der Referenzseite dieses Endpoints aufgeführt; lies sie dort nach, anstatt zu raten, und bündele sie an einer Stelle im Code, sodass eine Spezifikationsänderung nur eine Datei betrifft.

Eine nützliche Gewohnheit: Baue den JSON-Body in deiner gewählten Sprache als Dictionary/Objekt auf, logge ihn beim ersten Lauf einmal auf Debug-Level und prüfe seine Struktur mit eigenen Augen, bevor du schlechte Ergebnisse dem Modell anlastest.

Aufruf mit curl

Beginne mit curl. Es entfernt alle Bibliotheksabstraktionen zwischen dir und dem Wire-Format, sodass du sofort siehst, wenn die Anfrage fehlerhaft ist.

Das Absenden ist eine POST-Anfrage mit JSON-Body und einem Authentifizierungsheader, der deinen HiAPI-API-Schlüssel trägt:

curl -sS -X POST "https://api.hiapi.ai/v1/recraft-v4-styles/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a ceramic coffee cup on a linen tablecloth, soft daylight",
    "style_references": [
      "https://your-cdn.example.com/style/ref-01.png"
    ]
  }'

Einige Hinweise zu dem, was du siehst:

• Bewahre den Schlüssel in einer Umgebungsvariable ($HIAPI_API_KEY) auf, niemals inline in der Shell-Historie oder in committeten Skripten.
• Die -d-Payload ist reines JSON. Die Quoting-Regeln der Shell sind eine häufige Fehlerquelle – wenn du Parse-Fehler bekommst, schreibe den Body in eine Datei und verwende -d @body.json.
• Die hier gezeigten Feldnamen folgen der Request-Anatomie aus dem vorigen Abschnitt; bestätige vor dem Release die genauen Namen und zulässigen Ausgabeoptionen auf der Referenzseite des Endpoints.

Die Antwort ist kein Bild. Sie ist eine Aufgabenbestätigung: eine Kennung für die gerade eingereihte Generierung und ein Statusfeld, das dir mitteilt, dass sie noch nicht abgeschlossen ist. Lies den Antwort-Body beim ersten Lauf sorgfältig und notiere den Feldnamen, der die Aufgaben-ID enthält – dieser String ist dein Handle für alles Weitere. Speichere ihn. Wenn deine erste Antwort ein Fehlerobjekt enthält, stoppe und korrigiere die Anfrage; das Pollen einer ID, die du nie erhalten hast, ist die häufigste Sackgasse.

Dieselbe Anfrage in Python umsetzen

Portiere den curl-Aufruf einmal nach Python, und du hast ein wiederverwendbares Primitiv. Das folgende Beispiel verwendet requests und spiegelt den Body exakt.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = "https://api.hiapi.ai/v1"

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

STYLE_REFERENCES = [
    "https://your-cdn.example.com/style/ref-01.png",
]

def submit_generation(prompt: str) -> dict:
    body = {
        "prompt": prompt,
        "style_references": STYLE_REFERENCES,
    }
    resp = requests.post(
        f"{BASE_URL}/recraft-v4-styles/text-to-image",
        headers=HEADERS,
        json=body,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()

if __name__ == "__main__":
    job = submit_generation(
        "a ceramic coffee cup on a linen tablecloth, soft daylight"
    )
    print(job)

Zwei Designentscheidungen solltest du beim Anpassen dieses Codes beibehalten:

• Immer ein Timeout setzen. Das Absenden sollte schnell zurückkehren; wenn es hängt, willst du eine Exception, keinen festgefahrenen Prozess.
• Das geparste JSON zurückgeben, nicht das Response-Objekt. Nachgelagerter Code sollte von der Aufgaben-Payload abhängen, nicht von den Interna von requests. Das macht den späteren Austausch der Transportschicht mühelos.

Definiere die Referenzbild-Sammlung wie oben gezeigt auf Modul- oder Konfigurationsebene. Wenn sich das Markenaussehen weiterentwickelt, aktualisierst du nur eine Liste, statt an den Aufrufstellen zu suchen. Und halte den Body-Aufbau in einer einzigen Funktion, sodass jedes vom Endpoint benötigte Feld nur an einer Stelle hinzugefügt werden muss.

Asynchrone Ergebnisse abfragen

Die Generierung ist asynchron, daher durchläuft deine abgesendete Aufgabe mehrere Zustände, bevor sie abgeschlossen ist. Dein Client braucht eine Warteschleife, die den Status prüft, zwischen den Prüfungen zurückhaltend wartet und schließlich aufgibt.

import time

def wait_for_result(job_id: str, timeout_s: int = 300, interval_s: float = 3.0) -> dict:
    deadline = time.monotonic() + timeout_s
    delay = interval_s
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE_URL}/recraft-v4-styles/text-to-image/{job_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(delay)
        delay = min(delay * 1.5, 15.0)
    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

In dieser Schleife ist wichtig:

• Unbekannte Zustände als ausstehend behandeln. Vergleiche mit expliziten Endzuständen, nicht mit einer Allowlist von In-Progress-Zuständen; falls die Plattform einen Zwischenzustand hinzufügt, wartet deine Schleife weiter, statt abzustürzen.
• Backoff. Fünf Minuten lang jede Sekunde fest zu pollen, sind fünf Minuten verschwendeter Anfragen. Beginne mit einem kleinen Intervall, multipliziere und setze eine Obergrenze.
• Wartezeit begrenzen. Jede Schleife braucht eine Deadline, und die Deadline sollte als Exception auftreten, die der Aufrufer behandeln kann.
• Nach Fehlern verzweigen. Ein terminaler Fehlerzustand trägt Diagnoseinformationen. Logge den vollständigen Antwort-Body – das ist der Unterschied zwischen „es ist kaputt“ und „die Referenz-URL hat 403 zurückgegeben“.

Wenn du viele Bilder verarbeitest, schlafe nicht im Web-Request-Handler. Sende die Aufgabe ab, persistiere die Aufgaben-ID und lasse einen Hintergrund-Worker oder einen geplanten Job das Polling vorantreiben. Die Referenzseite des Endpoints dokumentiert die genauen Statuswerte und den Polling-Pfad; prüfe sie bei jedem Client-Upgrade.

Ausgaben herunterladen und speichern

Wenn die Aufgabe einen erfolgreichen Endzustand erreicht, enthält die Antwort die URL des generierten Bildes. Diese URL ist der Übergabepunkt zwischen der API und deiner Speicherschicht.

Rufe sie als Bytes ab und schreibe sie dorthin, wo du sie brauchst:

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

Für alles jenseits lokaler Experimente solltest du das Artefakt nicht einfach an der zurückgegebenen URL belassen. Behandle das generierte Bild als temporären Zeiger und kopiere es in einen Speicher, den du kontrollierst – einen Object-Storage-Bucket, deinen CDN-Origin oder eine Media-Pipeline. Drei Gründe:

1. Lebenszyklus. Generierte Ausgabe-URLs sind nicht unbegrenzt haltbar. Ein erneuter Download von einer veralteten URL während eines Retries ist ein potenzielles stilles Scheitern.
2. Stabile Schlüssel. Deine Anwendung braucht einen deterministischen Identifikator, den sie in eine Datenbankzeile schreiben kann, nicht eine URL, die sich bei jeder Neugenerierung ändert.
3. Provenienz. Prompt, Version der Stilreferenz-Sammlung und Aufgaben-ID zusammen mit dem Bild zu speichern, ermöglicht es dir, jedes Asset später zu reproduzieren oder zu auditieren. Bewahre diese Metadaten in einer Begleitaufzeichnung oder Datenbankspalte auf.

Beim Upload in Object Storage streame den Antwort-Body, statt große Bilder vollständig im Speicher zu puffern, und setze den Inhaltstyp aus den Antwort-Headern. Wenn du das Bild über dein eigenes CDN an Clients auslieferst, ist dieser Schritt auch der Ort, um Cache-Header anzuwenden.

Fehlerbehebung beim ersten Lauf

Die meisten ersten Versuche scheitern auf einige vorhersehbare Weisen. Prüfe diese der Reihe nach.

Der Request-Body wird abgelehnt

Fehler der 400er-Klasse bedeuten meist fehlerhaftes JSON oder ein fehlendes Pflichtfeld. Führe zuerst die curl-Version aus und prüfe den exakten Body, den du sendest. Häufige Probleme: Shell-Quoting, das das JSON zerstört; ein Feld, das die API als Array erwartet, aber als String gesendet wird; oder ein Wert einer Ausgabeoption außerhalb des zulässigen Bereichs. Die Referenzseite des Endpoints ist die maßgebliche Quelle für Feldnamen und Werte – vergleiche deinen Body wörtlich damit.

Du hast einen Prompt, aber keine brauchbare Stilreferenz

Der Endpoint ist um Stilreferenzen herum aufgebaut. Wenn deine Anfrage einen Prompt enthält, aber die Referenzbilder leer, nicht erreichbar sind oder beim Abruf einen Authentifizierungsfehler zurückgeben, wird die Aufgabe entweder abgelehnt oder eine Ausgabe erzeugt, die dein beabsichtigtes Aussehen ignoriert. Verifiziere jede Referenz-URL, indem du sie mit demselben unauthentifizierten Client abrufst, den die Plattform verwenden würde. Referenzbilder, die ein Session-Cookie oder einen signierten Query-String benötigen, gelten als defekt.

Du erhältst nie eine Aufgaben-ID

Die Absendeantwort ist eine Bestätigung, kein Bild. Wenn du Code schreibst, der Bild-Bytes bereits in der ersten Antwort erwartet, wird er bei jedem Lauf scheitern. Parse die Antwort, extrahiere die Aufgaben-ID und beginne erst dann zu pollen. Logge bei den ersten Läufen die vollständige Absendeantwort, damit du ihre Form siehst.

Du pollst zu häufig

Hunderte Statusprüfungen pro Minute lassen die Aufgabe nicht schneller fertig werden, sondern lösen eher Rate-Limits aus. Verwende ansteigende Intervalle mit Obergrenze und einen einzelnen Worker pro Aufgabe. Wenn du viele Aufgaben verteilst, füge ein kleines Nebenläufigkeitslimit hinzu, damit ein Sendeschwall nicht zu einem Polling-Schwall wird.

Die Aufgabe ist fertig, aber der Download schlägt fehl

Ein 403 oder 404 beim Abrufen der Ausgabe-URL bedeutet meist, dass die URL abgelaufen ist oder die Aufgabe nach einer falsch gelesenen Statusprüfung fehlgeschlagen ist. Bestätige, dass der Endzustand Erfolg ist, und lies die Antwort erneut, um das tatsächliche Ausgabefeld zu erhalten. Speichere das Artefakt sofort, sobald es verfügbar ist, statt den Download aufzuschieben.

Löse diese Probleme in der Reihenfolge, in der die Pipeline läuft – Senden, Abfragen, Herunterladen –, und Fehler beim ersten Lauf lösen sich fast immer in offensichtliche Korrekturen auf. Die Endpoint-Referenz und ihre Request-Schemata sind der schnellste Weg, feldbezogene Fragen zu klären.