So rufen Sie recraft-v4-styles-pro/text-to-image auf der hiapi API auf: curl und Python

Was dieser Endpunkt tut und wann Sie ihn verwenden

recraft-v4-styles-pro/text-to-image wandelt Text-Prompts in Bilder um, wobei die Besonderheit in der Stilbewusstheit liegt: Sie können die visuelle Sprache des Ergebnisses über Stilreferenzen lenken, statt sich allein auf die Formulierung des Prompts zu verlassen. Wenn die Ausgabe über viele Generierungen hinweg ein konsistentes Gefühl vermitteln soll und nicht nur bei ein oder zwei Generierungen gut aussehen muss, ist dies eine praktische Wahl.

Entwickler setzen es häufig in folgenden Szenarien ein:

• Markenkonsistente Assets – Key Visuals, Social Cards und Werbevarianten, die alle in dasselbe visuelle System fallen müssen.
• Produkt- und Marketing-Mockups – Prompts wiederholt anpassen, den Stil fixieren und eine markenkonforme Variantenserie erzeugen.
• Pipeline-Schritte – Generierung als eine Phase in einer größeren Automatisierung, bei der ein anderer Dienst die gespeicherten Bilder konsumiert.

Eine Eigenschaft bestimmt, wie jedes Codebeispiel unten geschrieben wird: Die Bildgenerierung ist asynchron. Die Anfrage übermittelt einen Auftrag und kehrt sofort zurück; das Bild erscheint erst später. Sie müssen einen Übermittlungsschritt und einen Abfrageschritt schreiben und diese als zwei getrennte Belange behandeln.

hiapi-Anmeldedaten und Anfragegrundlage vorbereiten

Alle Aufrufe laufen über die einheitliche Endpunkt-Oberfläche von hiapi, daher sind vor der ersten Anfrage drei Dinge vorzubereiten:

1. Ein API-Schlüssel aus Ihrem hiapi-Konto. Behandeln Sie ihn wie jedes andere Geheimnis: aus Umgebungsvariablen laden und niemals in ein Skript hartkodieren, das Sie möglicherweise weitergeben.
2. Die Modellkennung, die exakt mit der Veröffentlichung übereinstimmen muss: recraft-v4-styles-pro/text-to-image.
3. Ein HTTP-fähiges Werkzeug – curl zum Erkunden und eine HTTP-Bibliothek für jede dauerhafte Nutzung.

export HIAPI_API_KEY="your-key-here"

Konventionen, die es sich lohnt, sich früh einzuprägen:

• Verwenden Sie Content-Type: application/json, wenn Sie einen JSON-Anfragekörper senden.
• Authentifizieren Sie sich mit einem Bearer-Token-Header.
• Halten Sie Modell-ID, Prompt und Stilreferenzen als jeweils eigene Felder in der Nutzlast, statt alles in einen einzigen String zu packen – so bleiben Abfrageschritt und Logs leichter verständlich.

Zu den genauen Header-Namen, der Basis-URL und den aktuellen Felddefinitionen konsultieren Sie die hiapi-API-Referenzdokumentation dieses Modells; betrachten Sie dieses Tutorial als die Form des Aufrufs und die Referenzdokumentation als die maßgebliche Quelle für die Namen.

Eine funktionierende curl-Anfrage

Hier ist der Übermittlungsaufruf. Verstehen Sie ihn als drei Ebenen: Transport, Authentifizierung und Anfragekörper.

curl -sS -X POST "$HIAPI_BASE_URL/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "recraft-v4-styles-pro/text-to-image",
    "prompt": "minimalist product photo of a ceramic mug on a linen surface, soft daylight",
    "style_references": []
  }'

Zeile für Zeile erklärt:

• -X POST – übermittelt einen Auftrag, ruft nichts ab.
• Authorization: Bearer ... – das Token stammt aus einer Umgebungsvariablen, daher kann der Befehl sicher in ein Terminal eingefügt und ohne die Variable auch sicher weitergegeben werden.
• -d '{...}' – der JSON-Anfragekörper. model ist die exakte Kennung. prompt ist der Freitext, der die Szene beschreibt. style_references ist der Anknüpfungspunkt für die Stilsteuerung, der als Nächstes besprochen wird.
• -sS – stiller Fortschrittsbalken, aber Fehler werden weiterhin angezeigt, sodass fehlgeschlagene Aufrufe sichtbar bleiben.

Eine erfolgreiche Antwort ist eine Bestätigung, kein Bild: Sie erhalten die Kennung des Auftrags und einen Status. Notieren Sie sich diese Kennung – sie ist das einzige Handle, das für die Abfrage benötigt wird. Wenn Sie interaktiv erkunden, formatieren Sie die Antwort mit einem JSON-Formatierer, damit Auftrags-ID und Status deutlicher hervortreten.

Stilreferenzen zusammen mit dem Prompt übergeben

Das mentale Modell ist einfach: Der Prompt sagt was, die Stilreferenzen sagen wie es aussehen soll. Halten Sie sie in der Nutzlast getrennt, dann bleibt Ihre Flexibilität erhalten – Sie können denselben Prompt gegen mehrere Stilsätze erneut ausführen, um Ergebnisse zu vergleichen.

{
  "model": "recraft-v4-styles-pro/text-to-image",
  "prompt": "ceramic mug on a linen surface, soft daylight",
  "style_references": [
    "https://your-bucket.example.com/styles/mug-ref-01.jpg",
    "https://your-bucket.example.com/styles/mug-ref-02.jpg"
  ]
}

Praktische Empfehlungen:

• Starten Sie ohne Referenzen. Führen Sie den Prompt zuerst nackt aus. Fügen Sie dann eine Referenz hinzu und beobachten Sie den Unterschied, dann zwei. Eine Änderung pro Schritt liefert weit mehr Erkenntnisse als der erste Versuch mit einem kompletten Stilsatz.
• Halten Sie Referenzen erreichbar. Hosten Sie sie dort, wo der Dienst sie zuverlässig abrufen kann – ein öffentlicher Bucket oder eine signierte URL mit reichlich Gültigkeitsdauer – und nicht unter einem Link, der nach wenigen Minuten abläuft.
• Halten Sie das Set kohärent. Miteinander konsistente Referenzen (ähnliche Beleuchtung, Farbpalette, Textur) erzeugen tendenziell stabilere Ergebnisse als ein heterogener Haufen, bei dem das Modell Widersprüche ausgleichen muss.
• Versionieren Sie Referenzen. Speichern Sie sie unter stabilen Schlüsseln. Wenn die Ausgabe nächsten Monat Probleme macht, müssen Sie genau wissen, welche Referenzdateien damals verwendet wurden.

Konsultieren Sie die hiapi-Referenzdokumentation dieses Modells, um zu bestätigen, ob Stilreferenzen als URLs, hochgeladene Assets oder benannte Presets übergeben werden und welche Einschränkungen für Anzahl und Format gelten.

Derselbe Aufruf in Python

Der curl-Aufruf lässt sich direkt übertragen. In kleine Funktionen gekapselt, ist er als Pipeline-Phase wiederverwendbar.

import os
import requests

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


def submit_generation(prompt: str, style_references: list[str] | None = None) -> str:
    """Übermittelt einen Text-zu-Bild-Auftrag und gibt die Auftrags-ID zurück."""
    payload = {
        "model": "recraft-v4-styles-pro/text-to-image",
        "prompt": prompt,
        "style_references": style_references or [],
    }
    response = requests.post(
        f"{HIAPI_BASE_URL}/generate",
        headers={
            "Authorization": f"Bearer {HIAPI_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()
    return data["job_id"]

Hinweise zum Design:

• Setzen Sie immer ein Timeout. Eine unbegrenzt hängende Übermittlung blockiert Ihren Worker-Prozess ähnlich effektiv wie ein Absturz.
• raise_for_status() verwandelt Nicht-2xx-Antworten in Ausnahmen, die abgefangen und protokolliert werden können, statt mit einem fehlerhaften Antwortkörper stillschweigend weiterzumachen.
• Geben Sie nur die ID zurück. Die Auftrags-ID ist der Vertrag zwischen Übermittlung und Abfrage. Wenn Sie den Rest der Antwort aus dem aufrufenden Code heraushalten, wird der nächste Abschnitt leichter zu schreiben.

Bestätigen Sie in der hiapi-Referenzdokumentation den tatsächlichen Feldnamen der Antwort und passen Sie data["job_id"] entsprechend an – die Feldbenennung ist der Punkt, an dem die Beispiele dieses Artikels am wahrscheinlichsten abweichen.

Den Auftragsstatus abfragen

Die Generierung braucht Zeit. Fragen Sie in festen Intervallen ab, stoppen Sie bei einem Endzustand und geben Sie schließlich auf.

import time


def wait_for_job(job_id: str, timeout: float = 300, interval: float = 3) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        response = requests.get(
            f"{HIAPI_BASE_URL}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {HIAPI_API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        job = response.json()

        status = job["status"]
        if status == "succeeded":
            return job
        if status == "failed":
            raise RuntimeError(f"Job {job_id} failed: {job.get('error')}")

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

Die weniger offensichtlichen Teile:

• Drei Ergebnisse, nicht zwei. Ausstehend, erfolgreich, fehlgeschlagen. Behandeln Sie jeden nicht erkannten Status als ausstehend und protokollieren Sie eine Zeile, damit ein neu hinzugefügter Status den Worker nicht zum Absturz bringt.
• Eine Deadline für die gesamte Wartezeit. Eine time.monotonic()-Deadline ist von Uhrzeitanpassungen unbeeinflusst, Wanduhr-Arithmetik dagegen nicht.
• Nicht zu häufig anfragen. Bei der Bildgenerierung sind einige Sekunden zwischen den Prüfungen ausreichend. Wenn Sie schneller abfragen müssen, sollten Sie zwischen den Versuchen Backoff einsetzen, statt das Intervall zu verkürzen.
• Erzwingen Sie ein Timeout. Ein nie endender Auftrag sollte sich als alarmierbarer Fehler zeigen, nicht als Schleife, die läuft, bis der Container getötet wird.

Wenn Sie viele Aufträge ausführen, übermitteln Sie sie im Batch und fragen Sie parallel ab – mit einer Event-Loop oder einem Thread-Pool und versetzten Intervallen – statt für jeden Auftrag in einer engen Schleife einen Abfrager zu starten.

Ausgabe herunterladen und speichern

Ein abgeschlossener Auftrag liefert Ihnen eine Bildreferenz, üblicherweise eine URL. Laden Sie diese zeitnah herunter, denn solche Links können zeitlich begrenzt sein.

def save_image(job: dict, path: str) -> None:
    url = job["output"]["image_url"]
    for attempt in range(3):
        try:
            with requests.get(url, stream=True, timeout=60) as r:
                r.raise_for_status()
                with open(path, "wb") as f:
                    for chunk in r.iter_content(chunk_size=8192):
                        f.write(chunk)
            return
        except requests.RequestException:
            if attempt == 2:
                raise
            time.sleep(2 ** attempt)

Praktiken, die sich in der Produktion lohnen:

• Streaming-Download. Generierte Bilder sind nicht klein; sie ohne Grund vollständig in den Speicher zu laden, ist Verschwendung.
• In einen temporären Pfad schreiben, dann umbenennen. Ein Absturz mitten im Schreiben sollte keine abgeschnittene Datei an der Stelle hinterlassen, an der die Pipeline ein gültiges Bild erwartet.
• Downloads wiederholen, nicht die Generierung. Ein erneuter Versuch bei einem instabilen Bucket-Abruf ist günstig; eine verschwendete Generierung nicht. Begrenzen Sie die Wiederholungsversuche und verwenden Sie exponentielles Backoff.
• Die Auftrags-ID zusammen mit der Datei persistieren. Wenn jemand fragt, woher ein Bild stammt, sollte die Antwort eine einzige Abfrage erfordern und nicht das Durchwühlen von Logs.

Für Objektspeicher ersetzen Sie open() durch den Streaming-Upload Ihres SDK und behalten dieselbe Wiederholungshülle bei.

Fehler, Wiederholungen und Kostenplausibilitätsprüfung

Die Fehlermodi, auf die Sie zuerst stoßen werden, und der Umgang mit jedem:

• 401 / Authentifizierungsfehler – Schlüssel fehlt, ist falsch geschrieben oder wurde nicht in die Shell exportiert, die das Skript ausführt. Prüfen Sie die Umgebung, bevor Sie die Nutzlast anfassen.
• 4xx-Validierungsfehler – meist ein Tippfehler in der Modell-ID, ein fehlender prompt oder eine fehlerhafte Stilreferenz. Protokollieren Sie den Antwortkörper wörtlich; Validierungsmeldungen sind hier der schnellste Weg zur Behebung.
• 429 / Rate-Limit – verwenden Sie Backoff mit Jitter statt sofortiger Wiederholung. Eine Warteschlange vor der Übermittlungsfunktion ist besser als ein Wiederholungssturm.
• Auftrags-Timeout – die Abfrage-Deadline wurde ausgelöst. Entscheiden Sie bewusst, ob Sie neu übermitteln; blindes Neuübermitteln verdoppelt die Ausgaben, ohne die Erfolgsrate zu erhöhen.
• Vorübergehende Netzwerkfehler – wiederholen Sie Übermittlung und Download mit begrenztem exponentiellem Backoff. Wiederholen Sie Download-Fehler großzügig; Generierungen vorsichtig.

Kostendisziplin, praktisch gesprochen:

• Die Abrechnung folgt der tatsächlich vom Modell ausgeführten Arbeit, daher sind fehlgeschlagene Aufträge und aufgegebene Batches versteckte Kosten. Protokollieren Sie jede Übermittlung mit Prompt-Hash und Auftrags-ID, um die Nutzung später abzurechnen.
• Iterieren Sie mit möglichst günstigen Prompts. Justieren Sie Formulierung und Stilreferenzen in kleinen, schnellen Läufen, bevor Sie große Batches investieren.
• Deduplizieren. Wenn derselbe Prompt und dasselbe Stil-Set zweimal angefordert werden, liefern Sie das Ergebnis des ersten Laufs aus Ihrem eigenen Cache.
• Fügen Sie im Worker-Prozess ein hartes Parallelitätslimit hinzu. Ein Limit zu erhöhen ist einfacher, als eine unerwartete Rechnung zu erklären.

Wenn Sie Übermittlung, Abfrage und Speichern als drei eigenständige, testbare Funktionen behandeln, lässt sich dieser Endpunkt sauber in jede Pipeline einbetten. Zu den genauen Feldnamen, Status und aktuellen Preisen sehen Sie vor der Integration auf der Modellseite von recraft-v4-styles-pro/text-to-image auf hiapi nach.