> ## 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 圖片編輯](/zh-hant/api-reference/endpoint/grok-imagine-edit)