> ## 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 的 JSON 请求格式编辑图片，此接口不使用 OpenAI 的 multipart 图片上传格式。

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

## 支持模型

| 模型 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            | 是   | 图片生成或编辑的文本指令。                                                                    |
| `image`                                    | object            | 按场景 | 单张源图，通过 `url` 或 `file_id` 指定，不与 `images` 同时传入。                                   |
| `images`                                   | object\[]         | 按场景 | 多张参考图，与 `image` 互斥；Image 2.0 最多支持五张，每项使用相同的图片引用对象。                               |
| `image.url / images[].url`                 | string            | 按场景 | JPEG、PNG 或 WebP 的公网 URL 或 Base64 data URI，与同一对象中的 file\_id 互斥。                   |
| `image.file_id / images[].file_id`         | string            | 按场景 | 当前路由可访问、且已上传完成的 xAI Files API 图片 ID，不是 MixRoute 任务 ID。                           |
| `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` 字段。

编辑时提供 `image` 或 `images`。多图可按顺序在提示词中用 `<IMAGE_0>`、`<IMAGE_1>` 等引用。应使用直接 JSON HTTP 请求，OpenAI SDK 的 images.edit 会发送 multipart 数据，不适合此 xAI 请求。

## 调用示例

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

```bash theme={null}
curl --request POST "https://api.mixroute.ai/v1/images/edits" \
  --header "Authorization: Bearer $MIXROUTE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "grok-imagine-image-2.0",
  "prompt": "Make the mug blue while preserving its shape, lighting, and background.",
  "image": {
    "url": "https://example.com/source.png"
  },
  "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": "Make the mug blue while preserving its shape, lighting, and background.",
  "image": {
    "url": "https://example.com/source.png"
  },
  "n": 1,
  "aspect_ratio": "1:1",
  "resolution": "1k",
  "quality": "low",
  "response_format": "url"
}
''')
response = requests.post(
    "https://api.mixroute.ai/v1/images/edits",
    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-image)