Skip to main content
用老张API调用 xAI 的 grok-imagine-image-2.0 文生图,或上传 1–3 张参考图编辑。计费按成功输出的图片张数,批量请求按实际返回张数扣费。

当前接入范围

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

三个模型怎样选择

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 示例与保存脚本用到的依赖。
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。

宽高比、分辨率与质量

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

单张参考图编辑

编辑必须使用文件上传,不要把参考图 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 按成功输出的图片张数计费,1K/2K、Low/Medium 使用同一单价(见当前接入范围)。例如:
  • n=4 成功返回四张时计 $0.22;
  • n=10 成功返回十张时计 $0.55;
  • 三张参考图编辑并返回一张结果时,只按一张计费。
老张API售价与 xAI 官方价格分别计算,不能直接对照。大批量任务开始前请到控制台复核,并以调用记录作为最终账单依据。

错误处理

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

上线前检查

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

常见问题

新模型的正确 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 示例在代码里直接保存。

来源与相关文档