> ## 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 官逆](/api-capabilities/grok-imagine-image/overview)。两者对比见 [官转与官逆怎么选](#官转与官逆怎么选)。

> [!NOTE]
>
> 图片 API 全部为**同步调用**：没有异步任务 ID，客户端断开连接结果即丢失、但请求仍会计费。`grok-imagine-image-2.0` 的 `medium` 档 2K 出图实测约 60–80 秒，请为本模型设置足够大的 timeout，详见 [图片 API 调用须知与最佳实践](/api-capabilities/image-api-best-practices)。

> **[文生图 API](/api-capabilities/grok-imagine-image-official/text-to-image)**
>
> 输入文本提示词生成图片，带交互式 Playground 在线调试。

> **[Grok Imagine 视频生成](/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]
>
> 模型价格与官网对齐，且可能随官网调整；上表仅供参考，具体以顶部导航「模型价格」栏目为准：[模型价格](/models/index)。

> [!NOTE]
>
> **计费说明**
>
> * **不传参数时**：默认 `resolution: 1k`；`grok-imagine-image-2.0` 默认 `quality: low`，即 \$0.04 一张。
> * **按张计费、每次 1 张**：本通道请固定 `n=1`，需要多张请并发调用。
> * **请求失败不计费**：参数错误（422 / 400）、分组无权限（503）等返回错误的请求不扣费。
> * **响应体里的 `usage` 不能用来核账**：`prompt_tokens` 恒为 `1000 × 张数`，是占位值，真实扣费以控制台账单为准。
> * 可叠加 [充值阶梯加赠](/faq/recharge-promotions)；用量较大的企业客户可联系商务沟通专属价格。

## 官转与官逆怎么选

API易 同时提供 Grok Imagine 的官转与官逆两条通道，**分组、计费方式和能力都不同**：

| 维度 | **官转**（本页） | [**官逆**](/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 端分发的场景建议在你这一侧再加一层审核。相关背景见 [国内产品调用海外模型的合规要点](/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 官逆](/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 官逆](/api-capabilities/grok-imagine-image/overview)，它的 `/v1/images/edits` 支持 1–4 张参考图。

> **为什么要求 n=1？一次出多张怎么办？**
>
> 本通道当前只开放单张出图。需要多张请并发发起多次请求，每次 `n=1`。如果你的业务确实依赖单次多张，可以使用 [Grok Imagine 官逆](/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](/api-capabilities/grok-imagine-image-official/text-to-image) - 带 Playground 的接口参考
* [Grok Imagine 视频生成](/api-capabilities/grok-imagine-video/overview) - 同一分组，文生视频 / 图生视频
* [Grok Imagine 官逆](/api-capabilities/grok-imagine-image/overview) - 按次计费，支持图片编辑与单次多张
* [图片 API 调用须知与最佳实践](/api-capabilities/image-api-best-practices) - 超时、断连、压缩通用建议
* [充值加赠活动](/faq/recharge-promotions)


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