---
url: /orchestration/recipes/grok.md
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# Grok image generation

Routes to xAI's Grok image API. Two operations — `createImage` and `editImage` — and a wide aspect-ratio menu (including extreme-wide and extreme-tall variants beyond what Google or OpenAI expose).

## Prerequisites

* For `editImage`: 1–3 source images (URLs, data URLs, or Base64)

## Text-to-image (`createImage`)

```http
POST https://orchestration.civitai.com/v2/consumer/workflows?wait=60
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "grok",
      "operation": "createImage",
      "prompt": "A photorealistic portrait of a woman with flowers in her hair, golden hour lighting",
      "aspectRatio": "1:1",
      "quantity": 1
    }
  }]
}
```

### Parameters

| Field | Required | Default | Notes |
|-------|----------|---------|-------|
| `operation` | ✅ | — | `createImage` or `editImage`. |
| `prompt` | ✅ | — | Natural-language. |
| `aspectRatio` | | `1:1` | See the ratio table below. |
| `quantity` | | `1` | `1`–`4`. |

### Aspect ratios

Grok exposes a wider aspect-ratio menu than other commercial engines:

| Category | Ratios |
|----------|--------|
| Ultra-wide | `2:1`, `20:9`, `19.5:9`, `16:9` |
| Landscape | `4:3`, `3:2` |
| Square | `1:1` |
| Portrait | `2:3`, `3:4` |
| Vertical | `9:16`, `9:19.5`, `9:20`, `1:2` |

Useful when you need phone-native vertical ratios (`9:19.5` / `9:20` match modern flagship screens) or cinema-wide output (`2:1`, `20:9`):

```json
{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "grok",
      "operation": "createImage",
      "prompt": "A sweeping cinematic view of a futuristic city skyline at dusk",
      "aspectRatio": "20:9",
      "quantity": 1
    }
  }]
}
```

::: warning `21:9` isn't in the enum
Grok's list jumps from `20:9` to `16:9` — `21:9` (the common cinema label) isn't accepted. Use `20:9` as the closest cinematic-wide option.
:::

## Image editing (`editImage`)

Pass 1–3 reference images in `images[]`:

```json
{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "grok",
      "operation": "editImage",
      "prompt": "Make it a winter scene with snow falling",
      "images": [
        "https://image.civitai.com/.../source.jpeg"
      ]
    }
  }]
}
```

Edit operations don't take an `aspectRatio` — the output resolution follows the source(s).

## Reading the result

Standard `imageGen` output: an `images[]` array, one entry per `quantity` ([shape and URL expiry](https://developer.civitai.com/orchestration/recipes.md#reading-results)).

## Runtime

xAI's API queue is the dominant factor. Typical wall time 10–30 s per image. `wait=60` is comfortable for `quantity ≤ 2`; higher batches or busy periods warrant `wait=0` + polling.

## Cost

Preview the exact charge with `whatif=true` ([Payments (Buzz)](https://developer.civitai.com/orchestration/guide/submitting-work.md#payments-buzz)).

Flat per-image pricing by operation:

```
total = base × quantity
```

| Operation | Base (per image) |
|-----------|------------------|
| `createImage` | **~26** |
| `editImage` | **~29** |

Examples:

* `createImage`, `quantity: 1` → **~26 Buzz**
* `createImage`, `quantity: 4` → ~104 Buzz
* `editImage` with 1 reference, `quantity: 1` → **~29 Buzz**

Aspect ratio and reference count don't affect Grok's Buzz price — the provider charges flat per-image.

## Troubleshooting

Timeouts, moderation blocks and expired blob URLs: see [Common troubleshooting](https://developer.civitai.com/orchestration/recipes.md#common-troubleshooting). `blocked` comes from xAI's content filter.

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `400` with "aspectRatio must be one of" | Ratio outside the accepted enum (e.g. `21:9`) | Pick a close equivalent from the table above — `20:9` is the closest cinematic wide. |
| `400` with "images minItems" on edit | Empty `images[]` on `editImage` | Include 1–3 source images. |
| `400` with "images maxItems" | More than 3 source images | Trim to 3. |
| `400` with "quantity must be ≤ 4" | Requested more than 4 in one call | Split into multiple submissions or use a different engine with a higher cap (OpenAI gpt-image-1 goes up to 10, Seedream up to 12). |

## Related

* [`SubmitWorkflow`](https://developer.civitai.com/orchestration/reference/operations/SubmitWorkflow.md) · [`GetWorkflow`](https://developer.civitai.com/orchestration/reference/operations/GetWorkflow.md)
* [OpenAI image generation](https://developer.civitai.com/orchestration/recipes/openai.md) — alternative commercial tier
* [Google image generation](https://developer.civitai.com/orchestration/recipes/google.md) / [Gemini](https://developer.civitai.com/orchestration/recipes/gemini.md) — alternative commercial tier
* [Flux 2](https://developer.civitai.com/orchestration/recipes/flux2.md) / [Qwen](https://developer.civitai.com/orchestration/recipes/qwen.md) / [SDXL](https://developer.civitai.com/orchestration/recipes/sdxl.md) — open-weights / sdcpp alternatives on Civitai-hosted workers
* [Image upscaling](https://developer.civitai.com/orchestration/recipes/image-upscaler.md) — chain after `imageGen` for higher-res output
* [Prompt enhancement](https://developer.civitai.com/orchestration/recipes/prompt-enhancement.md) — LLM-rewrite a prompt before feeding it in via `$ref`
* Full parameter catalog: the `GrokCreateImageGenInput` and `GrokEditImageGenInput` schemas in the [API reference](https://developer.civitai.com/orchestration/reference.md)
* [`imageGen` OpenAPI spec](https://orchestration.civitai.com/v2/consumer/recipes/imageGen/openapi.yaml)