Blog

Tutorial

Verwendung von minimax-h3-image für Text-zu-Bild über die HiAPI-API: curl und Python

Nov 13, 2026
Cover-Bild im flachen Webstil: ein quadratisches Webmuster aus breiten, ineinander verschlungenen Stoffbändern in Dunkelbraun und Haferfarbe, akzentuiert mit wenigen messingfarbenen Webkanten.
Auf dieser Seite

Was dieses Tutorial abdeckt und was du vorher brauchst

Dieses Tutorial behandelt genau eine konkrete Sache: eine Bildgenerierungs-Eingabeaufforderung über die HiAPI-API an das Text-zu-Bild-Modell minimax-h3-image senden – zuerst mit einem curl-Request, dann mit einer kleinen Python-Funktion, die du in deine Anwendung einbauen kannst. Behandelt werden der Aufbau der Anfrage, das Lesen der Antwort, wie sich Fehler zeigen und welche Stellen vor dem Produktivbetrieb nachgeschärft werden müssen.

Bewusst nicht behandelt werden Prompt-Engineering-Theorie, Bildnachbearbeitung oder UI-Entwicklung. Das Ziel ist fokussierter: Nach der Lektüre solltest du einen verlässlichen Request besitzen und genau wissen, warum er beim letzten Mal fehlgeschlagen ist.

Voraussetzungen

  • Ein HiAPI-Konto. Vor allem anderen brauchst du ein Projekt und einen API-Schlüssel – jede Anfrage unten erfordert Authentifizierung.
  • Den Schlüssel sicher aufbewahren. Lege ihn in einer Umgebungsvariable (HIAPI_API_KEY) ab, nicht in einer Quelldatei, damit derselbe Code lokal und in CI funktioniert.
  • Den Modellbezeichner. Dieses Tutorial verwendet minimax-h3-image mit der Fähigkeit text-to-image. Behandle Modellname und Aufgabenpfad als Konfigurationswerte im Code, nicht als überall verstreute Magic Strings.
  • Werkzeuge. Für die erste Anfrage curl, für die zweite Python 3.9+ und requests. Weitere Bibliotheken sind nicht nötig.
  • Eine Möglichkeit, das Bild anzusehen. Du erhältst eine Antwortnutzlast mit Bilddaten oder einem Verweis auf das Bild – prüfe die Antwortfelder einmal manuell, bevor du ein Schema annimmst.

Eine Gewohnheit, die du dir jetzt aneignen solltest

Erzeuge die erste erfolgreiche Anfrage außerhalb deines Anwendungscodes. Ein funktionierender curl-Befehl ist die Grundwahrheit: Wann immer sich die Python-Version merkwürdig verhält, vergleiche damit. Wenn der curl-Aufruf erfolgreich ist und Python nicht, liegt das Problem in deinem Client, nicht im Modell oder im Netzwerk.

Einen funktionierenden Text-zu-Bild-Request mit curl aufbauen

Beginne mit der kleinstmöglichen Anfrage und füge dann Schritt für Schritt eine Einstellung nach der anderen hinzu. Eine Generierungsanfrage besteht aus drei Teilen: dem Endpunkt, dem Authentifizierungsheader und dem JSON-Request-Body.

Die Anfrage

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-image",
    "task": "text-to-image",
    "prompt": "Eine Keramikschale auf einer Leinentischdecke, weiches Licht vom Nordfenster, 50-mm-Objektiv, geringe Schärfentiefe",
    "size": "1024x1024",
    "n": 1
  }'

Drei Dinge sind an diesem Befehl beachtenswert:

  • Der Schlüssel wird als Bearer-Token im Authorization-Header übergeben. Lege ihn niemals in die URL oder den Request-Body, sonst landet er in Logs und der Shell-Historie.
  • model und task beschreiben, was du willst – Modellfamilie und Fähigkeit. Schreibe beide explizit hin, auch wenn Standardwerte existieren; explizite Anfragen überdauern länger.
  • prompt ist ein einfacher String. Alles andere (size, n) sind Bild-Einstellungen, keine Beschreibung des Motivs.

Die Antwort interpretieren

Formatiere die Ausgabe, damit du sie wirklich lesen kannst:

curl -s -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

Lege den Request-Body während der Iteration in eine Datei (request.json) – so bleibt der Prompt lesbar und eine Prompt-Änderung wird zu einem Ein-Zeilen-Diff statt zu einem Ratespiel mit Anführungszeichen.

Prüfe die Nutzlast, bevor du einen Parser schreibst. Achte darauf, ob das Bild inline oder als URL zurückgegeben wird, welche Felder die Bildkennung und gegebenenfalls den geänderten Prompt enthalten und ob die Antwort Nutzungsmetadaten enthält. Notiere dir diese Feldnamen; dein Python-Client wird sich darauf stützen.

Den gesamten Ablauf von Anfang bis Ende bestätigen

Speichere das zurückgegebene Bild, öffne es und prüfe, ob du genau das erhalten hast, was du angefordert hast. Eine 200-Antwort mit einer plausibel aussehenden JSON-Nutzlast bedeutet nicht, dass das Bild korrekt ist – an genau dieser Stelle lassen sich Prompt- und Parameterprobleme am günstigsten entdecken.

Die Anfrage nach Python übertragen

Portiere nun genau dieselbe Anfrage. Halte sie unspektakulär: eine Funktion, explizite Timeouts, vorerst keine versteckten Wiederholungen.

import os
import requests

HIAPI_API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/images/generations"


def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
    """Generiert ein Bild mit minimax-h3-image über HiAPI."""
    payload = {
        "model": "minimax-h3-image",
        "task": "text-to-image",
        "prompt": prompt,
        "size": size,
        "n": n,
    }
    response = requests.post(
        ENDPOINT,
        headers={
            "Authorization": f"Bearer {HIAPI_API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=(5, 120),  # Verbindungs-Timeout, Lese-Timeout
    )
    response.raise_for_status()
    return response.json()

In dieser Funktion stecken vier bewusste Entscheidungen:

  • Tupel-Timeout. Der Verbindungs-Timeout ist kurz, denn ein langsamer Verbindungsaufbau deutet auf ein Problem hin; der Lese-Timeout ist großzügiger, denn die Bildgenerierung braucht nun einmal Zeit. Ein einzelner Timeout-Wert zwingt dich, bei einem der beiden Fehlermodi schlecht abzuschneiden.
  • json=payload. Lass die Bibliothek den Request-Body serialisieren. Manuell zusammengebaute JSON-Strings sind eine Brutstätte für Anführungszeichen-Bugs.
  • raise_for_status() vor dem Parsen. Die Statusprüfung ist nicht optional – einen Fehler-Response-Body als Erfolg zu parsen ist die verwirrendste Art von Bug in dieser Art von Integration.
  • Ein einfaches dict zurückgeben. Du kannst es später mit typisierten Modellen veredeln; stelle zuerst sicher, dass du weißt, welche Felder die Antwort tatsächlich enthält.

Die Schlüsselsuche isolieren

Wenn die Variable fehlt, wirft os.environ["HIAPI_API_KEY"] sofort eine Ausnahme. Das ist Absicht: beim Start scheitern statt bei der ersten Nutzeranfrage. In einer größeren Codebasis löst du den Schlüssel einmal während des Ladens der Konfiguration auf und übergibst dann einen konfigurierten Client, statt an der Aufrufstelle Umgebungsvariablen zu lesen.

In einen Lauf einbinden

if __name__ == "__main__":
    result = generate_image("Ein roter Drachen über einem nassen Strand bei Ebbe, bewölktes Licht")
    print(result)

Führe ihn aus und vergleiche mit der Ausgabe von curl. Die Struktur der Nutzlast sollte übereinstimmen. Wenn nicht, hast du eine Abweichung gefunden, die es wert ist, vor dem Weiterbauen zu klären.

Fehler behandeln statt raten

Der häufigste Integrationsfehler ist, einen Fehler zu wiederholen, der niemals erfolgreich sein wird. Teile Fehler in drei Kategorien ein und behandle sie unterschiedlich.

Authentifizierungs- und Autorisierungsfehler

Diese zeigen sich in der Regel als 401 oder 403. Ursachen sind: fehlender Header, falsch formatiertes Bearer-Präfix, widerrufener oder falsch konfigurierter Schlüssel oder ein Projekt ohne Zugriff auf das Modell. Sie sind nicht wiederholbar. Eine Wiederholung kostet nur Zeit und verschmutzt die Logs mit demselben Fehler. Korrigiere die Zugangsdaten und mache weiter.

Anfragevalidierungsfehler

Dies sind typischerweise 400-Antworten: unbekannte model- oder task-Werte, ein vom Modell nicht unterstütztes size, n außerhalb des zulässigen Bereichs, ein leerer Prompt, fehlerhaftes JSON. Auch sie sind nicht wiederholbar – dieselbe Anfrage schlägt auf dieselbe Weise fehl. Die nützliche Arbeit besteht darin, die Fehlermeldung unverändert an den Entwickler weiterzugeben, der die Anfrage geschrieben hat, statt sie in einer allgemeinen Ausnahme zu verschlucken.

Transiente Server- und Netzwerkfehler

429- und 5xx-Antworten sowie Verbindungsabbrüche und Lese-Timeouts sind die wirklich wiederholbare Kategorie. Behandle sie mit begrenztem exponentiellem Backoff und Jitter:

import time, random, requests

def post_with_retry(session, url, payload, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            r = session.post(url, json=payload, timeout=(5, 120))
            if r.status_code in (429, 500, 502, 503, 504):
                raise requests.HTTPError(f"Transienter Fehler {r.status_code}", response=r)
            r.raise_for_status()
            return r.json()
        except (requests.ConnectionError, requests.Timeout, requests.HTTPError) as exc:
            if attempt == max_attempts - 1:
                raise
            time.sleep(min(2 ** attempt + random.random(), 30))

Zwei Hinweise. Erstens: Ein HTTPError, der durch ein anderes 4xx als 429 ausgelöst wird, muss sofort nach außen geworfen werden – lass die except-Klausel keine Validierungsfehler aufnehmen. Zweitens: Befolge alle Wiederholungshinweise in der Antwort, statt eigene Verzögerungen zu erfinden.

Wiederholungen sind hier nicht idempotent

Jede wiederholte Generierung ist eine neue, abgerechnete Generierung. Wenn die Anfrage ein Timeout erleidet, kann das Bild trotzdem erzeugt und abgerechnet worden sein. Halte die Anzahl der Wiederholungen klein, protokolliere die Versuchsnummer zusammen mit den Request-Metadaten im Log und zeige lieber einen klaren Fehler an, als stillschweigend viermal dasselbe Bild zu generieren.

Praktische Hygiene für Prompts und Parameter

Der Sinn dieser Gewohnheiten ist Vergleichbarkeit: Wenn du eine Sache änderst, solltest du beurteilen können, ob die Änderung der Ausgabe dadurch verursacht wurde.

Prompts schreiben, die den Bildinhalt benennen

Beschreibe in der Reihenfolge Motiv, Szene, Beleuchtung, Komposition. Konkrete Substantive und fotografische Begriffe (wie „weiches Licht vom Nordfenster“, „geringe Schärfentiefe“) transportieren mehr Signal als gestapelte ästhetische Adjektive. Vermeide massenhafte Verneinungen im Prompt; beschreibe, was erscheinen soll.

Pro Durchlauf nur eine Variable ändern

Führe pro Projekt eine kleine Prompt-Datei und bearbeite sie zwischen den Läufen, statt von Grund auf neu zu schreiben. Wenn ein Lauf enttäuscht, ändere entweder den Prompt oder die Einstellung – nicht beides. Sonst kannst du nicht wissen, welche Änderung gewirkt hat.

Einstellungen als expliziten Vertrag behandeln

size und n beeinflussen sowohl die Ausgabe als auch die Kosten. Fixiere sie in einem Konfigurationsobjekt, statt Literale durch alle Aufrufstellen zu reichen, sodass eine Änderung des Seitenverhältnisses für das gesamte Feature nur eine einzige Bearbeitung ist. Wenn du mehrere Bilder zum Vergleichen brauchst, fordere sie in einem Aufruf an statt in mehreren – weniger Roundtrips, besser lesbare Logs.

Prompts zusammen mit der Ausgabe speichern

Speichere dauerhaft neben jedem generierten Bild den exakten Prompt-String, die Einstellungen und den Modellbezeichner. Ein Prompt, der sich nicht reproduzieren lässt, gehört zu einem Bild, das sich nicht neu generieren, debuggen oder verbessern lässt. Diese eine Gewohnheit spart mehr Zeit als jeder Prompt-Trick.

Seeds für Vergleiche setzen

Derselbe Prompt kann zwischen Läufen unterschiedliche Bilder erzeugen. Wenn du eine Änderung bewertest, vergleiche aggregierte Ergebnisse – mehrere Bilder pro Konfiguration –, statt einem einzelnen glücklichen oder unglücklichen Sample zu vertrauen.

Prompts versionieren

Behandle Prompt-Text wie Code: in Dateien speichern, Änderungen überprüfen und festhalten, welche Prompt-Version welches Asset erzeugt hat. So wird aus „Warum wurden die Bilder letzten Dienstag schlechter?“ eine beantwortbare Frage.

Checkliste für die Produktion vor dem Go-live

Ein funktionierender Request ist der leichte Teil. Die folgenden Prüfungen unterscheiden eine Demo von einer echten Integration.

  • Timeouts bei jedem Aufruf festlegen. Setze Verbindungs- und Lese-Timeout explizit und verwende niemals die Standardwerte. Ein Generierungsendpunkt ohne Lese-Timeout blockiert irgendwann einen Worker.
  • Begrenzte Wiederholungen, nur bei wiederholbaren Fehlern. Begrenze die Versuche, füge Jitter hinzu und stelle sicher, dass Validierungs- und Authentifizierungsfehler den Wiederholungspfad vollständig umgehen.
  • Schlüsselverwaltung. Lies den Schlüssel aus der Umgebung oder einem Secret Store, niemals aus dem Quellcode. Eine Rotation soll ohne Codeänderung möglich sein.
  • Strukturierte Logs. Protokolliere Modellbezeichner, Prompt (oder dessen Hash plus Referenz), Einstellungen, HTTP-Status, Versuchsnummer und jede Request-Kennung aus der Antwort. Ohne diese Angaben lassen sich Bildprobleme nicht reproduzieren.
  • Kostentransparenz. Die Generierung wird pro Ausgabe abgerechnet, daher hängt die Nutzung davon ab, wie viele Bilder du anforderst und wie oft du wiederholst. Lege vorab fest, ob Anfragen pro Nutzer, pro Aufgabe oder im Hintergrund ausgeführt werden, und verfolge die Menge entsprechend – prüfe das aktuelle Preispaneel auf der Website auf die aktuellen Tarife, statt Annahmen fest zu verdrahten.
  • Fehlerverhalten definieren. Entscheide, was Nutzer erleben, wenn die Generierung nach dem letzten Versuch fehlschlägt: Fehlerstatus, Platzhalter oder erneute Einreihung in die Warteschlange. Ein undefinierter Fallback wird zu einer undefinierten User Experience.
  • Nutzlast-Schema festnageln. Speichere und validiere die Antwortfelder, auf die du dich verlässt, damit Änderungen der Nutzlast als expliziter Fehler auftreten statt als stilles None.

Abschließende Verifikationsrunde

Führe den curl-Befehl, die Python-Funktion und eine absichtlich fehlerhafte Anfrage (zuerst ein falscher Schlüssel, dann falsche Parameter) aus und bestätige, dass jede davon den erwarteten Fehler erzeugt. Erst dieser letzte Schritt zeigt dir, ob die Fehlerbehandlung echt ist und nicht nur dekorativ.

Sobald die Anfrage authentifiziert, portiert, sinnvoll wiederholt und protokolliert ist, kann diese Integration hinter den Rest der Anwendung treten.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen