Wie verwende ich die Grok Image 2.0 Text-zu-Bild-API? In 5 Minuten zum ersten Bild

Wie verwende ich die Grok Image 2.0 Text-zu-Bild-API? In drei Schritten: POST /v1/tasks erstellt einen Task, nach Erhalt der taskId pollst du (oder setzt einen Callback) und lädst das fertige Bild von data.output[0].url herunter. Ein Bild kostet $0.052, 1K und 2K zum selben Preis.

Grok Image 2.0 ist bei HiAPI verfügbar. Öffne die Modellseite und generiere direkt; neue Nutzer erhalten bei der Registrierung 200 Credits, genug für 1 Bild zum Ausprobieren.

TL;DR

• Was es ist: grok-imagine-image-2.0/text-to-image, ein Text-zu-Bild-Modell von xAI, das die einheitliche asynchrone Task-Schnittstelle von HiAPI nutzt.
• Was es kostet: $0.052 pro Bild, für 1K / 2K, low / medium und jedes Seitenverhältnis derselbe Preis; abgerechnet wird pro erfolgreich generiertem Bild, bei Fehlschlag automatische Rückerstattung. Für $10 gibt es ca. 192 Bilder.
• So rufst du es am schnellsten auf: Ein prompt genügt; optional sind die drei Parameter aspect_ratio, resolution und quality.

Welche Parameter hat Grok Image 2.0 Text-zu-Bild?

input enthält nur vier Felder:

Feld	Erforderlich	Werte	Beschreibung
prompt	Ja	String	Bildbeschreibung
aspect_ratio	Nein	1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 2:1, 1:2, 19.5:9, 9:19.5, 20:9, 9:20, auto	Standard 1:1
resolution	Nein	1k, 2k	Standard 1k
quality	Nein	low, medium	Standard medium; medium hat mehr Details, low ist schneller

Jeder Task liefert 1 Bild; für Stapelverarbeitung mehrere Tasks parallel einreichen. Felder oder Werte außerhalb der obigen Tabelle führen zu 400, die Fehlermeldung nennt das konkrete Feld.

Zwei Wege: online testen und API

Online testen (1 Minute)

1. Öffne die Text-zu-Bild-Modellseite und melde dich an.
2. Gib den Prompt ein und wähle Seitenverhältnis und Auflösung.
3. Klicke auf „Ausführen“, und nach erfolgreichem Task siehst du das Bild und kannst es herunterladen.

API-Integration (5 Minuten)

1. Erstelle einen API Key in der Konsole.
2. Reiche den Task mit POST /v1/tasks ein.
3. Polls GET /v1/tasks/<taskId> oder setze einen Callback.
4. Lade bei Erfolg sofort data.output[0].url herunter.

Product photography of a matte black ceramic coffee mug filled with steaming black coffee, thin wisps of steam curling upward, mug placed on a warm honey-toned wooden table near a bright window with sheer curtains, soft natural window light from the left creating gentle highlights on the mug's curved surface, shallow depth of field with the background softly blurred, plenty of empty negative space to the right of the mug for text overlay, warm cozy morning color grade, realistic commercial photography style, 3:2 aspect ratio

Zunächst ein Prompt, der direkt läuft: Das Folgende ist ein Produktbild im Format 3:2, generiere mit diesem Prompt → (Verhältnis 3:2, Auflösung 2K)

curl und Python: das erste Bild zum Laufen bringen

Setze zuerst den API Key:

export HIAPI_API_KEY="sk-..."

Alle Anfragen tragen Authorization: Bearer sk-<key>. Die Bildgenerierung ist asynchron und nutzt dieselbe Task-Schnittstelle wie die anderen Modelle von HiAPI.

Schritt 1: Task erstellen:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/text-to-image",
    "input": {
      "prompt": "A red apple on a wooden table, studio lighting, shallow depth of field",
      "aspect_ratio": "16:9",
      "resolution": "2k"
    }
  }'

Gibt sofort eine taskId zurück:

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

Schritt 2: bis zum Endzustand pollen:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JGSGB818MX59GVZZCVH67 \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Prüfe data.status: success bedeutet Erfolg, fail bedeutet Fehlschlag; bei anderen Status weiter warten. Beispiel einer erfolgreichen Antwort:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JGSGB818MX59GVZZCVH67",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JGSGB818MX59GVZZCVH67-0.jpg",
        "artifactId": "76710",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Achte auf storage: "temp" und expireAt: Die Bild-URL ist temporär; lade das Bild direkt nach Abschluss des Tasks herunter oder speichere es in deinem eigenen Objektspeicher.

Python-Version:

Installiere zuerst requests (python3 -m pip install requests) und setze den obigen HIAPI_API_KEY. Das Skript pollt maximal 10 Minuten; nach dem Timeout behältst du die taskId und fragst weiter ab.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def generate_image(prompt: str, aspect_ratio: str = "1:1", resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/text-to-image",
            "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = generate_image("A red apple on a wooden table, studio lighting", resolution="2k")
    print(url)

Was ist vor dem Go-live zu beachten?

• Für Stapelverarbeitung Callbacks verwenden, nicht in enger Schleife pollen. Gib beim Erstellen des Tasks callback an, dann pusht HiAPI nach Abschluss an deine Adresse:

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

  when: "final" benachrichtigt, wenn der Task den Endzustand Erfolg oder Fehlschlag erreicht; der Empfänger dedupliziert nach taskId. Für interaktive Seiten Polling, für Stapelverarbeitung Callbacks.

• Bild sofort sichern. data.output[0].url ist eine temporäre Adresse und läuft gemäß expireAt ab.

• Einen Task nur einmal einreichen. Speichere nach der Antwort die Zuordnung zwischen taskId und deinem Geschäftsvorgang; wiederholtes Einreichen kann mehrere Tasks anlegen und jeweils berechnen. Wenn die Erstellungsanfrage in einen Timeout läuft und keine ID zurückkommt, prüfe zuerst die Task-Aufzeichnungen, bevor du entscheidest, ob du erneut einreichst.

• resolution explizit angeben. Standard ist 1k; 1K und 2K kosten gleich, für finale Bilder direkt "resolution": "2k" übergeben.

• Prompts mit quality: low abstimmen. Gleicher Preis, schnellere Antwort; erst für die finale Version auf medium wechseln.

• Fehlerbehandlung. Prüfe zuerst den HTTP-Status und code, message in der Antwort, dann lies data. Bei Parameter- oder Authentifizierungsfehlern korrigiere und reiche erneut ein; wenn der Task fail zurückgibt, protokolliere den Fehler und beende das Polling.

Weiterlesen

• Was kostet die Grok Image 2.0 API? Text-zu-Bild $0.052 pro Bild, 2K ohne Aufpreis
• Grok Image 2.0 Text-zu-Bild-Prompts: 5 Szenarien zum direkten Kopieren
• Grok Image 2.0 Bild-zu-Bild-API: Bildbearbeitung mit einem Referenzbild
• Grok Image 2.0 vs GPT Image 2: Vergleich mit identischen Prompts
• Authentifizierung und Schnellstart

Häufige Fragen

Wie schreibt man die Modell-ID? Schreibe die vollständige grok-imagine-image-2.0/text-to-image, mit Versionsnummer 2.0 und /text-to-image.

Was tun bei "additional properties not allowed"? input akzeptiert nur die vier Felder prompt, aspect_ratio, resolution, quality. Die bei anderen Modellen üblichen size, n, seed, negative_prompt, output_format sind hier nicht verfügbar; einfach löschen.

Kann man mehrere Bilder auf einmal erzeugen? Nein, jeder Task liefert 1 Bild. Für mehrere Bilder mehrere Tasks parallel einreichen.

Wie lange ist die Ausgabe-URL gültig? Temporärer Speicher; expireAt in der Antwort ist ein Unix-Zeitstempel. Lade oder sichere das Bild direkt nach Erfolg des Tasks.

Muss man synchron auf das Ergebnis warten? Nein. Die Erstellungs-Schnittstelle kehrt sofort zurück, nachdem der Task in die Warteschlange gestellt wurde; kurze Skripte pollen GET /v1/tasks/<taskId>, in der Produktion setzt man callback.

Kosten fehlgeschlagene Tasks Geld? Nein, abgerechnet wird pro erfolgreich generiertem Bild, bei Fehlschlag automatische Rückerstattung. Wenn data.status fail ist, beende das Polling.

Erzeuge jetzt dein erstes Bild

Setze zuerst HIAPI_API_KEY, erstelle den Task mit dem obigen curl und frage dann mit der zurückgegebenen data.taskId ab; bei Erfolg lädst du von data.output[0].url herunter. Wenn du zuerst das Ergebnis sehen möchtest, öffne die Text-zu-Bild-Modellseite; die 200 Credits aus der Registrierung reichen für 1 Bild.