Tutorial
So verwendest du krea-3/text-to-image über die HiAPI API: curl, Python und eine lauffähige Anfrage
Auf dieser Seite
Warum krea-3/text-to-image über eine aggregierte API aufrufen
Jedes neue Bildmodell bedeutet ein weiteres SDK, ein weiteres Authentifizierungsschema und eine weitere Reihe von Response-Eigenheiten. Wenn du nur ein Bildfeature auslieferst, sind diese Kosten verkraftbar. Wenn du aber mehrere ausliefern willst – oder dir die Freiheit wünschst, Modelle später auszutauschen –, werden sie zum Hauptkostenfaktor deiner Arbeit.
Der Aufruf von krea-3/text-to-image über HiAPI beseitigt diese Kosten. Du integrierst einmal gegen eine einzige Endpunkt-Konvention, einen einzigen Credential und eine einzige Response-Struktur. Der Modell-Identifier wird zu einem Feld im Request-Payload statt zu einer Verzweigung in deiner Codebasis. Wenn du Ausgaben mit anderen Bildmodellen vergleichen oder Workloads migrieren willst, änderst du einen String statt einer Integration.
Für dieses spezielle Modell sind die praktischen Vorteile konkret:
- Eine gemeinsame Struktur für alle Anfragen. Text-zu-Bild-Aufrufe folgen plattformweit derselben Authentifizierungs- und Payload-Konvention, sodass das Wissen aus dem ersten Aufruf direkt auf das nächste Modell übertragbar ist.
- Modellunabhängiger Anwendungscode. Halte den Modellnamen in der Konfiguration. Prototypen mit
krea-3/text-to-imagezu bauen und später auf ein anderes Modell zu wechseln, sollte keine Änderung an deiner HTTP-Schicht erfordern. - Einheitliche Stelle für Nutzungsbeobachtung. Abrechnung, Request-Logs und Fehlerantworten kommen aus einer Oberfläche statt aus N Anbieter-Dashboards.
- Weniger Schlüssel. Egal wie viele Modelle du aufrufst, du musst nur einen Schlüssel speichern, rotieren und einschränken.
Der Preis ist der übliche Preis der Aggregation: Du arbeitest über eine generische Schnittstelle, daher werden modellspezifische Eigenheiten normalisiert. In der Praxis ist das genau das, was du willst – normalisierte Eingaben, vorhersehbare Fehler und die Freiheit, das Modell als Parameter zu behandeln.
Dieses Tutorial bleibt bewusst eng gefasst. Wir bauen eine lauffähige Anfrage, führen sie zweimal aus (zuerst mit curl, dann mit Python), beobachten, wie die Prompt-Formulierung fotografische und illustrative Ausgaben lenkt, und debuggen dann die wenigen Fehlerfälle, die den Großteil der Probleme beim ersten Aufruf ausmachen. Keine Architekturdiagramme, keine Framework-Meinungen – nur eine Anfrage, die du in den nächsten fünf Minuten senden kannst, plus eine Checkliste für den Fehlerfall.
Voraussetzungen: Du hast ein HiAPI-Konto, kannst den API-Schlüssel aus dem Dashboard auslesen und bist mit Terminal und Python-Interpreter vertraut. Mehr nicht.
Bevor du die Anfrage sendest
Drei Bedingungen müssen vor dem ersten Aufruf erfüllt sein. Mach sie richtig, und der Rest ist meist Tuning; mach sie falsch, und du verbringst eine Stunde mit Debugging auf der falschen Ebene.
1. Konto und API-Schlüssel
Melde dich bei HiAPI an und hole deinen API-Schlüssel aus dem Dashboard. Behandle ihn als Geheimnis: Er gehört in eine Umgebungsvariable oder einen Secret-Manager, niemals in eine eingecheckte Datei, niemals in einen Prompt oder eine Support-Nachricht. Die folgenden Beispiele lesen ihn aus einer Umgebungsvariable:
export HIAPI_API_KEY="your-key-here"
Wenn deine Organisation mehrere Schlüssel unterstützt, verwende für diese Integration einen dedizierten Schlüssel, damit du ihn unabhängig von anderen Läufen rotieren kannst.
2. Endpunkt-Konvention und Auth-Header
HiAPI-Anfragen verwenden Bearer-Token-Authentifizierung – dasselbe Muster, das du aus hundert anderen APIs kennst:
Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json
Verwende die Base-URL, die in der HiAPI-API-Referenz für deine Konto-Region angegeben ist, und hänge den dort dokumentierten Pfad für die Bildgenerierung an. Rate den Pfad nicht aus dem Gedächtnis und kopiere ihn nicht aus Blogartikeln (einschließlich diesem hier) – die API-Referenz ist die einzige Quelle der Wahrheit, und der Pfad ist der einzige Teil der Anfrage, der sich ohne Vorwarnung ändern kann. Tipp für das Tutorial: Schlage die Referenz einmal nach, kopiere die URL und bewahre sie als Konfigurationswert auf.
3. Der Modell-Identifier, exakt buchstabiert
Der Modell-Identifier ist krea-3/text-to-image. Halte Namespace-Präfix und Bindestriche genau so, wie sie geschrieben sind – krea3/text2image oder ein alleinstehendes krea-3 scheitern mit Modell nicht gefunden. Auch die Groß-/Kleinschreibung zählt. Speichere ihn als Konstante:
MODEL = "krea-3/text-to-image"
Genau dieser String macht deine Integration modellunabhängig, also gib ihm einen Namen und behandle ihn als Konfiguration, statt ihn an jeder Aufrufstelle hart zu kodieren.
Was du vorab nicht klären musst
Du musst vor dem ersten Aufruf nicht die Namen der Felder für Bildgröße, Seed oder Schritte kennen. Beginne mit einer minimalen Konfiguration: Authentifizierung, Modell-Identifier, Prompt. Sobald du eine 200-Antwort hast, füge Parameter einen nach dem anderen hinzu, denn eine fehlgeschlagene Anfrage mit fünf gesetzten Feldern liefert dir fünf Verdächtige. Eine minimale fehlgeschlagene Anfrage liefert dir nur einen.
Eine lauffähige Anfrage mit curl bauen
curl ist der schnellste Weg, die zwei Probleme des ersten Aufrufs zu isolieren: Credentials und Payload-Struktur. Keine SDK-Version, keine virtuelle Umgebung, keine asynchrone Laufzeit – nur eine Anfrage über die Leitung.
Der minimale Aufruf enthält nur das, was das Modell wirklich braucht: Auth-Header, Modell-Identifier und Prompt.
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "krea-3/text-to-image",
"prompt": "A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
}'
Zwei Hinweise vor dem Ausführen. Erstens: $HIAPI_BASE_URL ist ein Platzhalter – setze ihn auf die Base-URL aus der HiAPI-API-Referenz und prüfe das Pfadsegment gegen dieselbe Referenz. Zweitens: Das Flag -sS hält die Ausgabe ruhig, zeigt aber Fehler an – genau das willst du beim Debugging.
So sieht eine gesunde Antwort aus: ein JSON-Objekt mit einer Referenz auf das generierte Bild oder den Daten sowie Request-Metadaten. Die genaue Struktur ist in der API-Referenz dokumentiert; schreibe keinen Parsing-Code für eine Struktur, die du noch nicht beobachtet hast. Speichere die echte Antwort in einer Datei, um eine Baseline zu erhalten:
curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"krea-3/text-to-image","prompt":"A neon-lit alley after rain, cinematic still"}' \
-o response.json
Prüfe sie dann mit jq oder deinem Editor. Diese Datei ist dein Test-Fixture: Wenn du zu Python portierst, vergleiche die Ausgabe. Wenn die Python-Antwort strukturell von response.json abweicht, liegt das Problem in deinem Code, nicht im Modell.
Der Grund, das zuerst mit curl zu tun, ist die diagnostische Hebelwirkung. Wenn der curl-Aufruf gelingt, ist dein Schlüssel gut, die URL korrekt und der Modell-Identifier auflösbar – dann liegt jeder spätere Fehler in deinem Anwendungscode. Wenn der curl-Aufruf scheitert, sagt dir der Fehlerbody, welcher der drei Punkte das Problem ist, und du hast noch keine Zeile Code geschrieben.
Sobald die minimale Anfrage gelingt, füge Parameter einen nach dem anderen hinzu. Führe curl nach jeder Ergänzung erneut aus. Behalte die erfolgreichen Payloads; sie werden zu akzeptierten Input-Fixtures für deine Tests.
Dieselbe Anfrage in Python
Die Python-Version bleibt bewusst langweilig: dieselbe URL, dieselben Header, derselbe JSON-Body. Der Fokus liegt auf Portabilität – die Request-Struktur, die du in curl validiert hast, sollte sich in ein Skript und dann in einen Service übertragen lassen, ohne neu entworfen zu werden.
import os
import json
import requests
BASE_URL = os.environ["HIAPI_BASE_URL"].rstrip("/")
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL = "krea-3/text-to-image"
def generate(prompt: str) -> dict:
response = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={"model": MODEL, "prompt": prompt},
timeout=120,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate(
"A weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph"
)
print(json.dumps(result, indent=2))
Einige bewusste Entscheidungen:
- Umgebungsvariablen statt Literale. Der Schlüssel taucht nie im Quellcode auf. Wenn die Variable fehlt, scheitert
os.environ["HIAPI_API_KEY"]beim Start laut – besser als ein verwirrender 401 drei Ebenen tiefer. raise_for_status()vor dem Parsen. Du willst HTTP-Fehler als Exceptions sehen, nicht alsKeyError, wenn du versuchst, Felder aus einem Fehlerbody zu lesen, der zufällig JSON ist.- Großzügiges Timeout. Bildgenerierung ist kein Instant-Endpunkt. Setze ein Timeout, das das spiegelt, und behandle es in der Produktion explizit (siehe Produktionsabschnitt).
json=statt manuell gebauter Strings. Lass die Bibliothek serialisieren. Handgebautes JSON ist die Quelle von Komma- und Anführungszeichenfehlern.
Führe es einmal aus und vergleiche die Ausgabe mit der zuvor gespeicherten response.json. Die Struktur sollte übereinstimmen. Gib die Bildreferenz oder die dekodierten Bilddaten aus, je nachdem, was die Antwort liefert – auch hier: Code für die beobachtete Struktur schreiben, nicht für eine angenommene.
Da MODEL eine Konstante ist, funktioniert dieselbe Funktion generate() für jedes Bildmodell auf der Plattform. Das ist die Rendite des aggregierten Modells: Sie in einen Service zu verschieben, ein zweites Modell hinzuzufügen oder A/B-Tests der Ausgaben zu fahren, sind nur Parameteränderungen statt einer Neuentwicklung.
Fotografischen und illustrativen Stil lenken
Stil ist kein Schalter; er ist die Richtung, in die du das Modell schiebst, und krea-3/text-to-image reagiert auf dieselben Hebel, die du bei einem Fotografen oder Illustrator ziehen würdest: Motiv, Medium, Licht und Handwerksvokabular.
In Richtung fotografischer Stil
Fotografische Ausgabe dreht sich vor allem darum, Geräte und ihre Folgen zu benennen. Wörter, die Kamera, Objektiv, Film und reales Licht beschreiben, wirken besser als das Wort „realistisch“.
- Nenne Medium und Aufnahmeart: „35mm photograph“, „editorial portrait“, „documentary still“.
- Nenne das Licht: „overcast daylight“, „golden hour backlight“, „single softbox at camera left“.
- Nenne Unvollkommenheiten: „slight motion blur“, „visible grain“, „shallow depth of field“.
Vergleiche "a fisherman on a dock" mit "a weathered fisherman mending a net on a dock at dawn, overcast light, 35mm photograph, visible grain". Der zweite Prompt zwingt das Modell in Richtung fotografischer Textur und Beleuchtung statt in eine allgemeine Darstellung.
In Richtung illustrativer Stil
Illustration dreht sich darum, Tradition, Linienqualität und Farbpalette zu benennen – und meist darum, die fotografischen Hinweise zu entfernen, die du gerade gelernt hast.
- Nenne den Stil: „flat vector illustration“, „ink and watercolor“, „mid-century editorial illustration“, „isometric line art“.
- Nenne die Linien: „clean uniform strokes“, „loose gestural linework“.
- Nenne die Palette: „restrained two-color palette“, „muted pastels“.
Iterieren statt vorab festlegen
Behandle den Prompt als abstimmbare Konfiguration. Ändere jeweils nur eine Dimension – tausche nur die Medium-Phrase, halte Motiv und Licht fest –, damit du lernst, was jedes Token bewirkt. Führe ein kurzes Log der Prompt-Varianten und ihrer Ausgaben; dieses Log ist wertvoller als jede Preset-Bibliothek, weil es auf dein Modell und deinen Content kalibriert ist.
Wenn die Anfrage Parameter jenseits des Prompts offenlegt – Größe, Seed oder Ähnliches –, stimme sie nach der Festlegung des Prompts ab, nicht davor. Prompt und drei Parameter gleichzeitig zu ändern, sagt dir nicht, welche Änderung gewirkt hat.
Häufige Fehler diagnostizieren
Die meisten Fehler beim ersten Aufruf fallen in vier Kategorien. Arbeite die Checkliste der Reihe nach ab; jeder Schritt schließt eine Ebene aus.
Authentifizierungsfehler
Symptom: 401 oder 403 mit einer Meldung zu Credentials oder Berechtigungen.
- Ist
HIAPI_API_KEYin der Shell, die den Befehl ausführt, wirklich gesetzt?echo $HIAPI_API_KEY– ein leerer String sieht einem falschen Schlüssel sehr ähnlich. - Ist der Header genau
Authorization: Bearer <key>? Ein fehlendesBearer, überzählige Anführungszeichen oder ein Zeilenumbruch im kopierten Schlüssel führen zum Scheitern. - Wurde der Schlüssel widerrufen oder ist er auf eine andere Umgebung beschränkt? Im Zweifel neu generieren und mit einem curl-Aufruf erneut testen.
Fehlerhafter Request-Payload
Symptom: 400 mit einer Meldung zu Body, Feldern oder JSON-Parsing.
- Validiere das JSON vor dem Senden. In curl zerstört ein unescaped Anführungszeichen im Prompt den Body. In Python kümmert sich
json=darum – ein weiterer Grund, es zu bevorzugen. - Prüfe, ob
Content-Type: application/jsonvorhanden ist. - Prüfe die Feldnamen gegen die API-Referenz. Ein korrekt geschriebener Wert unter einem falschen Feldnamen ist immer noch ein 400.
- Gehe auf den minimalen Payload zurück – nur Modell und Prompt –, bestätige, dass er funktioniert, und füge Felder dann einzeln hinzu.
Falscher Modell-Identifier
Symptom: 404 oder 400 mit der Meldung, das Modell sei unbekannt oder nicht verfügbar.
- Vergleiche deinen String Zeichen für Zeichen mit
krea-3/text-to-image. Namespace-Präfix, Bindestriche und Pfadsegmente zählen. - Prüfe, ob durch Copy-Paste aus der Dokumentation unbeabsichtigte Leerzeichen oder typografische Anführungszeichen hineingeraten sind.
- Stelle sicher, dass der Wert nicht irgendwo im Code von einem Konfigurations-Default überschrieben wird.
Rate- und Quota-Antworten
Symptom: 429 oder eine Meldung zu Limits oder unzureichendem Guthaben.
- Warte ab und versuche es nach kurzer Verzögerung erneut, statt den Endpunkt zu hämmern.
- Prüfe deine Nutzung und dein Guthaben im Dashboard.
- Wenn das während der Entwicklung passiert, suche nach einer Retry-Schleife, die schneller feuert als gedacht – eine fehlgeschlagene Anfrage in einem
try-Block plus aggressives Retrying erschöpft Limits schnell.
Wenn nichts davon hilft, erfasse die vollständige Request-ID und den Fehlerbody aus der Antwort und sende sie an den Support. Fehlerbodies bei einer aggregierten API sind meist spezifisch genug, um das Problem zu benennen; der Fehler liegt darin, sie zu paraphrasieren statt sie einzufügen.
In die Produktion bringen
Deine aktuelle Anfrage ist ein Prototyp. Vier Praktiken machen daraus etwas, das dauerhaft laufen kann.
Fehler nach Kategorie behandeln, nicht nach String
Ordne HTTP-Statuscodes Verhalten zu: Authentifizierungsfehler sind Konfigurationsfehler und sollten jemanden rufen; 4xx-Payload-Fehler sind Codefehler und sollten die Anfrage laut scheitern lassen; 429 und 5xx sind transient und sollten mit exponentiellem Backoff und Jitter wiederholt werden. Wiederhole niemals einen 400 – du verschwendest nur Quota, um denselben Defekt zu bestätigen. Setze explizite Timeouts und behandle Timeouts als transient.
if response.status_code == 429 or response.status_code >= 500:
raise TransientError(response.status_code)
response.raise_for_status()
Prompts protokollieren und versionieren
Jedes generierte Bild sollte auf den exakten Prompt zurückführbar sein, der es erzeugt hat. Speichere Prompt, Modell-Identifier, Parameter und Response-Request-ID zusammen. Behandle den Prompt-Text als versionierte Konfiguration – einen eingecheckten String prompt_v3 in einer Konfigurationsdatei statt eines Literals in einer Funktion. Wenn sich die Ausgabequalität ändert, musst du wissen, ob der Prompt, ein Parameter oder das Modell sich geändert hat.
Den Modellnamen in der Konfiguration halten
krea-3/text-to-image sollte genau einmal auftauchen, in einer Konstante oder einem Konfigurationseintrag. Genau das ist die Rendite des aggregierten Modells: Ein Modell auszutauschen, Vergleiche zu fahren oder zurückzurollen wird zu einer Konfigurationsänderung statt zum Deployment eines neuen Codepfads. Es macht es außerdem trivial, später verschiedene Workloads auf verschiedene Modelle zu routen.
Gegen Fixtures testen
Speichere die in diesem Tutorial erfassten Erfolgsantworten als Fixtures. Stelle sicher, dass dein Parsing-Code sie verarbeiten kann, und nutze die protokollierten Fehlerbodies zum Testen der Fehlerzuordnung. So erkennst du Drift der Response-Struktur vor deinen Nutzern.
Beginne mit dem minimalen curl-Aufruf, bestätige die Response-Struktur, portiere sie unverändert nach Python und iteriere dann den Prompt Dimension für Dimension – und konsultiere die HiAPI-API-Referenz für Endpunkt-Details, die sich ändern können.
Ä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