> ## Documentation Index
> Fetch the complete documentation index at: https://docs.widerouter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grok Imagine image models
> xAI's three image models on WideRouter: what each one is for, the resolution and quality grid, reference images, and measured latency.
Grok Imagine is xAI's family of generative media models. Three of them produce
images, and all three run on the [async task API](/api/async-tasks) with the same
envelope as every other model on the platform.
Model ids match xAI's official names exactly. WideRouter does not publish aliases.
## The series at a glance
| | Grok Imagine 2.0 | Grok Imagine Quality | Grok Imagine |
| ---------------------- | ------------------------- | ---------------------------- | --------------------- |
| **Model id** | `grok-imagine-image-2.0` | `grok-imagine-image-quality` | `grok-imagine-image` |
| Async task API | yes | yes | yes |
| Synchronous image APIs | yes | yes | yes |
| `quality` parameter | **yes**, `low` / `medium` | no | no |
| Resolution tiers | `1k` / `2k` | `1k` / `2k` | `1k` / `2k` |
| Default framing | landscape, 1248 × 832 | **portrait, 864 × 1152** | landscape, 1248 × 832 |
| Images per call | up to 4 | up to 4 | up to 4 |
| Reference images | up to 3 | up to 3 | up to 3 |
The three take **the same parameters** apart from one: only `grok-imagine-image-2.0`
accepts `quality`. On the other two it is rejected as `unknown field`, because
their quality is fixed rather than selectable.
That is the whole basis for choosing between them:
* **`grok-imagine-image-2.0`** is the tunable one. Use it when you want to trade
cost against fidelity, or when you need a specific aspect ratio and resolution.
* **`grok-imagine-image-quality`** is fixed at high quality and defaults to a
portrait frame. Use it when quality matters more than control.
* **`grok-imagine-image`** is the cheapest of the three by a wide margin. Use it
for drafts, thumbnails, and anything you will generate in bulk.
## Parameters
The envelope is the same three keys described in the
[async task API](/api/async-tasks) — `model`, `input`, and an optional
`callback_url`. Everything below goes inside `input`.
| Field | Type | Default | Notes |
| -------------- | --------- | ------------- | -------------------------------------------------------------- |
| `prompt` | string | — | Required. Must not be empty; at most 32000 bytes. |
| `resolution` | string | `1k` | `1k` or `2k`. Lowercase. |
| `quality` | string | `low` | `low` or `medium`. **Only on `grok-imagine-image-2.0`.** |
| `aspect_ratio` | string | model default | One of the 16 values below, or `auto`. |
| `n` | integer | 1 | 1 to 4. Each image is its own entry in `outputs`. |
| `images` | string\[] | — | Up to 3 reference images, as `https` URLs or base64 data URIs. |
Validation inside `input` is strict — an unrecognized key is rejected outright
with `invalid_params` and a `param` naming it exactly. A typo fails loudly
instead of being silently dropped.
`resolution` values are **lowercase** (`1k`, `2k`). This is the opposite of the
Nano Banana series, which uses uppercase `1K` / `2K` / `4K` in `image_size`.
The two families do not share a parameter name here, so there is nothing to
carry over — read this table, not that one.
## Resolution and quality
On `grok-imagine-image-2.0` the two dimensions are independent and both change
the output. Measured pixel sizes, one sample each:
| `resolution` | `quality` | Output |
| -------------- | --------------- | -------------------- |
| `1k` (default) | `low` (default) | 832 × 1248 |
| `1k` | `medium` | 1280 × 720 at `16:9` |
| `2k` | `low` | 1664 × 2496 |
| `2k` | `medium` | 2816 × 1584 |
On the other two models only `resolution` applies. Measured: `grok-imagine-image`
at `2k` returns 2816 × 1584; `grok-imagine-image-quality` at `2k` returns
1776 × 2368.
Exact pixel dimensions are the model's decision, not a fixed grid — the same
tier lands on different numbers depending on the aspect ratio you ask for.
Treat the table as an order of magnitude, and read the real size off the file.
## Aspect ratios
All three models accept the same 16 values:
| | | | |
| ------ | ------ | -------- | -------- |
| `auto` | `1:1` | `16:9` | `9:16` |
| `4:3` | `3:4` | `3:2` | `2:3` |
| `2:1` | `1:2` | `19.5:9` | `9:19.5` |
| `20:9` | `9:20` | `21:9` | `5:2` |
Omit it and each model uses its own default framing — landscape for
`grok-imagine-image` and `grok-imagine-image-2.0`, portrait for
`grok-imagine-image-quality`. `auto` lets the model pick from the prompt.
## Reference images
Pass up to three images in `input.images` to edit or compose from them. Each
entry is an `https` URL or a base64 data URI:
```json theme={null}
{
"model": "grok-imagine-image-2.0",
"input": {
"prompt": "put the teapot on a marble counter, warm morning light",
"images": ["https://example.com/teapot.jpg"],
"resolution": "2k"
}
}
```
A fourth image is rejected at submit time:
`input.images` — `must contain at most 3 items`. A malformed entry names its
index: `input.images[0]` — `must be an https URL or a base64 image data URI`.
WideRouter fetches the URLs server-side, so they have to be reachable from the
public internet. A host that does not resolve, or that returns something that is
not an image, fails the task after it has been queued rather than at submit time.
## Pricing
These models are served through the **`Grok-Official`** group. WideRouter's list
price matches xAI's official price exactly — the discount lives in the **group
multiplier**, which is `0.8` for `Grok-Official`. So what you pay is:
```
list price × group multiplier = charge
```
Per-image list prices, all confirmed against the billing figures the API returns:
| Model | `resolution` | `quality` | List price |
| ---------------------------- | ------------ | --------- | ------------------------------------ |
| `grok-imagine-image` | `1k` or `2k` | — | \$0.02 — the two tiers cost the same |
| `grok-imagine-image-2.0` | `1k` | `low` | \$0.04 |
| `grok-imagine-image-2.0` | `1k` | `medium` | \$0.06 |
| `grok-imagine-image-2.0` | `2k` | `low` | \$0.06 |
| `grok-imagine-image-2.0` | `2k` | `medium` | \$0.08 |
| `grok-imagine-image-quality` | `1k` | — | \$0.05 |
| `grok-imagine-image-quality` | `2k` | — | \$0.07 |
Two rules that are easy to miss:
* **Reference images cost extra**, about \$0.01 per input image, on top of the
output price. A three-image composition is priced as one output plus three
inputs.
* **`n` multiplies.** Four images at `2k` / `medium` is four times the single-image
price, not a bulk rate.
A completed task carries `usage.cost_in_usd_ticks`, where `10000000000` ticks
is \$1. That figure is the **list price** — before your group multiplier.
Multiply it by your group's rate to get what actually leaves your balance.
## Latency
Measured end to end on the async API, submit to `completed`, one sample each at
default settings:
| Model | End to end |
| ---------------------------- | ---------- |
| `grok-imagine-image` | 6.6 s |
| `grok-imagine-image-quality` | 6.6 s |
| `grok-imagine-image-2.0` | 10 s |
These are fast enough that the async round trip — submit, then poll every two to
three seconds — often costs more wall-clock time than the generation itself.
Two polls is a typical result.
## The synchronous surface
All three models also answer on `POST /v1/images/generations`, which holds the
connection open and hands back the image directly.
```bash theme={null}
curl https://api.widerouter.com/v1/images/generations \
-H "Authorization: Bearer $WIDEROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image-2.0",
"prompt": "a small ceramic teapot on a light-grey studio backdrop",
"resolution": "2k",
"response_format": "b64_json"
}'
```
The response is `data` plus `usage`. What lands in `data[0]` depends on
`response_format`: `b64_json` for bytes inline, `url` for a link.
**With `response_format: "url"` the link points at xAI's own host, not at
WideRouter's CDN**, and its lifetime is not ours to guarantee. Measured: a
`2k` generation came back as a 5.2 MB **PNG** on `imgen.x.ai`, where the same
model on the async API returns JPEG through the WideRouter CDN with a
documented 24-hour window. Prefer `b64_json` here, or use the async API.
The synchronous path is simpler for a script that wants bytes back immediately,
but it holds the connection for the full generation — 19.4 seconds measured at
`2k`. Anything behind a serverless function, a reverse proxy, or a mobile client
should use the async API instead.
## Next steps
Send a real request from the browser and watch the task complete.
The video half of the family — generate, edit and extend clips.