> ## 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 图片生成字段、模型限制与请求示例。

使用 xAI 图片生成请求格式，通过 Grok Imagine 生成图片。

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

## 支持模型

| 模型 ID                        | 能力与限制                                  |
| ---------------------------- | -------------------------------------- |
| `grok-imagine-image-2.0`     | 生成与编辑，支持质量选择及最多五张编辑参考图。                |
| `grok-imagine-image-quality` | 早期生成与编辑模型，不传 Image 2.0 专用的 quality 参数。 |
| `grok-imagine-image`         | 早期生成与编辑模型，不传 Image 2.0 专用的 quality 参数。 |

## 请求参数

| 字段                                         | 类型                | 必填  | 说明                                                                               |
| ------------------------------------------ | ----------------- | --- | -------------------------------------------------------------------------------- |
| `model`                                    | string            | 是   | 完整 Grok Imagine 模型 ID。                                                           |
| `prompt`                                   | string            | 是   | 图片生成或编辑的文本指令。                                                                    |
| `n`                                        | integer           | 否   | 输出图片数量，范围 1-10，默认 1。                                                             |
| `aspect_ratio`                             | string            | 否   | 输出宽高比，取值见下方列表。生成默认 `auto`；编辑通常跟随第一张输入图，显式指定比例时按该比例输出。                            |
| `resolution`                               | string            | 否   | `1k`（默认）或 `2k`，k 为小写。                                                            |
| `quality`                                  | string            | 否   | 仅 Grok Imagine Image 2.0：`low`、`medium` 或默认值 `auto`；auto 对生成选择 low，对编辑选择 medium。 |
| `response_format`                          | string            | 否   | `url`（默认）或 `b64_json`。                                                           |
| `user`                                     | string            | 否   | 用于滥用监测的稳定终端用户标识，避免直接提供个人信息。                                                      |
| `storage_options`                          | object            | 否   | 可选的原生 Files API 存储配置，要求当前路由的上游账号具备相应权限。                                          |
| `storage_options.filename`                 | string            | 按场景 | 提供 storage\_options 时必填，用于设置存储文件名；扩展名不会改变实际编码类型。                                 |
| `storage_options.expires_after`            | integer           | 否   | 存储文件有效期，范围 3600-2592000 秒；省略时不自动过期。                                              |
| `storage_options.public_url`               | boolean \| object | 否   | true 表示创建公开 URL；省略或 false 时不创建持久公开 URL，也可传入对象配置有效期。                              |
| `storage_options.public_url.expires_after` | integer           | 否   | 公开 URL 有效期，范围 3600-2592000 秒，默认跟随文件有效期，不能超过已配置的文件有效期。                            |

## 宽高比

`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` 和 `5:2` 是 Image 2.0 新增比例，早期模型使用其余受支持比例。使用 `aspect_ratio` 与 `resolution`，不使用 GPT Image 的 `size` 字段。

## 调用示例

将 MixRoute Key 设置到环境变量 `MIXROUTE_API_KEY`，通过 `Authorization: Bearer ...` 认证。编辑图片前，将素材占位值替换为可访问的图片或本地文件。

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

## 响应

从 `data[].url` 读取临时图片地址，或解码不带 data-URI 前缀的 `data[].b64_json`；`mime_type` 标明编码。请求原生存储时，`file_output` 返回文件信息，存储或公开 URL 失败与图片生成失败是不同情况。

[Grok 图片编辑](/cn/api-reference/endpoint/grok-imagine-edit)