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

# Grok Imagine 編輯

> Grok Imagine 圖片編輯欄位、模型限制與請求示例。

<link rel="alternate" hrefLang="en" href="https://mixroute.ai/docs/api-reference/endpoint/grok-imagine-edit" />

<link rel="alternate" hrefLang="zh-Hans" href="https://mixroute.ai/docs/zh-hans/api-reference/endpoint/grok-imagine-edit" />

<link rel="alternate" hrefLang="zh-Hant" href="https://mixroute.ai/docs/zh-hant/api-reference/endpoint/grok-imagine-edit" />

<link rel="alternate" hrefLang="ja" href="https://mixroute.ai/docs/ja/api-reference/endpoint/grok-imagine-edit" />

<link rel="alternate" hrefLang="x-default" href="https://mixroute.ai/docs/api-reference/endpoint/grok-imagine-edit" />

使用 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 圖片生成](/docs/zh-hant/api-reference/endpoint/grok-imagine-image)


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