grok-imagine-image-2.0 文生图,或上传 1–3 张参考图编辑。计费按成功输出的图片张数,批量请求按实际返回张数扣费。
当前接入范围
三个模型怎样选择
2026 年 9 月 24 日公开价格配置中,旧型号
grok-imagine-image 为 $0.025/张,grok-imagine-image-quality 为 $0.045/张,与 2.0 一样按成功输出的图片张数计费。
新接入优先测试 grok-imagine-image-2.0。现有旧模型调用无需立即迁移;可以先用相同的提示词、比例和分辨率各生成一张,再按结果与成本选择。
调用前准备
1
创建并保护令牌
在令牌管理创建
default 分组的令牌,计费模式选择「按量优先」(推荐)或「按次计费」。按量优先的令牌可以同时调用按量和按次计费的模型,按次计费的令牌只能调用按次计费的模型。令牌只保存在服务端环境变量中,不要写入浏览器代码、公开仓库或日志。2
确认模型与价格
在模型价格页面确认当前令牌可以看到
grok-imagine-image-2.0,并核对当前单价。3
配置环境
设置密钥环境变量,并安装 Python 示例与保存脚本用到的依赖。
save_images.py 保存图片;它同时处理 url 与 b64_json 两种返回。Python 示例直接在代码里保存图片。
文生图快速开始
下面的请求生成一张 2K、16:9、Medium 图片:data 中有一张图片:
response_format 改为 b64_json。
Python SDK
宽高比、分辨率与质量
grok-imagine-image-2.0 支持以下 15 个固定宽高比:
省略
aspect_ratio 时由模型自动选择。需要稳定布局时应显式传值。
resolution="1k":更快,适合草稿、缩略图和批量候选;resolution="2k":文件更大、延迟更高,适合成片与裁切;quality="low":速度优先;quality="medium":细节优先;- 不要发送
quality="high",也不要发送resolution="4k"。
单张参考图编辑
编辑必须使用文件上传,不要把参考图 JSON 放进请求体:两张或三张参考图编辑
多图编辑时重复提交image[]。下面的三图请求分别提供主体、场景和风格:
aspect_ratio=3:2,预期返回一张 1248×832 的 JPEG 图片。
Python SDK 编辑
参数表
价格与计费
grok-imagine-image-2.0 按成功输出的图片张数计费,1K/2K、Low/Medium 使用同一单价(见当前接入范围)。例如:
n=4成功返回四张时计 $0.22;n=10成功返回十张时计 $0.55;- 三张参考图编辑并返回一张结果时,只按一张计费。
错误处理
正常请求遇到 429、网络错误或临时 5xx 时,使用带抖动的指数退避重试。客户端超时后先检查调用记录,再决定是否重新提交,避免重复生成和重复计费。
上线前检查
- 先用 1K、Low、
n=1生成一张图,保存后检查真实格式和像素; - 再测试生产需要的 2K、Medium、画幅和
n; - 编辑时使用互不重复的参考图,逐个确认主体进入了输出;
- 在客户端把参考图数量上限设为三张;
- 1K Low 请求的超时至少设为 60 秒,Medium 与 2K 建议 120–180 秒;
- 扩大并发前核对成功率、延迟、图片张数和调用记录。
常见问题
新模型的正确 ID 是什么?
使用grok-imagine-image-2.0,包括末尾的 .0。旧模型 grok-imagine-image 与 grok-imagine-image-quality 是独立的模型 ID。
按请求还是按张计费?分辨率和质量影响价格吗?
按成功输出的图片张数计费,1K、2K 与 Low、Medium 当前使用同一单价,举例见价格与计费。 请求返回错误、没有生成图片时不按张计费;但客户端超时不等于失败,服务端可能已经出图并扣费,重新提交前先查调用记录。实际扣费以调用记录为准。编辑能用 JSON 格式或四五张参考图吗?
都不能。编辑只接受 multipart 文件上传,最多三张参考图(见当前接入范围);发送 xAI 官方的 JSON 图片对象会返回 400。 xAI 文档说 OpenAI SDK 的images.edit() 不能用于 Grok 编辑,那是针对 xAI 官方的 JSON 接口。
在老张API上,images.edit() 可以直接做单图编辑,写法见 Python SDK 编辑;多图编辑建议先用 cURL 的 image[] 写法。
编辑结果的宽高比由什么决定?
xAI 官方说明:不传aspect_ratio 时,输出比例跟随第一张参考图。需要固定画幅时,在编辑请求里加上 aspect_ratio,例如三图示例中的 aspect_ratio=3:2 会返回 1248×832 的图片。
能在上一次的结果上继续编辑吗?
可以。先把上一次返回的图片下载到本地,再作为image 上传,并在提示词里只写这一轮要改的内容,例如「保持画面不变,只加一个金色边框」。每一轮都是一次新的编辑请求,按返回的图片张数单独计费。
生成结果应该怎样保存?
返回 URL 时尽快下载到自己的存储;xAI 官方也说明返回的 URL 是临时地址,不要当作长期链接。需要响应里直接携带图片时使用b64_json。本页的 cURL 示例用 save_images.py 保存,Python 示例在代码里直接保存。
来源与相关文档
- Grok Imagine Image 2.0 上线公告:开放范围与三图编辑说明
- xAI Grok Imagine Image 2.0 模型:官方模型 ID、分辨率与质量价格
- xAI 图像生成文档:官方画幅、分辨率、质量、批量与返回形式
- xAI 图像编辑文档:官方 JSON 编辑格式,与老张API当前的 multipart 方式不同
- xAI 多图编辑文档:上游最多五图的能力,不等同于老张API当前的三图上限
- Images API 参考:通用 Images API 请求、响应与保存脚本
- 图像生成 API 选型与价格:与其他图像模型对比
- 模型与价格总表与控制台模型价格:当前模型、分组、售价与调用记录入口