So rufen Sie muse-image-1.0/text-to-image über die HiAPI API auf: curl und Python

Was diese Integration tatsächlich umfasst

Bei HiAPI ist ein Text-to-Image-Aufruf eine einzelne synchrone HTTP-Anfrage: Sie senden einen JSON-Anfragekörper, der das gewünschte Bild beschreibt, und die Antwort enthält die generierten Bilddaten. Dieser Endpunkt hat keine Polling-Schleife und keine Job-Warteschlange, die verwaltet werden müsste – eine Anfrage, eine Antwort.

Es sind nur wenige Komponenten beteiligt:

• Ihr API-Schlüssel – authentifiziert die Anfrage über den Authorization-Header.
• Der Endpunkt – ein fester URL-Pfad für muse-image-1.0/text-to-image auf der HiAPI-Basis-URL.
• Der JSON-Anfragekörper – enthält Ihren Prompt sowie alle optionalen Parameter, die das Modell akzeptiert.
• Die Antwortnutzlast – liefert die generierten Bilddaten zurück, die Sie decodieren oder weiterleiten.

Das ist die gesamte Schnittstellenfläche. Die folgenden Abschnitte bauen die Anfrage Stück für Stück mit curl auf und wiederholen denselben Vorgang dann in Python, sodass Sie jeden Teil verifizieren können, bevor Sie Komplexität hinzufügen.

Voraussetzungen und Authentifizierung

Bevor Sie die erste Anfrage senden, stellen Sie sicher, dass Sie Folgendes haben:

1. Einen API-Schlüssel aus dem Dashboard Ihres HiAPI-Kontos. Behandeln Sie ihn wie ein Passwort; committen Sie ihn niemals in die Versionsverwaltung.
2. Einen HTTP-Client – curl zum Testen reicht aus; die Skriptversion zielt auf Python 3.8+ ab.
3. Die Basis-URL der HiAPI API, die Sie zusammen mit dem Schlüssel in der Dashboard-Dokumentation finden.

Die Authentifizierung erfolgt über ein Bearer-Token im Authorization-Header. Jede Anfrage an muse-image-1.0/text-to-image benötigt ihn:

Authorization: Bearer $HIAPI_API_KEY

Speichern Sie den Schlüssel in einer Umgebungsvariable statt ihn im Skript fest zu codieren:

export HIAPI_API_KEY="your-key-here"

Der Endpunktpfad dieses Modells ist /muse-image-1.0/text-to-image, angehängt an die Basis-URL. Die genaue Basis-URL ist in Ihrem HiAPI-Dashboard dokumentiert; speichern Sie auch sie in einer Umgebungsvariable, damit Sie die Umgebung wechseln können, ohne Code zu ändern:

export HIAPI_BASE_URL="https://api.hiapi.ai"   # confirm the current value in your dashboard

Sobald diese beiden Variablen gesetzt sind, können Sie Anfragen senden.

Eine funktionierende curl-Anfrage

Hier ist ein minimaler Aufruf von muse-image-1.0/text-to-image. Er sendet einen Prompt und schreibt die rohe JSON-Antwort in eine Datei, sodass Sie sie prüfen können, bevor Sie Parsing-Code schreiben.

curl -sS -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a quiet harbor at dawn, soft fog, wide angle",
    "n": 1
  }' \
  -o response.json

Zum Anfragekörper gibt es einige Punkte zu beachten:

• prompt ist erforderlich – er ist die Textbeschreibung, die das Modell rendert.
• n ist optional und steuert, wie viele Bilder Sie anfordern. Lassen Sie ihn weg, wird der Standardwert verwendet.
• Fügen Sie nur Parameter ein, die Sie in der HiAPI API-Referenz für dieses Modell bestätigt haben. Raten Sie keine undokumentierten Felder; unbekannte Parameter können von der Servervalidierung abgelehnt oder stillschweigend ignoriert werden.

Bei erfolgreicher Anfrage enthält response.json die Bilddaten. Bei einem Fehler erhalten Sie einen Fehler-Antwortkörper und einen Nicht-2xx-Statuscode – siehe den Abschnitt zur Fehlerbehandlung unten.

Sie können den HTTP-Statuscode prüfen, ohne den gesamten Antwortkörper auszugeben:

curl -sS -o /dev/null -w "%{http_code}\n" -X POST "$HIAPI_BASE_URL/muse-image-1.0/text-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"test"}'

Dieselbe Anfrage in Python implementieren

Die Python-Version verwendet requests und ist mit dem curl-Aufruf identisch – derselbe Endpunkt, dieselben Header, derselbe Anfragekörper. Kapseln Sie ihn in eine wiederverwendbare Funktion.

import os
import requests

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

def generate_image(prompt: str, n: int = 1) -> dict:
    url = f"{BASE_URL}/muse-image-1.0/text-to-image"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {"prompt": prompt, "n": n}

    response = requests.post(url, headers=headers, json=payload, timeout=60)
    response.raise_for_status()  # raise on 4xx/5xx
    return response.json()

if __name__ == "__main__":
    result = generate_image("a quiet harbor at dawn, soft fog, wide angle")
    print(result.keys())

Zwei Details sollten Sie beibehalten:

• timeout=60 – setzen Sie ein explizites Timeout. Die Bildgenerierung ist langsamer als ein typischer JSON-API-Aufruf; ohne Timeout kann Ihr Prozess bei einer stagnierenden Verbindung unbegrenzt hängen bleiben.
• raise_for_status() – macht HTTP-Fehler als Ausnahmen sichtbar, statt dass Sie stillschweigend einen Fehler-Antwortkörper als Bild parsen.

Wenn Sie bereits httpx oder aiohttp verwenden, ist die Umstellung unkompliziert: dieselben Header, derselbe JSON-Anfragekörper. Diese Anfrage hängt von keiner bestimmten HTTP-Bibliothek ab.

Die synchrone Antwort lesen

Da muse-image-1.0/text-to-image synchron ist, kommen die Bilddaten in derselben Antwort an – kein zweiter Aufruf zum Abrufen des Ergebnisses nötig. Die Antwort ist JSON; prüfen Sie ihre Struktur einmal, bevor Sie einen Parser schreiben:

import json

result = generate_image("a quiet harbor at dawn")
print(json.dumps(result, indent=2)[:500])

Wie Sie das Bild verarbeiten, hängt davon ab, was die Antwort enthält:

Wenn die Antwort Base64-Bilddaten enthält

Decodieren Sie den String und schreiben Sie die Bytes in eine Datei:

import base64

b64 = result["data"][0]["b64_json"]   # field name: confirm against the API reference
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

Wenn die Antwort eine URL enthält

Laden Sie sie mit einem normalen GET herunter – die URL ist für den Abruf autorisiert, hängen Sie den API-Schlüssel also nicht an einen Drittanbieter-Host an:

import requests

image_url = result["data"][0]["url"]   # field name: confirm against the API reference
img = requests.get(image_url, timeout=60)
img.raise_for_status()
with open("output.png", "wb") as f:
    f.write(img.content)

Die genauen Feldnamen – b64_json versus url und die äußere Struktur, die sie umschließt – sind in der HiAPI API-Referenz für dieses Modell definiert. Geben Sie die Antwort einmal aus, bestätigen Sie die Struktur und schreiben Sie dann den Code entsprechend. Gehen Sie nicht davon aus, dass die Strukturen verschiedener Modelle gleich sind.

Schreiben Sie im Dienst nicht blind auf die lokale Festplatte: Streamen Sie die Bytes in einen Objektspeicher oder geben Sie sie direkt an die Stelle weiter, die die Bilder konsumiert (Upload-Schritt, Warteschlange, Antwort an Ihren eigenen Client). Bevor Sie weiterleiten, prüfen Sie, ob die decodierten Bytes wie ein Bild aussehen (prüfen Sie die Magic Bytes).

Fehlercodes und Wiederholungen behandeln

HiAPI gibt standardmäßige HTTP-Statuscodes zurück. Eine nützliche Triage-Regel ist: Würde dieselbe Anfrage erfolgreich sein, wenn ich sie ohne Änderung erneut sende?

Anfrage korrigieren – nicht wiederholen

• 400 Bad Request – fehlerhaftes JSON oder ein Parameter, den das Modell nicht akzeptiert. Prüfen Sie, ob prompt vorhanden ist und ob Sie keine Felder erfunden haben. Korrigieren Sie den Anfragekörper; eine unveränderte Wiederholung schlägt genauso fehl.
• 401 Unauthorized – fehlender oder ungültiger API-Schlüssel. Prüfen Sie, ob HIAPI_API_KEY gesetzt und nicht rotiert wurde.
• 403 Forbidden – der Schlüssel ist gültig, aber hat keinen Zugriff auf diesen Endpunkt. Prüfen Sie Ihre Kontozugriffsrechte im Dashboard.
• 404 Not Found – falscher Pfad. Stellen Sie sicher, dass die Endpunktzeichenkette genau /muse-image-1.0/text-to-image lautet und die Basis-URL korrekt ist.
• 422 Unprocessable Entity – JSON ist wohlgeformt, aber semantisch ungültig, z. B. ein Wert außerhalb des zulässigen Bereichs. Lesen Sie die Fehlermeldung; sie nennt normalerweise den Feldnamen.

Wiederholen mit Backoff

• 429 Too Many Requests – Sie werden rate-limitiert. Wiederholen Sie mit exponentiellem Backoff; beachten Sie einen vorhandenen Retry-After-Header.
• 5xx-Fehler – serverseitige Störung. Wiederholen Sie mit exponentiellem Backoff und einer Obergrenze (z. B. drei Versuche), dann geben Sie auf und legen den Fehler offen.

Eine kompakte Wiederholungsschleife:

import time

def post_with_retry(url, headers, payload, attempts=3):
    for i in range(attempts):
        resp = requests.post(url, headers=headers, json=payload, timeout=60)
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(2 ** i)
            continue
        resp.raise_for_status()
        return resp.json()
    raise RuntimeError(f"failed after {attempts} attempts: {resp.status_code} {resp.text}")

Protokollieren Sie bei Fehlern immer den Statuscode und den Fehler-Antwortkörper. Die Meldung im Antwortkörper sagt Ihnen, zu welcher der beiden Kategorien ein gegebener Fehler gehört.

Produktions-Checkliste vor der Veröffentlichung

Einige Gewohnheiten machen Aufrufe von muse-image-1.0/text-to-image auch dann vorhersehbar, wenn sie Ihren Laptop verlassen:

• Anfragestruktur fixieren. Validieren Sie den JSON-Anfragekörper anhand der in der API-Referenz dokumentierten Felder. Wenn Sie einen Parameter hinzufügen, bestätigen Sie zuerst, dass er unterstützt wird.
• Timeouts überall setzen. Sowohl Generierungsaufrufe als auch alle Downloads der zurückgegebenen Bilddaten benötigen explizite Timeouts.
• Fehlerkategorien unterscheiden. Trennen Sie wiederholbare (429, 5xx) von endgültigen (400, 401, 403, 404, 422) Fehlern, damit Ihre Alarme nicht rauschen und Wiederholungen nicht verschwendet werden.
• Wichtige Informationen protokollieren. Wenn die Antwort eine Request-ID liefert, protokollieren Sie sie, den Statuscode, die Latenz und die Länge des Prompts – aber nicht den Prompt selbst, falls er sensible Texte enthalten könnte.
• Kostentreiber im Blick behalten. Die Generierung wird nach Ausgabe abgerechnet – Bildanzahl, Größe und wie häufig Sie wiederholen, beeinflussen die Kosten. Vermeiden Sie Wiederholungen bei endgültigen Fehlern und vermeiden Sie Neugenerierungen, wenn das Cachen von Ergebnissen machbar ist.
• Schlüssel serverseitig halten. Betten Sie den API-Schlüssel niemals in Browser- oder Mobile-Clients ein, um den Endpunkt direkt aufzurufen.

Damit ist die Integration eine kleine, langweilige Funktion, die Sie von überall aufrufen können – genau das wollen Sie. Die vollständige Parameterfläche und die aktuellen Antwortfelder finden Sie in der HiAPI API-Referenz für dieses Modell.