> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
**Text-zu-Bild · asynchrone Aufgaben.** Senden Sie `POST /v1/images/generations` und pollen Sie anschließend [Aufgabenstatus abrufen](/de/api-reference/tasks/status).\
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.
```bash cURL theme={null}
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
```
```python Python theme={null}
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer ",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
```
```javascript JavaScript theme={null}
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer ",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
```
```json 202 theme={null}
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
```
```json 400 theme={null}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
```
```json 401 theme={null}
{
"error": {
"code": 401,
"message": "Authentication failed. Please check your API key",
"type": "authentication_error"
}
}
```
```json 402 theme={null}
{
"error": {
"code": 402,
"message": "Insufficient balance. Please top up and try again",
"type": "payment_required"
}
}
```
```json 429 theme={null}
{
"error": {
"code": 429,
"message": "Too many requests. Please try again later",
"type": "rate_limit_error"
}
}
```
## Fähigkeiten und Grenzen
| Dimension | Vertrag |
| ----------------- | ----------------------------------------------------------------------------------- |
| Modell | Fest `grok-imagine-2.0-ext` |
| Fähigkeit | **Nur Text-zu-Bild** |
| Modus | Asynchrone Aufgabe |
| Anzahl `n` | `1`–`12`, Standard `1` |
| `size` | 7 Seitenverhältnisse + 5 Pixel-Aliase (siehe unten) |
| Ausgabe | Nur `response_format=url` (auch Standard) |
| Qualität | Öffentliches Feld `resolution`; verifizierter Wert `quality` |
| Nicht unterstützt | Bild-zu-Bild, `stream=true`, öffentliches `quality`, `style`, `b64_json` / `base64` |
| Abrechnung | Fester Stückpreis; Abrechnung nach **erfolgreich gelieferten** Bildern |
## Authentifizierung und empfohlene Header
Bearer-Token. Schlüssel auf der [API-Key-Seite](https://apimart.ai/keys) erstellen.
```
Authorization: Bearer YOUR_API_KEY
```
| Header | Hinweise |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type` | `application/json` (Absenden) |
| `Accept` | `application/json` |
| `Idempotency-Key` | Dringend empfohlen. Neue UUID pro vom Nutzer bestätigter Generierung; Netzwerk-Retries **müssen** denselben Key und Body wiederverwenden |
| `X-APIMart-Response-Version` | Bevorzugt `2026-07-27` für eine stabile Submit-Struktur (`data.id`) |
## Anfrageparameter
Fester Wert: `grok-imagine-2.0-ext`
Prompt. Nach Trim darf er nicht leer sein. Vor dem Absenden trimmen.
Bildanzahl: `1`–`12`. Explizites `0` führt zu einem Fehler. Weglassen → `1`.
Seitenverhältnis. **Bevorzugen Sie Verhältnis-Strings** (UI sollte nur Verhältnisse anzeigen):
| `size` | Ausrichtung | Typische Nutzung |
| ------ | ----------- | ----------------------- |
| `1:1` | Quadrat | Produkt, Avatar |
| `2:3` | Hochformat | Poster, Ganzkörper |
| `3:2` | Querformat | Foto, breite Szene |
| `3:4` | Hochformat | E-Commerce, Personen |
| `4:3` | Querformat | Anzeigebilder |
| `9:16` | Vertikal | Story / Kurzvideo-Cover |
| `16:9` | Breitbild | Banner, Video-Cover |
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.
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`.
Nur `url` ist erlaubt. Darf weggelassen werden. `b64_json` / `base64` → `400 invalid_response_format`.
Optionale öffentliche HTTPS-**Basis-URL**. Bei Endstatus sendet die Plattform einen POST an `{webhook}/callback`. Nur serverseitig — siehe [Webhook](#webhook-optional).
### Nicht unterstützte Parameter
| Parameter | Verhalten |
| ------------------------------------------ | ---------------------------------------------- |
| `quality` | `400 invalid_quality` → `resolution` verwenden |
| `style` | `400 invalid_style` |
| `image_urls` / `image_with_roles` | `400 invalid_image_input` |
| `stream: true` | `400 invalid_stream` |
| `response_format: "b64_json"` / `"base64"` | `400 invalid_response_format` |
Bauen Sie Anfragen mit einer Whitelist; leiten Sie kein generisches Formularobjekt anderer Bildmodelle weiter.
## Anfragebeispiele
### Minimal
```json theme={null}
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo"
}
```
### Empfohlen
```json theme={null}
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}
```
## 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).
| Szenario | Verhalten | Aktion |
| --------------------------------------------- | --------------------------------------------- | ------------------------------------------------------ |
| Gleicher Key + gleicher Body bereits erledigt | Replay; Header `Idempotency-Replayed: true` | Dieselbe Task-ID verwenden |
| Gleicher Key noch in Bearbeitung | `409 idempotency_in_progress` + `Retry-After` | Warten, mit **gleichem Key und Body** erneut versuchen |
| Gleicher Key, anderer Body | `409 idempotency_key_reused` | Neuer logischer Job braucht einen neuen Key |
| Ergebnis unbestimmt | `409 idempotency_result_indeterminate` | Keinen neuen Key erzeugen; mit dem alten untersuchen |
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
```http theme={null}
GET /v1/tasks/{task_id}?language=en
Authorization: Bearer YOUR_API_KEY
Accept: application/json
```
Optionaler Parameter `language`: `zh` / `en` / `ko` / `ja` (nur Lokalisierung von Fehlermeldungen). Siehe [Aufgabenstatus abrufen](/de/api-reference/tasks/status).
### Statuswerte
| `status` | Endstatus | Behandlung |
| ------------------------ | :-------: | ----------------------------------------------------------------- |
| `pending` / `processing` | Nein | Weiter pollen (`result` kann fehlen — kein Fehler) |
| `completed` | Ja | `result.images` parsen |
| `failed` | Ja | `error.message` anzeigen; `cost` ist `0` (Vorabbuchung erstattet) |
| `unknown` | Nein | Kurze Retries; bei Anhalten Support mit Task-ID kontaktieren |
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
```json theme={null}
{
"code": 200,
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"status": "completed",
"progress": 100,
"created": 1786419262,
"completed": 1786419275,
"actual_time": 13,
"estimated_time": 100,
"cost": 0.08,
"credits_cost": 0.8,
"result": {
"images": [
{
"expires_at": 1786505675,
"url": [
"https://example.com/image/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg"
],
"image_ids": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
]
}
]
}
}
}
```
### `url` und `image_ids` parsen
```text theme={null}
result.images[]
├─ url[] ← maßgebliches Anzeige-/Download-Feld (Array)
├─ image_ids[] ← optionale opake IDs
└─ expires_at ← Unix-Sekunden; für JS Date mit 1000 multiplizieren
```
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):
| `n` | Geschätzter Grundbetrag |
| --: | ----------------------: |
| 1 | \$0.08 |
| 4 | \$0.32 |
| 8 | \$0.64 |
| 12 | \$0.96 |
* 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)
```json theme={null}
{
"webhook": "https://your-service.example.com/apimart"
}
```
* 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
| HTTP | `error.code` | Ursache | Aktion |
| ---: | ------------------------- | ------------------------------- | ---------------------------------------------- |
| 400 | `invalid_request` | Leerer Prompt / ungültiges JSON | Eingabe validieren |
| 400 | `invalid_n` | `n` außerhalb 1–12 | Anzahl begrenzen |
| 400 | `invalid_size` | Size nicht auf Whitelist | Feste Select-Optionen |
| 400 | `invalid_response_format` | Nicht `url` | Korrigieren oder weglassen |
| 400 | `invalid_quality` | Öffentliches `quality` gesendet | `resolution` verwenden |
| 400 | `invalid_style` | `style` gesendet | Entfernen |
| 400 | `invalid_image_input` | Referenzbilder | Anderes Modell wählen |
| 400 | `invalid_stream` | `stream=true` | Entfernen |
| 400 | `invalid_idempotency_key` | Ungültiger Key | UUID verwenden |
| 401 | Auth-Fehler | Ungültiger Key | Server-Credentials prüfen |
| 402 | Zahlung erforderlich | Guthaben zu niedrig | Aufladen |
| 409 | `idempotency_*` | Idempotenz-Konflikt | Siehe Tabelle oben |
| 429 | Rate Limit | Zu schnell | `Retry-After` beachten |
| 5xx | Serverfehler | — | Idempotency-Key behalten; nicht blind rotieren |
Für die UI bevorzugt `error.message` verwenden. Authentifizierungs-Internals nicht an Endnutzer weitergeben.
## Unterschiede zu 1.5 (Kurzüberblick)
| Punkt | Grok Imagine 1.5 | 2.0 Ext |
| ------------- | ------------------------------- | ---------------------------------------------------- |
| Modell | `grok-imagine-1.5-apimart` usw. | `grok-imagine-2.0-ext` |
| Bild-zu-Bild | Unterstützt (siehe 1.5-Docs) | **Nicht unterstützt** |
| Anzahl | Siehe 1.5-Docs | **1–12** |
| Qualitätsfeld | Siehe 1.5-Docs | `resolution` (`quality`); nie öffentliches `quality` |
| Ausgabe | Siehe 1.5-Docs | **Nur URL** |
| URL-TTL | Siehe 1.5-Docs (oft 24 h) | **72 Stunden** |
| Stückpreis | Siehe 1.5-Docs | **\$0.08 / Bild** |