Grok Imagine 2.0 Ext
Grok Imagine 2.0 Ext Bildgenerierung
- Asynchrone Text-zu-Bild-Generierung; Ergebnis per task_id abfragen
- 1–12 Bilder pro Anfrage; Abrechnung pro erfolgreich geliefertem Bild ($0.08/Stück)
- Nur URL-Ausgabe; kein Bild-zu-Bild / Streaming
- Bild-URLs sind 72 Stunden gültig
POST
Text-zu-Bild · asynchrone Aufgaben. Senden Sie
Modellname fest:
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.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-extstring
erforderlich
Prompt. Nach Trim darf er nicht leer sein. Vor dem Absenden trimmen.
integer
Standard:"1"
Bildanzahl:
1–12. 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
1K / 2K / 4K-Pixel-Tier; Bildausschnitt und Verhältnis steuert size.string
Standard:"url"
Nur
url ist erlaubt. Darf weggelassen werden. b64_json / base64 → 400 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 SieX-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.idzum Pollenrequest_idfür Gateway-Debugging- den
Idempotency-Keyfür sichere Retries bei unklarem Ergebnis - die originalen Anfrageparameter für UI / Support
Idempotenz und sichere Retries
Bildgenerierung ist kostenpflichtig — dringend empfohlen istIdempotency-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
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
- Für die Anzeige
url[]verwenden; bein>1alle Einträge durchlaufen - Nur indexweise paaren, wenn
image_ids.length === url.length - Fehlende
image_idserlauben weiterhin die Anzeige - Links gelten 72 Stunden — zeitnah herunterladen; zusätzlich
expires_atvertrauen
Abrechnung
Grundpreis $0.08 pro Bild (erfolgreiche Lieferungen):- UI vor dem Absenden sollte „Schätzung“ anzeigen; finaler USD-Betrag ist
data.cost data.credits_costist 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
resolutionableiten; dieses Modell hat einen flachen Stückpreis
Webhook (optional)
- Geben Sie eine Basis-URL an; die Plattform ruft
{base}/callbackauf - Muss öffentlich erreichbar sein und SSRF-Prüfungen bestehen
- Ist
webhook_secretgesetzt, lautet die Signaturhex(HMAC-SHA256(secret, raw_body))über die Rohbytes - Callback-Body entspricht dem
datader 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.