跳转到主要内容
Grok Imagine Image 2.0 是 xAI 当前的图像模型,文生图和参考图编辑都走 OpenAI 兼容的 Images 接口,一次请求可以返回多张。在老张API上,模型 ID 是 grok-imagine-image-2.0,每张 $0.055,1K、2K 同价,不需要 xAI 账号。

当前接入范围

xAI 官方按分辨率和质量分档计价,老张API下列档位都是每张 $0.055,编辑也不另收输入图费用:
  • 1K medium、2K low:xAI 官方 $0.06
  • 2K medium:xAI 官方 $0.08
  • 编辑:xAI 官方另按每张输入图收 $0.01
模型由 xAI 提供。价格为 2026 年 9 月 24 日公开价格配置,核对日期 2026 年 10 月 14 日,见模型与价格总表;xAI 价格见 xAI 模型页,2026 年 10 月 13 日核对。
Grok Imagine Image 2.0 生成的日出灯塔,海面反射阳光

「文生图快速开始」示例的输出:2K,16:9,medium

参数与限制

老张API当前的编辑接口采用 OpenAI 兼容的文件上传格式,不接受 xAI 文档中的 JSON 图片对象。四张或五张参考图会失败;请在客户端把数量限制为最多三张,不要对相同的超限请求自动重试。

三个模型怎样选择

新接入优先测试 grok-imagine-image-2.0。
  • grok-imagine-image:已于 2026 年 10 月 30 日下架,继续调用会返回 503。把 model 改为 grok-imagine-image-2.0 即可,aspect_ratio 和多参考图编辑的写法不变(见下架公告)。
  • grok-imagine-image-quality:xAI 宣布自 2026 年 11 月 2 日起退役这个型号,之后由 grok-imagine-image-2.0 的 low 档处理(见 xAI 迁移说明)。截至 2026 年 11 月 3 日,老张API 仍可调用,与 2.0 一样按成功输出的张数计费,每张 $0.045。它与 2.0 是相互独立的模型 ID,不要混用;新接入请直接使用 2.0,并显式设置 quality。

调用前准备

1

创建并保护令牌

在令牌管理创建 default 分组的令牌,计费模式选择「按量优先」(推荐)或「按次计费」。按量优先的令牌可以同时调用按量和按次计费的模型,按次计费的令牌只能调用按次计费的模型。令牌只保存在服务端环境变量中,不要写入浏览器代码、公开仓库或日志。
2

确认模型与价格

在模型与价格总表确认当前令牌可以看到 grok-imagine-image-2.0,并核对当前单价。
3

配置环境

设置密钥环境变量,并安装 Python 示例与保存脚本用到的依赖:
cURL 示例把响应写入 JSON 文件,再用 Images API 参考中的保存脚本 save_images.py 保存图片;它同时处理 url 与 b64_json 两种返回。Python 示例直接在代码里保存图片。

生成与编辑

文生图快速开始

下面的请求生成一张 2K、16:9、Medium 图片:
成功响应为 HTTP 200,data 中有一张图片:
URL 是临时地址,请求成功后应尽快下载到本地或自己的对象存储。需要在响应里直接拿到图片内容时,把 response_format 改为 b64_json。

Python SDK

OpenAI Python SDK 没有把全部 Grok 图像字段做成顶层参数。将 aspect_ratio、resolution 与 quality 放入 extra_body。

单张参考图编辑

编辑必须使用文件上传,不要把参考图 JSON 放进请求体:
HTTP 200 之后仍要打开保存的图片,检查主体、颜色、文字和构图。参考图编辑会重新生成整个画面,不是像素级的 mask 局部重绘。

两张或三张参考图编辑

多图编辑时重复提交 image[]。下面的三图请求分别提供主体、场景和风格:
上传顺序对应提示词中的 image 1、image 2、image 3。这个三图请求设置了 aspect_ratio=3:2,预期返回一张 1248×832 的 JPEG 图片。

Python SDK 编辑

OpenAI SDK 可以直接用于单图编辑。多图上传建议先使用上面的 curl 形式,确认文件数组和服务端框架的 multipart 行为。

宽高比、分辨率与质量

grok-imagine-image-2.0 支持以下 15 个固定宽高比: 省略 aspect_ratio 时由模型自动选择。需要稳定布局时应显式传值。
  • resolution="1k":更快,适合草稿、缩略图和批量候选;
  • resolution="2k":文件更大、延迟更高,适合成片与裁切;
  • quality="low":速度优先;
  • quality="medium":细节优先;
  • 不要发送 quality="high",也不要发送 resolution="4k"。
成功响应不会明确返回最终采用的质量档。生产请求建议显式使用 low 或 medium,不要依赖 auto 推断成本、延迟或画质。

价格与计费

grok-imagine-image-2.0 按成功输出的图片张数计费,1K/2K、Low/Medium 使用同一单价,单价与 xAI 官方分档对照见当前接入范围。例如:
  • n=4 成功返回四张时计 $0.22;
  • n=10 成功返回十张时计 $0.55;
  • 三张参考图编辑并返回一张结果时,只按一张计费。
大批量任务开始前请到模型与价格总表复核,并以调用记录作为最终账单依据。

参数、错误与上线检查

参数表

错误处理

正常请求遇到 429、网络错误或临时 5xx 时,使用带抖动的指数退避重试。客户端超时后先检查调用记录,再决定是否重新提交,避免重复生成和重复计费。

上线前检查

  1. 先用 1K、Low、n=1 生成一张图,保存后检查真实格式和像素;
  2. 再测试生产需要的 2K、Medium、画幅和 n;
  3. 编辑时使用互不重复的参考图,逐个确认主体进入了输出;
  4. 在客户端把参考图数量上限设为三张;
  5. 1K Low 请求的超时至少设为 60 秒,Medium 与 2K 建议 120–180 秒;
  6. 扩大并发前核对成功率、延迟、图片张数和调用记录。

常见问题

不用 xAI 账号能调用 Grok Imagine 吗?

可以。只需要老张API密钥,不需要 xAI 账号。生成和编辑都走 OpenAI 兼容的 Images 接口,按成功输出的图片张数计费。

新模型的正确 ID 是什么?

使用 grok-imagine-image-2.0,包括末尾的 .0。旧模型 grok-imagine-image 已于 2026 年 10 月 30 日下架;grok-imagine-image-quality 是独立的旧模型 ID,xAI 已宣布 11 月 2 日起退役,新接入请用 2.0。

按请求还是按张计费?分辨率和质量影响价格吗?

按成功输出的图片张数计费,1K、2K 与 Low、Medium 当前使用同一单价,举例见价格与计费。2026 年 10 月 14 日用本页「文生图快速开始」的提示词各生成一张:1K low 用时 16 秒,2K medium 用时 71 秒,调用日志都扣 $0.055。
Grok Imagine Image 2.0 以 1K low 生成的日出灯塔,岩石海岸和海面反光

1K,low,16:9:16 秒,$0.055

Grok Imagine Image 2.0 以 2K medium 生成的日出灯塔,云层和海浪细节更多

2K,medium,16:9:71 秒,$0.055

上游返回非 200、没有生成图片时不按张计费;但客户端超时不等于失败,服务端可能已经出图并扣费,重新提交前先查调用记录。实际扣费以调用记录为准。

编辑能用 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 示例在代码里直接保存。

来源与相关文档