> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/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 

> [!NOTE]
>
> **Text-zu-Bild · asynchrone Aufgaben.** Senden Sie `POST /v1/images/generations` und pollen Sie anschließend [Aufgabenstatus abrufen](https://gccai.heqingsong.uk/de/api-reference/tasks/status.md).\
> Modellname fest: `grok-imagine-2.0-ext`. **Nicht unterstützt**: Referenzbilder, `stream` sowie `response_format`-Werte außer `url`.

> [!NOTE]
>
> Informationen zu Objektebenen und der Bearbeitung ausgewählter Bereiche finden Sie unter [Ebenen- und Bereichsbearbeitung](https://gccai.heqingsong.uk/de/api-reference/images/grok-imagine-2.0-ext/layer-region-edit.md).

> [!WARNING]
>
> 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 GccAi-Key bleibt auf dem Server.

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
  --header 'X-GccAi-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://gccai.heqingsong.uk/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 <token>",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Idempotency-Key": str(uuid.uuid4()),
    "X-GccAi-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://gccai.heqingsong.uk/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 <token>",
  "Content-Type": "application/json",
  Accept: "application/json",
  "Idempotency-Key": crypto.randomUUID(),
  "X-GccAi-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

**Authorization** `string` *required*

Bearer-Token. Schlüssel auf der [API-Key-Seite](https://gccai.heqingsong.uk/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-GccAi-Response-Version` | Bevorzugt `2026-07-27` für eine stabile Submit-Struktur (`data.id`) |

## Anfrageparameter

**model** `string` *required*

Fester Wert: `grok-imagine-2.0-ext`

**nsfw\_check** `boolean` (default: false)

Legt fest, ob der Inhalt vor dem Absenden des Bildauftrags moderiert wird.

* `true`: Prompts und Eingabebilder mit `omni-moderation-latest` prüfen
* `false` oder nicht angegeben: keine Moderationsanfrage und damit keine zusätzlichen Moderationskosten oder Verzögerung (Standard)

**prompt** `string` *required*

Prompt. Nach Trim darf er nicht leer sein. Vor dem Absenden trimmen.

**n** `integer` (default: 1)

Bildanzahl: `1`–`12`. Explizites `0` führt zu einem Fehler. Weglassen → `1`.

**size** `string`

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`).

> [!NOTE]
>
> 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.

**resolution** `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`.

> [!WARNING]
>
> Senden Sie kein öffentliches Feld `quality` — Sie erhalten `400 invalid_quality`. Verwenden Sie `resolution`.

**response\_format** `string` (default: url)

Nur `url` ist erlaubt. Darf weggelassen werden. `b64_json` / `base64` → `400 invalid_response_format`.

**webhook** `string`

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-GccAi-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](https://gccai.heqingsong.uk/de/api-reference/tasks/status.md).

### 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/gccai"
}
```

* 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-gccai` 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** |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.