So verwendest du recraft-v4.1/text-to-image über die HiAPI-API: curl- und Python-Leitfaden

Was dieser Endpunkt dir bietet

recraft-v4.1/text-to-image ist ein Text-zu-Bild-Modell-Endpunkt: Du sendest im Request-Body einen Text-Prompt sowie einige Formgebungsoptionen und erhältst die generierten Bilddaten. Er eignet sich besonders, wenn du mit einem einzigen Aufruf ein fertiges Bild erzeugen möchtest, ohne selbst eine mehrstufige Pipeline zu orchestrieren.

Auf HiAPI ist das Modell in den Aggregationsmodus eingebunden: eine Basis-URL, ein Authentifizierungs-Header und eine über Endpunkte hinweg konsistente Request-/Response-Struktur. Du musst nicht für jedes Bildmodell, das du evaluieren möchtest, separat SDK und Anmeldedaten anbinden – du richtest deinen Client einfach auf den Endpunkt von recraft-v4.1/text-to-image auf HiAPI, und der restliche Code bleibt stabil. Das ist besonders in der Prototyping-Phase wichtig – du möchtest Prompts, Stile und Modelle vergleichen, ohne jedes Mal die Transportschicht neu zu schreiben.

Eine praktische Art, den Aufruf zu verstehen:

• Prompt – die natürlichsprachliche Beschreibung des Bildes, das du möchtest.
• Style – ein Feld im Request-Body, das die visuelle Verarbeitung der Ausgabe steuert.
• Resolution – ein Feld im Request-Body, das die Ausgabegröße bestimmt.

Da alle drei im selben JSON-Body übertragen werden, erfolgen Prompt-Engineering und Ausgabeformung in einem einzigen Roundtrip. Wenn du beurteilst, ob dies der passende Endpunkt ist, lautet die Antwort in der Regel ja – wenn du synchrone, promptgesteuerte Bildgenerierung benötigst und die Details der Anbieter-Pipeline aus deinem Anwendungscode heraushalten möchtest.

Voraussetzungen und Authentifizierung

Bevor du den ersten Aufruf machst, stelle sicher, dass du Folgendes hast:

• Ein HiAPI-Konto und einen API-Schlüssel. Halte ihn aus der Versionskontrolle heraus und lade ihn aus einer Umgebungsvariable.
• curl für einen schnellen Smoke-Test sowie Python 3 mit installiertem requests (falls du die Python-Beispiele verwenden willst).
• Einen Prompt, den du tatsächlich rendern möchtest – selbst ein grober reicht aus, um zu prüfen, ob die Verdrahtung korrekt ist.

Die Authentifizierung bei HiAPI erfolgt headerbasiert. Der API-Schlüssel wird über einen Header übertragen – egal, ob du aus curl, Python oder einem anderen HTTP-Client aufrufst, das Header-Muster ist dasselbe. Die Modellauswahl erfolgt über den Endpunktpfad, daher bleibt der Authentifizierungs-Header unverändert, wenn du das Modell wechselst.

Eine sichere lokale Einrichtung sieht so aus:

export HIAPI_API_KEY="your-key-here"

Dann referenzierst du $HIAPI_API_KEY in Shell-Befehlen und os.environ["HIAPI_API_KEY"] in Python. Hardcodiere den Schlüssel niemals in Skripten, die eingecheckt werden könnten, und vermeide es, ihn in Logs oder Fehlerberichte einzufügen. Wenn der Schlüssel kompromittiert wurde, rotiere ihn in den Kontoeinstellungen, anstatt zu versuchen, ihn aus der Historie zu entfernen.

Die folgenden Beispiele setzen zwei Dinge voraus: die Basis-URL der HiAPI-API und den Modellpfad von recraft-v4.1/text-to-image. Bestätige beide anhand der API-Referenz deines Kontos, bevor du sie in einen Build einbindest, denn der genaue Host und Pfad sind das Einzige in diesem Leitfaden, das du aus der aktuellen Dokumentation statt aus dem Gedächtnis kopieren solltest.

Ein ausführbarer curl-Request

Der schnellste Weg, um zu bestätigen, dass Schlüssel, Endpunkt und Payload-Struktur funktionieren, ist ein curl-Aufruf. Der Request sendet einen JSON-Body mit Prompt und Formgebungsfeldern und übergibt den API-Schlüssel im Header:

curl -X POST "$HIAPI_BASE_URL/recraft-v4.1/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A minimalist isometric illustration of a developer workstation, soft pastel palette, clean background",
    "style": "illustration",
    "resolution": "1024x1024"
  }'

Zum diesem Aufruf gibt es einige Punkte zu beachten:

• Der Endpunktpfad. Der Modellname steht im Pfad. Ein Wechsel zu einem anderen Modell bedeutet später, dieses Pfadsegment zu ändern, statt den Request neu aufzubauen.
• Request-Body statt Query-String. prompt, style und resolution stehen alle im JSON-Body. So bleibt die URL stabil und die Payload lässt sich leicht protokollieren und wiedergeben.
• Header-Authentifizierung. Der Authorization-Header trägt den Schlüssel; Content-Type muss application/json sein.

Wenn du beim ersten Versuch eine Nicht-200-Antwort erhältst, prüfe in dieser Reihenfolge: ob der Schlüssel in der Shell gesetzt ist, ob die Basis-URL keinen doppelten abschließenden Schrägstrich hat, ob der JSON-Body gültig ist (abschließende Kommas sind meist der Übeltäter). Sobald der Aufruf erfolgreich ist, speichere den exakten Befehl in einer Entwurfsdatei – ein bekanntermaßen funktionierender curl-Aufruf ist deine Referenz beim Vergleich jeder SDK- und Client-Änderung.

Derselbe Request in Python

Für echten Code kapsele den Aufruf in einer kleinen Funktion, damit Retries, Logging und Modellwechsel einen einheitlichen Ort haben. Mit requests:

import os
import requests

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


def generate_image(prompt, style="illustration", resolution="1024x1024", timeout=120):
    url = f"{HIAPI_BASE_URL}/recraft-v4.1/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "prompt": prompt,
        "style": style,
        "resolution": resolution,
    }
    response = requests.post(url, headers=headers, json=payload, timeout=timeout)
    response.raise_for_status()
    return response.json()

Bemerkenswerte Designpunkte, die du beibehalten solltest:

• json= statt data=. Wenn du ein dict an json= übergibst, wird der Content-Type für dich gesetzt und der Body serialisiert, sodass die Payload byteweise mit der curl-Version übereinstimmt.
• Expliziter Timeout. Die Bildgenerierung ist nicht sofort; ein großzügiger Timeout verhindert Fehlalarme bei langsamen, aber gesunden Requests. Verlasse dich nicht auf Client-Defaults.
• raise_for_status() zuerst. Wandele HTTP-Fehler in Exceptions um, bevor du versuchst, den Response-Body zu lesen, damit 4xx oder 5xx niemals als Bilddaten missverstanden werden.
• Umgebungsgesteuerte Konfiguration. Basis-URL und Schlüssel kommen beide aus der Umgebung, was die Funktion zwischen lokaler, Staging- und Produktionsumgebung portabel macht.

Die Funktion gibt das geparste JSON zurück. Wie du das Bild aus diesem JSON extrahierst, ist das nächste Thema – und hier gehen die meisten Integrationen schief.

Umgang mit der synchronen Bildantwort

recraft-v4.1/text-to-image gibt die Bilddaten synchron zurück: Das Bild kommt mit dem Request in derselben HTTP-Antwort, ohne Polling-Schleife und ohne Task-ID, die du verfolgen müsstest. Das vereinfacht den Client, verlagert aber zwei Verantwortlichkeiten in deinen Code – das Decodieren der Payload und die explizite Fehlerbehandlung.

Der robuste Verarbeitungspfad sieht so aus:

1. Status vor dem Parsen prüfen. Behandle alles außer 200 als Fehler und zeige den Response-Body an – dieser erklärt meist, wo das Problem liegt.
2. Das Bildfeld bewusst lesen. Das Response-JSON enthält die Bilddaten; je nachdem, welches Feld du erhältst, kann es eine URL oder codierte Bildbytes sein. Behandle beide Pfade, statt einen davon anzunehmen.
3. Defensiv decodieren. Wenn die Payload base64-codiert ist, decodiere sie und schreibe die Bytes in eine Datei. Leite Binärdaten nicht über textbasierte Pfade und gib sie nicht im Terminal aus.
4. Payload-Größe begrenzen. Synchrone Bildantworten sind im Vergleich zu typischem JSON groß. Schreibe sie nach Möglichkeit streaming auf die Festplatte und halte nicht mehrere Antworten gleichzeitig im Speicher.

Minimaler Speicherschritt für eine base64-Payload:

import base64

data = generate_image("A calm forest at dawn, soft light")
image_b64 = data["image"]  # adjust to the actual field name in the response
with open("out.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

Zwei Fehlermodi verdienen besondere Behandlung. Timeouts sollten mit Backoff wiederholt werden, aber nur bei Idempotenz-Erwartung – das erneute Generieren eines Bildes erzeugt andere Ergebnisse, also protokolliere bei jedem Versuch den Prompt. Client-Fehler (etwa ein fehlerhafter Body oder ungültige Optionswerte) beheben sich durch Wiederholen nicht von selbst; scheitere schnell und protokolliere den Antworttext. Prüfe schließlich vor dem Decodieren, ob das Bildfeld vorhanden ist, damit eine Schemaänderung oder eine Fehler-Payload eine klare Exception auslöst statt eines verwirrenden Decodierungsfehlers.

Stil und Auflösung an deinen Anwendungsfall anpassen

style und resolution sind die beiden Request-Body-Felder mit dem größten Einfluss auf das Ergebnis, und beide lassen sich kostengünstig iterieren, da sie zusammen mit dem Prompt übertragen werden.

Style

style steuert die visuelle Verarbeitung der Ausgabe. Nutze es, um den Stil einer Bildserie konsistent zu halten – zum Beispiel einen einheitlichen Stil für eine Reihe von Produktillustrationen oder Artikel-Headerbildern, damit sie wie ein Set wirken. Wenn das Ergebnis falsch wirkt, prüfe zuerst, ob der Stil zum Inhalt passt: Ein für Illustrationen gedachter Stil, der auf einen realistischen Prompt angewendet wird, kollidiert mit dem Text. Probiere mit festem Stil zunächst einfache Prompts aus, bevor du Details hinzufügst, damit du beurteilen kannst, ob ein schlechtes Ergebnis vom Stil oder von der Formulierung kommt.

Resolution

resolution bestimmt die Ausgabegröße. Passe sie dem Zielzweck an: für Avatare und Thumbnails eine nahezu quadratische Größe wählen, für Banner und Hero-Bilder eine breitere. Zwei praktische Regeln:

• Nicht hochskalieren, was du direkt anfordern kannst. Generiere das Bild direkt in einer Größe nahe der endgültigen Anzeigegröße, statt ein kleines Bild zu erzeugen und es dann zu vergrößern.
• Seitenverhältnis beachten. Wenn dein Layout ein bestimmtes Verhältnis erwartet, wähle eine Auflösung, die diesem Verhältnis entspricht, statt nachträglich zuzuschneiden.

Unerwartete Ausgaben debuggen

Wenn das Bild falsch aussieht, isoliere jeweils eine Variable. Lasse den Prompt unverändert und ändere style; dann lasse beide unverändert und ändere resolution. Wenn beides nicht hilft, schreibe den Prompt mit konkreten Substantiven und klaren Kompositionshinweisen neu, statt Adjektive hinzuzufügen. Prüfe außerdem, ob du nicht stillschweigend den falschen Werttyp sendest – ein Stil-String, der nicht zu den zulässigen Optionen passt, kann je nach Validierungslogik abgelehnt oder ignoriert werden. Protokolliere den exakten Request-Body jedes Aufrufs; das ist der einzige verlässliche Nachweis, wodurch ein bestimmtes Bild entstanden ist.

Für die Produktion kapseln

Der Wert der kleinen Funktion von vorhin zeigt sich, wenn du sie härtest. Eine produktionsreife Kapselung sollte vier Dinge tun:

• Den Transport kapseln. Eine Funktion besitzt URL, Header, Payload-Struktur und Timeout. Aufrufer übergeben nur den Prompt und die Optionen, sonst nichts.
• Retries mit Backoff hinzufügen. Timeouts und 5xx-Antworten eine begrenzte Anzahl von Malen wiederholen; 4xx-Fehler niemals wiederholen. Da die Bildgenerierung nicht idempotent ist, halte die Retry-Obergrenze niedrig und verknüpfe den Prompt mit jedem Versuch.
• Den Request protokollieren, nicht nur das Ergebnis. Protokolliere Prompt, Stil, Auflösung, Status und Dauer. Wenn jemand fragt, warum das Bild so aussieht, ist dieses Log die Antwort.
• Das Modell als Parameter führen. Übergib den Modellpfad als Parameter mit dem Standardwert recraft-v4.1/text-to-image. So wird der Wechsel zu einem anderen Bildmodell zu einer Konfigurationsänderung statt zu einem Refactoring, was die parallele Evaluierung günstig macht.

Halte die Kapselungsschicht dünn. Widerstehe der Versuchung, Caching, Queuing oder Speicherstrategien darin unterzubringen – diese gehören in eine darüberliegende Schicht, damit sie sich unabhängig vom API-Aufruf weiterentwickeln können. Eine stabile Schnittstelle bedeutet auch, dass deine Tests die Transportschicht mocken und die Payload asserten können, die du senden wirst – so werden die meisten Integrationsfehler abgefangen, bevor sie einen echten Request erreichen.

Mit Authentifizierung, einem bekanntermaßen funktionierenden Request und expliziter Antwortverarbeitung hast du alles, was du brauchst, um recraft-v4.1/text-to-image über HiAPI mit curl und Python aufzurufen, und kannst später das Modell wechseln, ohne den restlichen Code anzufassen.