Tutorial
So verwenden Sie grok-imagine/text-to-image über die HiAPI API: curl- und Python-Leitfaden
Auf dieser Seite
Was grok-imagine/text-to-image Ihnen bietet
grok-imagine/text-to-image ist ein Text-zu-Bild-Endpunkt, der über HiAPI bereitgestellt wird: Sie senden einen Prompt und einige Generierungsparameter als JSON per HTTP und erhalten ein Bild zurück. Das ist die gesamte Vereinbarung. Kein SDK zu installieren, keine Sitzung zu initialisieren und kein Hintergrundtask abzufragen, um das erste Bild zu sehen.
Seine Rolle im Entwickler-Workflow:
- Prototyping. Sie gelangen mit einem einzigen Terminalbefehl von der Idee zum gerenderten Bild, was es Ihnen ermöglicht, Prompt-Ideen schnell zu testen.
- Content-Pipelines. Da es nur ein gewöhnlicher HTTP-Aufruf ist, können Sie es wie jede andere API aus Backend-Diensten, Queue-Workern oder Build-Skripten aufrufen.
- Produktfunktionen. Benutzergerichtete Bildgenerierung bedeutet in der Regel, dass Sie vorhersehbare Request/Response-Verarbeitung, strukturierte Fehler und Wiederholungen benötigen. Ein zustandsloser Endpunkt eignet sich hervorragend für alle drei.
Was dieser Endpunkt nicht ist: Er speichert Ihre Prompts nicht, verwaltet keine Bibliothek generierter Bilder und ersetzt nicht Ihre eigene Orchestrierung. Sie sind für die Anfrage verantwortlich, Sie sind für die Ausgabe verantwortlich, und Sie entscheiden, wohin die Bytes gehen.
Dieser Leitfaden konzentriert sich darauf, Anfragen zuerst zum Laufen zu bringen und sie dann zuverlässig zu machen. Ob Sie mit curl oder Python aufrufen, das Muster ist identisch, da beide denselben authentifizierten HTTP-Request darstellen. Beginnen Sie mit dem minimalen funktionierenden Fall, bestätigen Sie einen erfolgreichen Roundtrip und fügen Sie dann Komplexität hinzu.
Voraussetzungen und Authentifizierung
Bevor Sie den ersten Aufruf tätigen, stellen Sie sicher, dass Sie Folgendes haben:
- Ein HiAPI-Konto und einen API-Schlüssel. Behandeln Sie den Schlüssel als vertraulich: Laden Sie ihn aus einer Umgebungsvariable und kodieren Sie ihn niemals fest in ein Skript, das committet werden könnte.
- Ein Werkzeug zum Senden von HTTP-Anfragen.
curlreicht für den ersten Test. Für Python verwenden Sierequestsoderhttpx; beide werden weiter unten behandelt. - Netzwerkzugriff auf den HiAPI-API-Host. Wenn Sie sich hinter einem Unternehmensproxy befinden, stellen Sie sicher, dass
HTTPS_PROXYfür Ihre Shell gesetzt ist, damit sowohlcurlals auch Python ihn lesen können.
Der Schlüssel wird als Bearer-Token über den Authorization-Header übergeben:
export HIAPI_API_KEY="your-key-here"
Dann trägt jede Anfrage:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Zwei Gewohnheiten, die es sich sofort anzueignen lohnt:
- Lassen Sie den Schlüssel nicht in der URL erscheinen. An keiner Stelle der Anfrage sollten Anmeldeinformationen in die Query-String gelangen, da sie dort letztendlich in Logs und Shell-Verläufen landen.
- Verwenden Sie einen Schlüssel pro Umgebung. Entwicklungs- und Produktionsschlüssel sollten unterschiedliche Werte sein, damit Sie einen rotieren können, ohne den anderen zu beeinträchtigen.
Wenn Sie noch keinen Schlüssel generiert haben, erstellen Sie einen im HiAPI-Dashboard und speichern Sie ihn in Ihrem Secret-Manager oder in einer lokalen .env-Datei, die von der Versionskontrolle ausgeschlossen ist. Sobald echo $HIAPI_API_KEY einen Wert ausgibt, können Sie Ihre erste Anfrage senden.
Minimal funktionierende Anfrage in curl
Der kleinste nützliche Aufruf sendet nur die Modellkennung und den Prompt. Alles andere hat Standardwerte, also tunen Sie nicht an den Parametern, bevor Sie ein Bild zurückerhalten haben.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine/text-to-image",
"prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light"
}'
Die Rolle der einzelnen Teile:
-X POSTzusammen mit einem JSON-Request-Body ist die Standardform für Generierungsendpunkte.modelwählt explizitgrok-imagine/text-to-imageaus. Fixieren Sie den Modellnamen in Skripten, anstatt sich auf Standardwerte zu verlassen, damit Änderungen an Standardwerten Ihre Ausgabe nicht unbemerkt verändern.promptist die einzige Inhaltseingabe. Halten Sie ihn für den ersten Test bei einem klaren Satz.
Eine erfolgreiche Antwort liefert JSON mit dem generierten Bild zurück, in der Regel eine URL oder eine base64-Nutzlast, abhängig vom angeforderten Antwortformat. Lesen Sie die Antwort mit einem JSON-Formatierungswerkzeug, bevor Sie Parsing-Code schreiben. Wenn Sie die Ausgabe im Terminal ansehen, macht die Weiterleitung durch python -m json.tool die Struktur lesbarer.
Nach einem erfolgreichen Lauf speichern Sie die Rohantwort in einer Datei, damit Sie eine bekannte gute Ausgangsbasis haben:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json \
-o response.json
Wenn Sie den Request-Body in request.json ablegen, können Sie den Prompt bearbeiten, ohne mit Shell-Anführungszeichen zu kämpfen, was besonders wichtig ist, wenn Prompts länger werden oder Satzzeichen enthalten.
Dieselbe Anfrage in Python
Die Python-Version ist derselbe HTTP-Aufruf, nur mit einer angenehmeren Erfahrung: ein Dictionary statt verschachtelter Anführungszeichen und direkte Handhabung der Bildbytes.
import os
import requests
api_key = os.environ["HIAPI_API_KEY"]
base_url = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "grok-imagine/text-to-image",
"prompt": "a lighthouse on a rocky coast at dusk, calm sea, soft overcast light",
}
response = requests.post(
f"{base_url}/v1/images/generations",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
Zwei Details verdienen besondere Erwähnung. Erstens, timeout=120 – die Bildgenerierung ist nicht sofort, und Anfragen ohne Timeout lassen Worker unbegrenzt hängen, wenn das Upstream nicht reagiert. Zweitens, rufen Sie raise_for_status() vor dem Parsen auf, damit ein Fehler-Response-Body nicht fälschlich als erfolgreiche Bildantwort interpretiert wird.
Um das Bild zu speichern, behandeln Sie beide Antwortformen:
item = data["data"][0]
if item.get("b64_json"):
import base64
image_bytes = base64.b64decode(item["b64_json"])
else:
image_bytes = requests.get(item["url"], timeout=60).content
with open("output.png", "wb") as f:
f.write(image_bytes)
Wenn Sie einen einheitlichen Abhängigkeitssatz bevorzugen, ist die Verwendung von httpx identisch, mit httpx.post(..., json=payload). Der entscheidende Punkt ist, dass Request-Body und Header exakt mit dem curl-Beispiel übereinstimmen – genau diese Konsistenz macht die beiden Beispiele austauschbar und das Debugging vorhersehbar.
Prompts für Seitenverhältnisse strukturieren
Breite Ausgaben scheitern auf bestimmte Weise: Das Modell hat viel horizontalen Raum zu füllen, sodass es entweder Elemente wiederholt oder ein winziges Motiv in einer leeren Bildfläche schweben lässt. Sie lösen dies durch Prompt-Struktur, nicht durch das Anhäufen weiterer Adjektive.
Verwenden Sie ein dreiteiliges Gerüst:
- Motiv – worum es im Bild geht, zuerst und konkret benannt. „Ein Frachtschiff, das in den Hafen einläuft“ ist besser als „ein Schiff“.
- Stil – die Bildsprache: Fotografie, flache Vektorgrafik, Aquarell, Filmstill. Ein oder zwei Wörter reichen aus.
- Komposition – wie das Bild organisiert ist; hier entscheidet sich Erfolg oder Misserfolg des Breitbildformats.
Für die Komposition benennen Sie horizontale Strukturen explizit:
- Geben Sie eine Leserichtung von links nach rechts oder eine panoramaartige an: „Weite Totale, Motiv im rechten Drittel, links offener Himmel.“
- Beschreiben Sie Vordergrund, Mittelgrund und Hintergrund als getrennte Zonen, da breite Bilder natürlich in Schichten gelesen werden.
- Geben Sie explizit an, was die Ränder füllt: „Ganz links Hafenkräne, ganz rechts offenes Wasser.“ Die Ränder sind der Ort, an dem breite Bilder zuerst leer werden.
- Vermeiden Sie Prompts, die Porträt- oder quadratische Kompositionen implizieren – Nahaufnahmen von Gesichtern, einzelne zentrierte Objekte – und rechnen Sie damit, dass sie gestreckt oder mit schwarzen Balken versehen werden.
Wenn Sie den Seitenverhältnis-Parameter für ein Panoramaformat festlegen, ändern Sie gleichzeitig den Prompt. Ein für ein quadratisches Bild geschriebener Prompt erzeugt ein quadratisches Konzept auf einer breiten Leinwand. Schreiben Sie ihn in eine Szene mit horizontaler Ausdehnung um: ein Horizont, eine Straße, Reihen von Objekten, eine über einen Raum verteilte Gruppe.
Iterieren Sie jeweils nur eine Variable. Halten Sie das Seitenverhältnis fest und ändern Sie die Formulierung; dann halten Sie die Formulierung fest und ändern Sie das Verhältnis. Protokollieren Sie beides zusammen mit der Ausgabe, damit Sie beurteilen können, welche Änderung tatsächlich geholfen hat.
Fehler und Statuscodes behandeln
Lesen Sie zuerst den Statuscode, dann den Response-Body. Jede häufige Fehlerart deutet auf eine andere Lösung hin, und ihre Verwechslung kostet Zeit.
401 Unauthorized
Der Schlüssel fehlt, ist falsch formatiert oder wurde widerrufen. Prüfen Sie, ob der Header exakt Authorization: Bearer <key> lautet, ob die Umgebungsvariable tatsächlich expandiert wurde (geben Sie ihre Länge aus, nicht den Wert) und ob Sie versehentlich einen Schlüssel aus einer anderen Umgebung gesendet haben.
400 Bad Request
Ihr JSON ist gültiges HTTP, aber für diesen Endpunkt ungültig. Häufige Verdächtige:
modelist falsch geschrieben oder fehlt. Es mussgrok-imagine/text-to-imagesein.promptist leer oder fehlt.- Ein Parameter hat den falschen Typ – ein String, wo eine Zahl erwartet wird, oder umgekehrt.
- Der Request-Body ist überhaupt kein gültiges JSON, was oft auf Shell-Anführungszeichen-Probleme in
curlzurückzuführen ist. Verschieben Sie den Body in eine Datei und verwenden Sie-d @request.json.
Lesen Sie den Fehler-Body; er gibt normalerweise das problematische Feld an.
429 Too Many Requests
Sie senden Anfragen schneller als Ihr Kontingent. Die Lösung liegt im Client: Backoff, Warteschlange, Wiederholung. Verkürzen Sie nicht Ihre Wiederholungsschleife, weil Sie einen 429 erhalten haben – das macht es schlimmer.
5xx Server Errors
Dies sind vorübergehende oder Upstream-Zustände. Wiederholen Sie nach einer Verzögerung, und wenn der Fehler nach mehreren Versuchen weiterhin auftritt, erfassen Sie die Request-Nutzlast und den Response-Body zur Diagnose, anstatt unbegrenzt zu wiederholen.
Timeouts und Verbindungsfehler
Dies sind überhaupt keine HTTP-Statuscodes, aber in der Praxis die häufigsten Fehler. Wenn requests einen Verbindungs-Timeout auslöst, wurde die Anfrage möglicherweise dennoch verarbeitet. Bevor Sie eine Wiederholungsschleife schreiben, entscheiden Sie für Ihren Anwendungsfall, ob ein Timeout „wiederholen“ oder „aufgeben“ bedeutet.
Tuning und Wiederholungen in der Produktion
Nachdem die Basis-Anfrage funktioniert, tunen Sie in kleinen Schritten: Ändern Sie zuerst die Prompt-Formulierung, dann das Seitenverhältnis, dann andere Parameter, und vergleichen Sie Ausgaben nebeneinander. Speichern Sie jede Request-Nutzlast zusammen mit ihrer Ausgabe, damit Ergebnisse stets reproduzierbar sind.
Ein Produktions-Wrapper erledigt drei Dinge: nur Fehler wiederholen, die es wert sind, wiederholt zu werden; genug für das Debugging protokollieren; und laut scheitern, wenn er aufgibt.
import time
import requests
def generate(payload, max_attempts=4):
for attempt in range(1, max_attempts + 1):
try:
r = requests.post(
f"{base_url}/v1/images/generations",
headers=headers,
json=payload,
timeout=120,
)
except requests.RequestException as exc:
log.warning("request failed attempt=%d err=%s", attempt, exc)
time.sleep(2 ** attempt)
continue
if r.status_code == 429 or r.status_code >= 500:
log.warning("retryable status=%d attempt=%d", r.status_code, attempt)
time.sleep(2 ** attempt)
continue
if r.status_code >= 400:
raise RuntimeError(f"{r.status_code}: {r.text[:500]}")
return r.json()
raise RuntimeError("exhausted retries")
Hinweise zu diesem Muster:
- Exponentielles Backoff mit Obergrenze (
2 ** attempt) verhindert, dass ein gedrosselter Client den Endpunkt wiederholt überlastet. Wenn Sie viele Worker betreiben, fügen Sie Jitter hinzu. - Wiederholen Sie nur 429, 5xx und Netzwerkfehler. 400 oder 401 schlagen bei jedem Versuch auf dieselbe Weise fehl.
- Protokollieren Sie Versuchsanzahl und Status, nicht den API-Schlüssel, und niemals den vollständigen Prompt, wenn der Prompt Benutzerdaten enthalten könnte.
- Begrenzen Sie die Gesamtzeit. Eine Wiederholungsschleife ohne Obergrenze verwandelt eine langsame Anfrage in einen hängenden Worker.
Messen Sie Ihre eigenen Latenzen und Erfolgsquoten, anstatt sie anzunehmen; diese beiden Zahlen sagen Ihnen, ob Sie mehr Parallelität oder mehr Backoff benötigen. Beginnen Sie mit der minimalen Anfrage aus diesem Leitfaden, umhüllen Sie sie mit der obigen Hilfsfunktion und iterieren Sie von dort aus.
Ähnliche Artikel
Alle Artikel ansehen →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen