So verwendest du die grok-imagine-quality Text-zu-Bild-API: curl, Python und eine lauffähige Anfrage

Zusammenfassung

• Was das ist: Eine lauffähige Lösung zur Nutzung der grok-imagine-quality/text-to-image API auf hiapi – Aufgabe über POST /v1/tasks erstellen, GET /v1/tasks/<taskId> abfragen (oder Callback verwenden), Bild von output[0].url herunterladen.
• Schema ist strikt und schlank: prompt (erforderlich), aspect_ratio (13 Seitenverhältnisse, Standard 1:1), resolution (1k | 2k, Kleinbuchstaben, Standard 1k), output_format (jpeg | png | webp, Standard jpeg). Jedes andere Feld wird mit 400 abgelehnt.
• „Quality“ ist eine Stufe, kein Regler. Es gibt keinen Parameter quality oder rich_detail – reichere Details, Materialien und Beleuchtung bietet diese Modellvariante standardmäßig. Wenn du günstige Massenentwürfe brauchst, gibt es am selben Endpunkt das Schwestermodell in der Standardstufe grok-imagine/text-to-image.
• Ausgabe-URLs haben eine expireAt-Frist – lade rechtzeitig herunter oder speichere dauerhaft.

Was du baust und was du vorbereiten musst

Ziel: Text-Prompt an grok-imagine-quality/text-to-image senden und eine fertige Bilddatei zurückbekommen, die als Key Visual taugt – zuerst mit curl, dann als kleines Python-Skript, das in eine Task-Queue passt.

Du brauchst nur eines: einen hiapi API-Schlüssel. Hole ihn aus deiner hiapi-Konsole und exportiere ihn:

export HIAPI_API_KEY="sk-..."

Jede Anfrage authentifiziert sich über den Standard-Bearer-Header: Authorization: Bearer sk-<key>.

Minimal lauffähige Anfrage (curl)

Die Bildgenerierung auf hiapi ist ausschließlich asynchron. Du wartest nicht auf einen langen HTTP-Aufruf, sondern erstellst eine Aufgabe und holst das Ergebnis nach Abschluss ab.

Schritt 1 – Aufgabe erstellen:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-quality/text-to-image",
    "input": {
      "prompt": "Produkt-Key-Visual einer mattschwarzen Espressomaschine auf einer Schieferplatte, dramatisches gerichtetes Licht, geringe Schärfentiefe, hochwertige kommerzielle Anmutung",
      "aspect_ratio": "16:9",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Während das Modell im Hintergrund arbeitet, erhältst du sofort eine taskId:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR" }
}

Schritt 2 – Abfragen bis zum Endzustand:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Die Aufgabe durchläuft queued → handling → archiving und endet schließlich in success oder fail. Nur success enthält eine Ausgabe:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "grok-imagine-quality/text-to-image",
    "status": "success",
    "created": 1783130400,
    "completed": 1783130460,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../image.png",
        "type": "image",
        "expireAt": 1783735260
      }
    ]
  }
}

Schritt 3 – Vor expireAt herunterladen:

curl -o hero.png "https://cdn.hiapi.ai/tasks/.../image.png"

Derselbe Ablauf in Python

Ein vollständiges Skript – erstellen, abfragen, speichern. Kopieren, HIAPI_API_KEY setzen, ausführen.

import os
import time

import requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "grok-imagine-quality/text-to-image",
    "input": {
        "prompt": (
            "Produkt-Key-Visual einer mattschwarzen Espressomaschine auf einer Schieferplatte, "
            "dramatisches gerichtetes Licht, geringe Schärfentiefe, hochwertige kommerzielle Anmutung"
        ),
        "aspect_ratio": "16:9",
        "resolution": "2k",       # Kleinbuchstaben! "2K" wird mit 400 abgelehnt
        "output_format": "png",
    },
}

resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
resp.raise_for_status()  # 4xx hier = die Anfrage selbst wurde abgelehnt
task_id = resp.json()["data"]["taskId"]
print("Aufgabe erstellt:", task_id)

while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    status = task["status"]
    if status == "success":
        image = task["output"][0]
        with open("hero.png", "wb") as f:
            f.write(requests.get(image["url"], timeout=120).content)
        print("hero.png gespeichert")
        break
    if status == "fail":
        err = task["error"]
        raise RuntimeError(f"Aufgabe fehlgeschlagen: {err['code']} {err['message']}")
    time.sleep(5)  # queued / handling / archiving – weiter abfragen

Die Generierung in der 2k-Stufe ist meist in ein bis zwei Minuten abgeschlossen; ein Abfrageintervall von 5 Sekunden reicht aus.

Die tatsächlich vorhandenen Parameter

Das Eingabe-Schema ist strikt – unbekannte Felder schlagen mit 400 INVALID_REQUEST: additional properties not allowed fehl, statt still ignoriert zu werden. Das ist eine gute Nachricht: Tippfehler schaffen es nicht in die Produktion. Der vollständige Schnittstellenumfang:

Feld	Erforderlich	Werte	Standardwert
input.prompt	Ja	Freitext	—
input.aspect_ratio	Nein	2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2	1:1
input.resolution	Nein	1k, 2k (nur Kleinbuchstaben)	1k
input.output_format	Nein	jpeg, png, webp	jpeg

Drei Dinge solltest du wissen, bevor du darauf aufbaust:

• Das „quality“ im Namen ist eine Stufe, kein Parameter. Du wirst dieses Modell vielleicht mit reicheren Details, Materialien und Beleuchtung beschrieben sehen – das ist die Modellvariante selbst. Es gibt kein umschaltbares Feld rich_detail, quality oder style.
• 1k und 2k werden zu unterschiedlichen Stufen abgerechnet. Häufiges Muster: Prompts in 1k wiederholt durchiterieren und dann den Gewinner-Prompt in 2k erneut ausführen, um das finale Material zu erzeugen. Aktuelle Preise pro Bild findest du auf der hiapi-Preisseite.
• Kein n, kein seed, kein negative_prompt. Eine Aufgabe erzeugt ein Bild. Für Varianten mehrere Aufgaben parallel einreichen – sie sind unabhängig und werden nebenläufig eingereiht.

Produktionshinweise: Callbacks, Idempotenz und Fehler

In der Produktion Callbacks statt Polling bevorzugen. Übergib callback auf oberster Ebene des Request-Bodys (nicht innerhalb von input); hiapi ruft deinen Dienst auf, sobald die Aufgabe einen Endzustand erreicht:

{
  "model": "grok-imagine-quality/text-to-image",
  "input": { "prompt": "..." },
  "callback": {
    "url": "https://your-service.example.com/hiapi/callback",
    "when": "final"
  }
}

Mit when: "final" werden sowohl success als auch fail benachrichtigt – dedupliziere daher auf deiner Seite anhand der taskId. Behalte ein niederfrequentes Polling als Fallback bei, falls ein Callback verloren gehen kann – der Task-Detail-Endpunkt ist stets die Quelle der Wahrheit.

Mache Wiederholungen mit Idempotency-Key sicher. Die Aufgabenerstellung akzeptiert den Header Idempotency-Key (maximal 255 Byte). Wiederholungen mit demselben Key erzeugen niemals doppelte Aufgaben – ein Replay liefert die ursprüngliche taskId zurück:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Idempotency-Key: order-42-hero-image" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-imagine-quality/text-to-image", "input": {"prompt": "..."}}'

Unterscheide drei Fehlerformen bei der Behandlung:

1. Authentifizierungsfehler – HTTP 401 und {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}. Prüfe den Schlüssel und ob er für dieses Modell berechtigt ist; nicht blind wiederholen.
2. Ungültige Eingabe – HTTP 400 und "error_code": "INVALID_REQUEST", die Meldung benennt das konkrete Feld (z. B. resolution: value must be one of '1k', '2k'). Korrigiere den Payload; eine Wiederholung mit demselben Request-Body schlägt genauso fehl.
3. Fehler auf Aufgabenebene – der Erstellungsaufruf ist erfolgreich, aber die Aufgabe endet mit status: "fail" und einem data.error-Objekt. Prüfe error.code, bevor du erneut einreichst.

Achte auf expireAt. Ausgabe-URLs sind temporär. Lade die Datei sofort nach erfolgreicher Aufgabe herunter oder übergib beim Erstellen storage: "persistent", um die Ausgabe langfristig zu behalten.

Verwandte Seiten

• Modellseite grok-imagine-quality/text-to-image – Spielwiese und Preisgestaltung nach Stufe
• Vollständige Parameterreferenz in der Dokumentation
• API-Referenz zur Aufgabenerstellung – Header, Idempotenz, Callbacks
• So nutzt du grok-imagine-quality für Bild-zu-Bild – dieselbe Stufe, Bearbeitung vorhandener Bilder
• Alle Bild-, Video- und Musikmodelle

Häufige Fragen

Was ist der Unterschied zwischen grok-imagine-quality und grok-imagine/text-to-image? Gleicher Endpunkt, gleiche Request-Struktur, unterschiedliche Stufe. Die Quality-Stufe ist auf Key Visuals und kommerzielles Material mit reicheren Details und Beleuchtung ausgerichtet und wird nach den Auflösungsstufen 1k/2k abgerechnet; die Standardversion grok-imagine/text-to-image ist die schnellere, günstigere Option für Massen und Ideenfindung.

Warum gibt "resolution": "2K" einen 400 zurück? Die Enumeration ist case-sensitiv und in Kleinbuchstaben: 1k oder 2k. Großbuchstaben werden mit INVALID_REQUEST abgelehnt.

Kann ich exakte Pixelmaße wie 1920x1080 festlegen? Nein. Du steuerst die Form über aspect_ratio (13 Optionen, von 2:1 ultrabreit bis 9:20 ultrahoch) und die Schärfe über die Stufen 1k/2k. Dieses Modell hat kein freies size-Feld.

Kann ich in einer Anfrage mehrere Bilder erzeugen? Nein – es gibt keinen n-Parameter. Reiche mehrere Aufgaben parallel ein; jede Aufgabe liefert ihre eigene taskId und wird nebenläufig verarbeitet.

Unterstützt grok-imagine-quality Bild-zu-Bild? Ja, mit einer separaten Modell-ID: grok-imagine-quality/image-to-image. Ihr Schema findest du in der Bild-zu-Bild-Lösung – es unterscheidet sich von Text-zu-Bild.

Wie lange sind Ergebnis-URLs gültig? Jeder Eintrag in output[] hat einen expireAt-Unix-Zeitstempel. Lade vor dieser Frist herunter oder nutze beim Erstellen der Aufgabe storage: "persistent" (oder stufe die Ausgabe später hoch), um sie zu behalten.

Wie sieht eine eingereihte, aber noch nicht abgeschlossene Aufgabe aus? GET /v1/tasks/<taskId> liefert einen status von queued, handling oder archiving, noch ohne output. Nur success enthält eine herunterladbare Ausgabe; fail enthält data.error.