Skip to main content
POST
Text-zu-Bild · asynchrone Aufgaben. Senden Sie POST /v1/images/generations und pollen Sie anschließend Aufgabenstatus abrufen.
Modellname fest: grok-imagine-2.0-ext. Nicht unterstützt: Referenzbilder, stream sowie response_format-Werte außer url.
Legen Sie API-Keys nicht in Browser-Bundles ab (VITE_* / NEXT_PUBLIC_*, LocalStorage usw.). Rufen Sie aus dem Browser idealerweise nur Ihr eigenes BFF auf; der APIMart-Key bleibt auf dem Server.

Fähigkeiten und Grenzen

Authentifizierung und empfohlene Header

string
erforderlich
Bearer-Token. Schlüssel auf der API-Key-Seite erstellen.

Anfrageparameter

string
erforderlich
Fester Wert: grok-imagine-2.0-ext
string
erforderlich
Prompt. Nach Trim darf er nicht leer sein. Vor dem Absenden trimmen.
integer
Standard:"1"
Bildanzahl: 112. Explizites 0 führt zu einem Fehler. Weglassen → 1.
string
Seitenverhältnis. Bevorzugen Sie Verhältnis-Strings (UI sollte nur Verhältnisse anzeigen):Pixel-Aliase: 1024x1024 (1:1), 1024x1792 (2:3), 1792x1024 (3:2), 720x1280 (9:16), 1280x720 (16:9).Werte außerhalb der Whitelist liefern 400 invalid_size (z. B. 1:2, 2:1, 4:5, auto).
Die tatsächlichen Pixel zu einem Verhältnis können von der Alias-Tabelle abweichen (z. B. kann 1:1 1408×1408 zurückgeben). Vertrauen Sie dem zurückgegebenen Bild; leiten Sie size nicht aus gemessenen Pixeln um.
string
Qualitätsmodus-Feld. Verifizierter Wert: quality.
  • Weglassen (Modell ist standardmäßig im Qualitätsmodus), oder
  • Explizit resolution: "quality" senden
Kein 1K / 2K / 4K-Pixel-Tier; Bildausschnitt und Verhältnis steuert size.
Senden Sie kein öffentliches Feld quality — Sie erhalten 400 invalid_quality. Verwenden Sie resolution.
string
Standard:"url"
Nur url ist erlaubt. Darf weggelassen werden. b64_json / base64400 invalid_response_format.
string
Optionale öffentliche HTTPS-Basis-URL. Bei Endstatus sendet die Plattform einen POST an {webhook}/callback. Nur serverseitig — siehe Webhook.

Nicht unterstützte Parameter

Bauen Sie Anfragen mit einer Whitelist; leiten Sie kein generisches Formularobjekt anderer Bildmodelle weiter.

Anfragebeispiele

Minimal

Empfohlen

Submit-Antwort

Bevorzugen Sie X-APIMart-Response-Version: 2026-07-27. Erfolg ist HTTP 202; die Task-ID steht in data.id (verlassen Sie sich nicht auf das Legacy-Format data[0].task_id). Speichern Sie:
  • data.id zum Pollen
  • request_id für Gateway-Debugging
  • den Idempotency-Key für sichere Retries bei unklarem Ergebnis
  • die originalen Anfrageparameter für UI / Support

Idempotenz und sichere Retries

Bildgenerierung ist kostenpflichtig — dringend empfohlen ist Idempotency-Key (1–191 druckbare ASCII-Zeichen; UUID ist am einfachsten; Aufbewahrung ca. 24 Stunden). Bei POST-Netzwerk-Timeout, wenn unklar ist, ob der Server den Job angenommen hat, erzeugen Sie nicht sofort einen neuen Key — Retry mit demselben Key / Body / Response-Version.

Aufgaben pollen

Optionaler Parameter language: zh / en / ko / ja (nur Lokalisierung von Fehlermeldungen). Siehe Aufgabenstatus abrufen.

Statuswerte

Ca. alle 2 Sekunden pollen; Obergrenze etwa 10 Minuten oder 120 Versuche. Bei 429 den Header Retry-After beachten. Aufgaben werden standardmäßig ca. 3 Tage aufbewahrt — Task-ID behalten, falls der Client timeoutet.

Beispiel für abgeschlossene Aufgabe

url und image_ids parsen

  1. Für die Anzeige url[] verwenden; bei n>1 alle Einträge durchlaufen
  2. Nur indexweise paaren, wenn image_ids.length === url.length
  3. Fehlende image_ids erlauben weiterhin die Anzeige
  4. Links gelten 72 Stunden — zeitnah herunterladen; zusätzlich expires_at vertrauen

Abrechnung

Grundpreis $0.08 pro Bild (erfolgreiche Lieferungen):
  • UI vor dem Absenden sollte „Schätzung“ anzeigen; finaler USD-Betrag ist data.cost
  • data.credits_cost ist die Credits-Sicht (aktuell ca. USD × 10)
  • Vorabbuchung nach angeforderter Anzahl; Abrechnung nach erfolgreicher Anzahl (Teilerstattung bei Teilfehlern)
  • Vollständiger Fehler: cost=0, Vorabbuchung erstattet
  • Keine Preisschlüssel aus resolution ableiten; dieses Modell hat einen flachen Stückpreis

Webhook (optional)

  • Geben Sie eine Basis-URL an; die Plattform ruft {base}/callback auf
  • Muss öffentlich erreichbar sein und SSRF-Prüfungen bestehen
  • Ist webhook_secret gesetzt, lautet die Signatur hex(HMAC-SHA256(secret, raw_body)) über die Rohbytes
  • Callback-Body entspricht dem data der Aufgabenabfrage (ohne zusätzlichen {code,data}-Wrapper)
  • Behalten Sie trotzdem niedrigfrequentes Pollen als Fallback

Häufige Fehler

Für die UI bevorzugt error.message verwenden. Authentifizierungs-Internals nicht an Endnutzer weitergeben.

Unterschiede zu 1.5 (Kurzüberblick)