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

# Grok Imagine 官轉生圖

> xAI Grok Imagine 官方通道（官轉）完整指南：grok-imagine-image / grok-imagine-image-quality / grok-imagine-image-2.0 三款，與 xAI 官網同價，按解析度（1k / 1.5k / 2k）與畫質檔（low / medium）計費，每張 $0.02–0.08。需申請開通 GrokOfficial 分組。

## 概述

**Grok Imagine 官轉**是 xAI 影像模型的**官方通道**：請求經 API易 轉發到 xAI 官方 API，**價格與 xAI 官網一致**，按解析度與畫質檔計費，引數校驗也與官方一致。

本通道提供三個型號：標準版 `grok-imagine-image`、高品質版 `grok-imagine-image-quality`，以及新一代 **`grok-imagine-image-2.0`**（支援 `low` / `medium` 兩檔畫質）。

> [!WARNING]
>
> **🔒 本通道需申請開通 `GrokOfficial` 分組**
>
> Grok Imagine 官轉不在 `Default` 預設分組。該系列的內容安全策略與平臺其它模型差異較大，為避免合規風險我們採取**定向開放**：
>
> * **累計消費滿 \$1,000 的存量客戶**：聯絡客服說明用途，核驗後開通
> * **其他客戶**：通過[企業微信客服](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)提交申請，說明**使用場景**與**內容管控措施**，稽核通過後為你單獨開通
>
> 令牌分組不含 `GrokOfficial` 時呼叫會返回 **`503`**，這是權限問題、不是服務故障。詳見下方 [分組介紹](#分組介紹)。

> [!TIP]
>
> **官轉還是官逆？** 本頁是官轉：與官網同價、按檔計費、含 `grok-imagine-image-2.0`，**當前只開放文生圖且每次 1 張**。如果你需要**圖片編輯、單次多張**，或更低的按次固定價（\$0.02 / \$0.045 一張、不區分解析度），請用 [Grok Imagine 官逆](/zh-Hant/api-capabilities/grok-imagine-image/overview)。兩者對比見 [官轉與官逆怎麼選](#官轉與官逆怎麼選)。

> [!NOTE]
>
> 圖片 API 全部為**同步呼叫**：沒有非同步任務 ID，客戶端斷開連線結果即丟失、但請求仍會計費。`grok-imagine-image-2.0` 的 `medium` 檔 2K 出圖實測約 60–80 秒，請為本模型設定足夠大的 timeout，詳見 [圖片 API 呼叫須知與最佳實踐](/zh-Hant/api-capabilities/image-api-best-practices)。

> **[文生圖 API](/zh-Hant/api-capabilities/grok-imagine-image-official/text-to-image)**
>
> 輸入文本提示詞生成圖片，帶互動式 Playground 線上除錯。

> **[Grok Imagine 影片生成](/zh-Hant/api-capabilities/grok-imagine-video/overview)**
>
> 同一個 `GrokOfficial` 分組，文生影片 / 圖生影片，按秒計費。

## 讓 AI Agent 幫你接入

幫我在當前專案裡接入 / 排查 Grok Imagine 官轉的「文生圖」。

先讀文件再動手：抓 [https://docs.apiyi.com/api-capabilities/grok-imagine-image-official/overview.md](https://docs.apiyi.com/api-capabilities/grok-imagine-image-official/overview.md) 拿到本頁純文本版；需要更細的引數說明時，text-to-image 頁同樣在地址後加 `.md` 即可。

接入要求：

1. 模型名三選一：`grok-imagine-image`（標準）、`grok-imagine-image-quality`（高品質）、`grok-imagine-image-2.0`（新一代，支援 `quality` 兩檔）。令牌分組必須包含 `GrokOfficial`，否則固定返回 503。

2. 超時：客戶端 timeout 提到 360 秒兜底。`grok-imagine-image` 約 8 秒、`-quality` 約 7–12 秒，但 `grok-imagine-image-2.0` 的 `medium` 檔 2K 要 60–80 秒。圖片介面是同步呼叫，客戶端一斷連結果就丟了而且照樣計費。反向代理、閘道、Serverless 執行上限這些中間層也要一起放寬。

3. 端點：只用 `/v1/images/generations`（JSON）做文生圖。**不要往這個端點傳參考圖**（`image` / `image_url` 等），會被靜默丟棄。本通道當前不開放圖片編輯，需要編輯請用官逆通道 `/api-capabilities/grok-imagine-image/overview`。

4. 尺寸：用 `resolution`（`1k` / `1.5k` / `2k`，小寫）加 `aspect_ratio`（如 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`）控制輸出，**不要傳 `size`**——它不會被換算成解析度檔，傳了也按預設 1k 出圖。列舉外的值會直接返回 422，不會靜默回退。

5. 畫質：只有 `grok-imagine-image-2.0` 有 `quality`，只傳 `low`（預設）或 `medium`，不要傳 `auto` 或 `high`（`high` 會 400）。另外兩個模型不需要傳 `quality`，畫質靠選模型區分。

6. 張數：`n` 固定傳 1。要多張請併發發多次請求，不要用 `n`。

7. 返回處理：預設返回 `url`，也可以傳 `response_format: "b64_json"`。走 URL 的話請在服務端立即下載轉存到自己的物件儲存，不要長期引用這個連結。響應裡的 `usage` 是佔位值（`prompt_tokens` 恆為 1000 乘以張數），**不能拿來對賬**，費用以控制台賬單為準。

8. Key 從環境變數 `APIYI_API_KEY` 讀，base\_url 用 [https://api.apiyi.com/v1，不要硬編碼進程式碼、也不要提交進](https://api.apiyi.com/v1，不要硬編碼進程式碼、也不要提交進) git。改完真跑一次文生圖，把出圖結果和這次呼叫的花費貼給我。

## 模型與定價

價格與 xAI 官網一致，按**每張圖**計費，檔位由 `resolution`（與 2.0 的 `quality`）決定：

| 模型 | 畫質檔 | `1k` | `1.5k` | `2k` |
| - | - | - | - | - |
| **`grok-imagine-image`** | — | \$0.02 | \$0.02 | \$0.02 |
| **`grok-imagine-image-quality`** | — | \$0.05 | \$0.06 | \$0.07 |
| **`grok-imagine-image-2.0`** | `low`（預設） | \$0.04 | \$0.05 | \$0.06 |
| **`grok-imagine-image-2.0`** | `medium` | \$0.06 | \$0.07 | \$0.08 |

> [!NOTE]
>
> 模型價格與官網對齊，且可能隨官網調整；上表僅供參考，具體以頂部導航「模型價格」欄目為準：[模型價格](/zh-Hant/models/index)。

> [!NOTE]
>
> **計費說明**
>
> * **不傳引數時**：預設 `resolution: 1k`；`grok-imagine-image-2.0` 預設 `quality: low`，即 \$0.04 一張。
> * **按張計費、每次 1 張**：本通道請固定 `n=1`，需要多張請併發呼叫。
> * **請求失敗不計費**：引數錯誤（422 / 400）、分組無權限（503）等返回錯誤的請求不扣費。
> * **響應體裡的 `usage` 不能用來核賬**：`prompt_tokens` 恆為 `1000 × 張數`，是佔位值，真實扣費以控制台賬單為準。
> * 可疊加 [充值階梯加贈](/zh-Hant/faq/recharge-promotions)；用量較大的企業客戶可聯絡商務溝通專屬價格。

## 官轉與官逆怎麼選

API易 同時提供 Grok Imagine 的官轉與官逆兩條通道，**分組、計費方式和能力都不同**：

| 維度 | **官轉**（本頁） | [**官逆**](/zh-Hant/api-capabilities/grok-imagine-image/overview) |
| - | - | - |
| 分組 | `GrokOfficial`（需申請） | `Grok_imagine_Reverse`（需申請） |
| 計費 | **與官網同價**，按解析度 × 畫質檔按量計費 | 按次固定價，不區分解析度 |
| 型號 | `grok-imagine-image` / `-quality` / **`-2.0`** | `grok-imagine-image` / `-quality` |
| 解析度檔 | `1k` / `1.5k` / `2k` | `1k` / `2k` |
| 文生圖 | ✅ | ✅ |
| 圖片編輯 / 多圖融合 | 暫不開放 | ✅ 1–4 張參考圖 |
| 單次多張 | 暫不開放（`n=1`） | ✅ `n` 最多 10 |
| 引數校驗 | **嚴格**：列舉外的值返回 422 | 寬鬆：非法值靜默回退預設值 |

> [!TIP]
>
> **怎麼選**：要 `grok-imagine-image-2.0`、要按官方口徑對賬、或希望引數寫錯就報錯 → 官轉。要圖片編輯、單次多張，或者只出 2K 想要更低單價 → 官逆。兩個分組可以同時開通，用不同令牌分別呼叫。

## 分組介紹

> [!WARNING]
>
> **Grok Imagine 官轉不在 `Default` 預設分組。** 本通道放在 **`GrokOfficial` 專屬分組（與官網同價，即上方定價表）**，需申請開通後才能呼叫。

### 誰可以開通

| 客戶型別 | 開通方式 |
| - | - |
| **累計消費滿 \$1,000 的存量客戶** | 聯絡客服說明用途，核驗後開通 |
| **其他客戶** | 提交申請，說明使用場景與內容管控措施，稽核通過後單獨開通 |

### 怎麼申請

**1. 聯絡企業微信客服**

通過[企業微信客服](https://work.weixin.qq.com/kfid/kfc9adfd5810ece25ec)提交申請，也可發郵件到 [hi@apiyi.com](mailto:hi@apiyi.com)。註明申請的是 **`GrokOfficial`（Grok Imagine 官轉）**。

**2. 說明使用場景與內容管控措施**

請寫清楚三件事：出圖用於什麼業務、面向什麼終端使用者、你這一側有哪些內容稽核與人工複核措施。資訊越具體，稽核越快。

**3. 開通後切換令牌分組**

稽核通過後我們為你的賬號開通 `GrokOfficial` 分組。請到[控制台令牌頁](https://api.apiyi.com/token)把呼叫本通道的令牌分組切到 `GrokOfficial`，計費模式選 `按量優先` 或 `按量計費`。

> [!NOTE]
>
> **未開通時的表現**：令牌分組不含 `GrokOfficial` 時呼叫返回 **`503`（當前分組無可用渠道）**，重試無效，需要先完成開通。
>
> **令牌「計費模式」不要選 `按次計費`**：本通道是按量計費，按次計費的令牌路由不到，同樣會返回 503。

> [!NOTE]
>
> **合規提醒**：開通後生成內容的合規責任在呼叫方。請遵守當地法律法規，不得用於生成違法內容、侵犯他人肖像權與智慧財產權的內容，或面向未成年人的不當內容；面向 C 端分發的場景建議在你這一側再加一層稽核。相關背景見 [國內產品呼叫海外模型的合規要點](/zh-Hant/faq/overseas-model-compliance)。發現濫用我們會收回該分組權限。

## 技術規格

| 專案 | 規格 |
| - | - |
| 模型 ID | `grok-imagine-image`、`grok-imagine-image-quality`、`grok-imagine-image-2.0` |
| 端點 | `POST /v1/images/generations`（`application/json`） |
| 解析度檔位 | `1k`（預設）/ `1.5k` / `2k` |
| 寬高比 | 常用 `1:1`（預設）/ `16:9` / `9:16` / `4:3` / `3:4` / `3:2` / `2:3` |
| 畫質檔 | 僅 `grok-imagine-image-2.0`：`low`（預設）/ `medium` |
| 單次張數 | `n=1` |
| 返回格式 | `url`（預設）或 `b64_json` |
| 引數校驗 | 嚴格，列舉外的 `resolution` / `aspect_ratio` 返回 422 |
| 出圖耗時 | `grok-imagine-image` 約 8 秒；`-quality` 1k 約 7 秒、2k 約 12 秒；`-2.0` `low` 約 15–17 秒、`medium` 2K 約 60–80 秒 |
| 建議客戶端超時 | ≥ 360 秒 |

## 關鍵引數詳解

### `resolution` 與 `aspect_ratio`（輸出尺寸）

兩個引數組合決定輸出畫素。部分實測值：

| 模型 | 請求 | 實際輸出 |
| - | - | - |
| `grok-imagine-image` | `1k` + `3:2` | 1248×832（JPEG） |
| `grok-imagine-image-quality` | `2k` + `9:16` | 1584×2816（PNG，約 6.7 MB） |
| `grok-imagine-image-2.0` | `1.5k` + `16:9` + `medium` | 1792×1008 |

> [!WARNING]
>
> **不要傳 `size`，用 `resolution`**
>
> 本通道不會把 OpenAI 風格的 `size`（如 `"2048x2048"`）換算成解析度檔：傳了 `size` 不報錯，但會按預設 `1k` 出圖、按 `1k` 計費。需要 2K 請顯式傳 `resolution: "2k"`。

> [!NOTE]
>
> **引數寫錯會直接報錯**：與官逆通道不同，本通道的引數校驗與 xAI 官方一致。`resolution: "4k"`、`aspect_ratio: "5:7"` 這類列舉外的值會返回 **422**，請求不計費。看到 422 時先檢查這兩個引數的拼寫（注意都是小寫 `1k` / `1.5k` / `2k`）。

### `quality`（僅 `grok-imagine-image-2.0`）

| 值 | 說明 |
| - | - |
| `low` | 預設檔，速度較快 |
| `medium` | 畫質更高、單價高 \$0.02，2K 出圖約 60–80 秒 |

傳 `high` 會返回 400（`This model only supports the following quality value(s): low, medium, auto`）。**請只傳 `low` 或 `medium`**，不要傳 `auto`。`grok-imagine-image` 與 `grok-imagine-image-quality` 不需要傳 `quality`，畫質由模型本身決定。

### `n`（張數）

本通道**固定傳 `n=1`**。需要一次拿多張圖，請併發發起多次請求——本通道的出圖耗時穩定，併發呼叫即可線性提速。

## 最佳實踐

**1. 先用 1k 定稿，再出 2k**

同一個提示詞先用 `1k` 跑幾次挑方向，滿意後再用 `2k` 出終稿。`grok-imagine-image-2.0` 的 `medium` 檔 2K 出圖要 1 分鐘以上，不適合拿來試錯。

**2. 客戶端超時設到 360 秒**

圖片 API 是同步呼叫，按 60 秒配置會在 2.0 `medium` 檔產生大量誤超時，而被掐斷的請求仍然計費。

**3. 用 aspect\_ratio 控制構圖，不要寫進提示詞**

引數是真實生效的，直接傳 `aspect_ratio: "16:9"` 比在提示詞裡寫「橫版構圖」可靠。

**4. URL 結果立即轉存**

返回的圖片連結請在服務端立即下載到自己的儲存，不要長期引用，也不要直接下發給終端使用者。

**5. 需要編輯時換官逆通道**

本通道暫不開放圖片編輯。基於參考圖改圖、多圖融合請用 [Grok Imagine 官逆](/zh-Hant/api-capabilities/grok-imagine-image/overview) 的 `/v1/images/edits`。

## 錯誤碼與重試

| HTTP | 含義 | 處理建議 |
| - | - | - |
| `400` | `quality` 取值非法（如 `high`），錯誤資訊會列出合法值 | 改為 `low` / `medium`，不要重試 |
| `422` | `resolution` / `aspect_ratio` 不在支援的列舉內 | 檢查拼寫與大小寫，不要重試 |
| `429` | 頻率超限或額度不足 | 指數退避重試，並檢查賬戶餘額 |
| `503` | 令牌未開通 `GrokOfficial` 分組，或令牌計費模式為按次計費 | **權限問題不是故障**，重試無效，先按 [分組介紹](#分組介紹) 處理 |

> [!NOTE]
>
> **客戶端建議**：`400` / `422` 是確定性錯誤，重試沒有意義，應直接告警。只有 `429` 和網路層超時值得重試，建議指數退避、最多 3 次。返回錯誤的請求不計費。

## 常見問題

> **呼叫一直返回 503，是渠道掛了嗎？**
>
> 基本是權限問題，有兩種可能：
>
> 1. **令牌分組不含 `GrokOfficial`**：本通道需申請開通，見 [分組介紹](#分組介紹)。
> 2. **令牌計費模式是「按次計費」**：本通道按量計費，按次令牌路由不到。把計費模式改成 `按量優先` 或 `按量計費` 即可。

> **為什麼傳了 size: 2048x2048 出來還是 1K？**
>
> 本通道不把 `size` 換算成解析度檔，傳了也按預設 `1k` 出圖和計費。請改用 `resolution: "2k"`，構圖比例用 `aspect_ratio` 控制。

> **能做圖片編輯、傳參考圖嗎？**
>
> 本通道**暫不開放圖片編輯**。往 `/v1/images/generations` 傳參考圖不會報錯，但參考圖會被忽略，只按提示詞出一張新圖。
>
> 需要編輯或多圖融合，請開通並使用 [Grok Imagine 官逆](/zh-Hant/api-capabilities/grok-imagine-image/overview)，它的 `/v1/images/edits` 支援 1–4 張參考圖。

> **為什麼要求 n=1？一次出多張怎麼辦？**
>
> 本通道當前只開放單張出圖。需要多張請併發發起多次請求，每次 `n=1`。如果你的業務確實依賴單次多張，可以使用 [Grok Imagine 官逆](/zh-Hant/api-capabilities/grok-imagine-image/overview)（`n` 最多 10）。

> **grok-imagine-image-2.0 和另外兩款有什麼區別？**
>
> `grok-imagine-image-2.0` 是 xAI 新一代影像模型，多了 `quality`（`low` / `medium`）畫質檔，`medium` 檔細節更好但更慢（2K 約 60–80 秒）。`grok-imagine-image` 最便宜、各解析度同價；`grok-imagine-image-quality` 畫質更高，按解析度階梯計價。
>
> 建議先用 `grok-imagine-image` 或 2.0 `low` 跑通流程，再按畫質需求升檔。

> **usage 裡的 token 數能用來核對賬單嗎？**
>
> **不能。** 響應體的 `usage.prompt_tokens` 恆為 `1000 × 張數`，是佔位值，與實際計費無關。本通道按張、按解析度與畫質檔計費，真實扣費以控制台賬單為準。

> **能用 OpenAI 官方 SDK 呼叫嗎？**
>
> 可以。端點相容 OpenAI Images API，把 `base_url` 指向 `https://api.apiyi.com/v1`，非標準欄位放進 `extra_body`：
>
> ```python theme={null}
> from openai import OpenAI
> client = OpenAI(api_key="sk-your-api-key", base_url="https://api.apiyi.com/v1")
>
> resp = client.images.generate(
>     model="grok-imagine-image-2.0",
>     prompt="a red wooden boat on an alpine lake at dawn",
>     n=1,
>     extra_body={"resolution": "2k", "aspect_ratio": "16:9", "quality": "medium"},
>     timeout=360,
> )
> print(resp.data[0].url)
> ```

## 相關文件

* [Grok Imagine 官轉文生圖 API](/zh-Hant/api-capabilities/grok-imagine-image-official/text-to-image) - 帶 Playground 的介面參考
* [Grok Imagine 影片生成](/zh-Hant/api-capabilities/grok-imagine-video/overview) - 同一分組，文生影片 / 圖生影片
* [Grok Imagine 官逆](/zh-Hant/api-capabilities/grok-imagine-image/overview) - 按次計費，支援圖片編輯與單次多張
* [圖片 API 呼叫須知與最佳實踐](/zh-Hant/api-capabilities/image-api-best-practices) - 超時、斷連、壓縮通用建議
* [充值加贈活動](/zh-Hant/faq/recharge-promotions)


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