> ## 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 圖片生成欄位、模型限制與請求示例。
使用 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 圖片編輯](/docs/zh-hant/api-reference/endpoint/grok-imagine-edit)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.