Grok Imagine 官转生图

概述

Grok Imagine 官转是 xAI 图像模型的官方通道：请求经 API易转发到 xAI 官方 API，价格与 xAI 官网一致，按分辨率与画质档计费，参数校验也与官方一致。本通道提供三个型号：标准版 grok-imagine-image、高质量版 grok-imagine-image-quality，以及新一代 grok-imagine-image-2.0（支持 low / medium 两档画质）。

🔒 本通道需申请开通 GrokOfficial 分组Grok Imagine 官转不在 Default 默认分组。该系列的内容安全策略与平台其它模型差异较大，为避免合规风险我们采取定向开放：

累计消费满 $1,000 的存量客户：联系客服说明用途，核验后开通
其他客户：通过企业微信客服提交申请，说明使用场景与内容管控措施，审核通过后为你单独开通

令牌分组不含 GrokOfficial 时调用会返回 503，这是权限问题、不是服务故障。详见下方分组介绍。

官转还是官逆？ 本页是官转：与官网同价、按档计费、含 grok-imagine-image-2.0，当前只开放文生图且每次 1 张。如果你需要图片编辑、单次多张，或更低的按次固定价（$0.02 / $0.045 一张、不区分分辨率），请用 Grok Imagine 官逆。两者对比见官转与官逆怎么选。

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

文生图 API

输入文本提示词生成图片，带交互式 Playground 在线调试。

Grok Imagine 视频生成

同一个 GrokOfficial 分组，文生视频 / 图生视频，按秒计费。

让 AI Agent 帮你接入

复制这段提示词，粘贴给 Codex / Claude Code / Cursor

它会先抓本页的纯文本版（任意文档页地址后加 .md），再按你项目的技术栈写代码——超时、URL 结果要立即转存、size 不生效要改用 resolution、每次只出 1 张这几个高频坑已经写死在要求里。

帮我在当前项目里接入 / 排查 Grok Imagine 官转的「文生图」。

先读文档再动手：抓 https://docs.apiyi.com/api-capabilities/grok-imagine-image-official/overview.md 拿到本页纯文本版； …

模型名三选一：grok-imagine-image、grok-imagine-image-quality、grok-imagine-image-2.0 …

共 8 条接入要求，点下方按钮复制完整版

模型与定价

价格与 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

模型价格与官网对齐，且可能随官网调整；上表仅供参考，具体以顶部导航「模型价格」栏目为准：模型价格。

计费说明

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

官转与官逆怎么选

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

维度	官转（本页）	官逆
分组	`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	宽松：非法值静默回退默认值

怎么选：要 grok-imagine-image-2.0、要按官方口径对账、或希望参数写错就报错 → 官转。要图片编辑、单次多张，或者只出 2K 想要更低单价 → 官逆。两个分组可以同时开通，用不同令牌分别调用。

分组介绍

Grok Imagine 官转不在 Default 默认分组。 本通道放在 GrokOfficial 专属分组（与官网同价，即上方定价表），需申请开通后才能调用。

谁可以开通

客户类型	开通方式
累计消费满 $1,000 的存量客户	联系客服说明用途，核验后开通
其他客户	提交申请，说明使用场景与内容管控措施，审核通过后单独开通

怎么申请

联系企业微信客服

通过企业微信客服提交申请，也可发邮件到 [email protected]。注明申请的是 GrokOfficial（Grok Imagine 官转）。

说明使用场景与内容管控措施

请写清楚三件事：出图用于什么业务、面向什么终端用户、你这一侧有哪些内容审核与人工复核措施。信息越具体，审核越快。

开通后切换令牌分组

审核通过后我们为你的账号开通 GrokOfficial 分组。请到控制台令牌页把调用本通道的令牌分组切到 GrokOfficial，计费模式选 按量优先 或 按量计费。

未开通时的表现：令牌分组不含 GrokOfficial 时调用返回 503（当前分组无可用渠道），重试无效，需要先完成开通。令牌「计费模式」不要选 按次计费：本通道是按量计费，按次计费的令牌路由不到，同样会返回 503。

合规提醒：开通后生成内容的合规责任在调用方。请遵守当地法律法规，不得用于生成违法内容、侵犯他人肖像权与知识产权的内容，或面向未成年人的不当内容；面向 C 端分发的场景建议在你这一侧再加一层审核。相关背景见国内产品调用海外模型的合规要点。发现滥用我们会收回该分组权限。

技术规格

项目	规格
模型 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

不要传 size，用 resolution本通道不会把 OpenAI 风格的 size（如 "2048x2048"）换算成分辨率档：传了 size 不报错，但会按默认 1k 出图、按 1k 计费。需要 2K 请显式传 resolution: "2k"。

参数写错会直接报错：与官逆通道不同，本通道的参数校验与 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。需要一次拿多张图，请并发发起多次请求——本通道的出图耗时稳定，并发调用即可线性提速。

最佳实践

先用 1k 定稿，再出 2k

同一个提示词先用 1k 跑几次挑方向，满意后再用 2k 出终稿。grok-imagine-image-2.0 的 medium 档 2K 出图要 1 分钟以上，不适合拿来试错。

客户端超时设到 360 秒

图片 API 是同步调用，按 60 秒配置会在 2.0 medium 档产生大量误超时，而被掐断的请求仍然计费。

用 aspect_ratio 控制构图，不要写进提示词

参数是真实生效的，直接传 aspect_ratio: "16:9" 比在提示词里写「横版构图」可靠。

URL 结果立即转存

返回的图片链接请在服务端立即下载到自己的存储，不要长期引用，也不要直接下发给终端用户。

需要编辑时换官逆通道

本通道暂不开放图片编辑。基于参考图改图、多图融合请用 Grok Imagine 官逆的 /v1/images/edits。

错误码与重试

HTTP	含义	处理建议
`400`	`quality` 取值非法（如 `high`），错误信息会列出合法值	改为 `low` / `medium`，不要重试
`422`	`resolution` / `aspect_ratio` 不在支持的枚举内	检查拼写与大小写，不要重试
`429`	频率超限或额度不足	指数退避重试，并检查账户余额
`503`	令牌未开通 `GrokOfficial` 分组，或令牌计费模式为按次计费	权限问题不是故障，重试无效，先按分组介绍处理

客户端建议：400 / 422 是确定性错误，重试没有意义，应直接告警。只有 429 和网络层超时值得重试，建议指数退避、最多 3 次。返回错误的请求不计费。

常见问题

调用一直返回 503，是渠道挂了吗？

基本是权限问题，有两种可能：

令牌分组不含 GrokOfficial：本通道需申请开通，见分组介绍。
令牌计费模式是「按次计费」：本通道按量计费，按次令牌路由不到。把计费模式改成 按量优先 或 按量计费 即可。

为什么传了 size: 2048x2048 出来还是 1K？

本通道不把 size 换算成分辨率档，传了也按默认 1k 出图和计费。请改用 resolution: "2k"，构图比例用 aspect_ratio 控制。

能做图片编辑、传参考图吗？

本通道暂不开放图片编辑。往 /v1/images/generations 传参考图不会报错，但参考图会被忽略，只按提示词出一张新图。需要编辑或多图融合，请开通并使用 Grok Imagine 官逆，它的 /v1/images/edits 支持 1–4 张参考图。

为什么要求 n=1？一次出多张怎么办？

本通道当前只开放单张出图。需要多张请并发发起多次请求，每次 n=1。如果你的业务确实依赖单次多张，可以使用 Grok Imagine 官逆（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：

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)

产品基础

基础 API

图片 API（官转）

视频 API（官转）

多模态理解 API

文本生成

音频 API（官转）

检索与安全

概述

文生图 API

Grok Imagine 视频生成

让 AI Agent 帮你接入

模型与定价

官转与官逆怎么选

分组介绍

谁可以开通

怎么申请

技术规格

关键参数详解

`resolution` 与 `aspect_ratio`（输出尺寸）

`quality`（仅 `grok-imagine-image-2.0`）

`n`（张数）

最佳实践

错误码与重试

常见问题

相关文档

​概述

文生图 API

Grok Imagine 视频生成

​让 AI Agent 帮你接入

​模型与定价

​官转与官逆怎么选

​分组介绍

​谁可以开通

​怎么申请

​技术规格

​关键参数详解

​resolution 与 aspect_ratio（输出尺寸）

​quality（仅 grok-imagine-image-2.0）

​n（张数）

​最佳实践

​错误码与重试

​常见问题

​相关文档

概述

让 AI Agent 帮你接入

模型与定价

官转与官逆怎么选

分组介绍

谁可以开通

怎么申请

技术规格

关键参数详解

`resolution` 与 `aspect_ratio`（输出尺寸）

`quality`（仅 `grok-imagine-image-2.0`）

`n`（张数）

最佳实践

错误码与重试

常见问题

相关文档