> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok Imagine

> Grok Imagine image generation fields, model constraints, and request examples.

Generate images with Grok Imagine using the xAI image-generation request format.

`POST https://api.mixroute.ai/v1/images/generations`

## Models

| Model ID | Capabilities and Limits |
| - | - |
| `grok-imagine-image-2.0` | Generation/editing, quality selection, and up to five editing references. |
| `grok-imagine-image-quality` | Earlier generation/editing model. Do not send the Image 2.0 quality parameter. |
| `grok-imagine-image` | Earlier generation/editing model. Do not send the Image 2.0 quality parameter. |

## Request Parameters

| Field | Type | Required | Description |
| - | - | - | - |
| `model` | string | Yes | Complete Grok Imagine model ID. |
| `prompt` | string | Yes | Text description of the requested image or edit. |
| `n` | integer | No | Number of images, 1-10; default 1. |
| `aspect_ratio` | string | No | Output aspect ratio; see the list below. Generation defaults to `auto`; editing normally follows the first input image unless a concrete ratio is provided. |
| `resolution` | string | No | `1k` (default) or `2k`, using lowercase k. |
| `quality` | string | No | Grok Imagine Image 2.0 only: `low`, `medium`, or `auto` (default). Auto currently chooses low for generation and medium for editing. |
| `response_format` | string | No | `url` (default) or `b64_json`. |
| `user` | string | No | Stable end-user identifier for abuse monitoring; avoid raw personal data. |
| `storage_options` | object | No | Optional native Files API storage configuration. Requires permissions in the upstream account used by the route. |
| `storage_options.filename` | string | Conditional | Required when storage\_options is supplied. Stored filename; its extension does not change the generated content type. |
| `storage_options.expires_after` | integer | No | Stored-file lifetime, 3600-2592000 seconds. Omit for no automatic expiry. |
| `storage_options.public_url` | boolean \| object | No | True requests a public URL; omit or false to avoid creating a persistent public URL. An object can configure its lifetime. |
| `storage_options.public_url.expires_after` | integer | No | Public-URL lifetime, 3600-2592000 seconds. Defaults to the file lifetime and cannot exceed a configured file expiry. |

## Aspect Ratios

`auto`, `1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `2:3`, `3:2`, `9:19.5`, `19.5:9`, `9:20`, `20:9`, `1:2`, `2:1`, `21:9`, `5:2`

`21:9` and `5:2` are Image 2.0 additions. Use the other supported ratios with earlier models. Use `aspect_ratio` and `resolution`, not the GPT Image `size` field.

## Examples

Use your MixRoute key in the `MIXROUTE_API_KEY` environment variable. Requests use `Authorization: Bearer ...`. Replace source-image placeholders with accessible images or local files before editing.

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/generations" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "grok-imagine-image-2.0",
  "prompt": "A clean product photograph of a red ceramic mug on a white background.",
  "n": 1,
  "aspect_ratio": "1:1",
  "resolution": "1k",
  "quality": "low",
  "response_format": "url"
}'
```

### Python

```python theme={null}
import json
import os
import requests

payload = json.loads(r'''
{
  "model": "grok-imagine-image-2.0",
  "prompt": "A clean product photograph of a red ceramic mug on a white background.",
  "n": 1,
  "aspect_ratio": "1:1",
  "resolution": "1k",
  "quality": "low",
  "response_format": "url"
}
''')
response = requests.post(
    "https://api.mixroute.ai/v1/images/generations",
    headers={"Authorization": "Bearer " + os.environ["MIXROUTE_API_KEY"]},
    json=payload,
    timeout=180,
)
response.raise_for_status()
result = response.json()
for item in result["data"]:
    print(item.get("url") or item.get("b64_json"))
```

## Response

Read temporary image URLs from `data[].url`, or decode `data[].b64_json` without a data-URI prefix. `mime_type` identifies the encoding. When native storage is requested, `file_output` contains file information; a storage/public-URL error is distinct from generation failure.

[Grok image editing](/api-reference/endpoint/grok-imagine-edit)


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