Skip to main content
截至 2026 年 9 月 3 日,老张API已在可用令牌分组中开放 grok-imagine-image-2.0。文生图使用 /v1/images/generations;参考图编辑使用 OpenAI 兼容的 multipart/form-data /v1/images/edits,支持 1–3 张参考图。当前价格为 $0.055/成功输出图片,批量请求按实际返回张数计费。
本页是 Grok Imagine 图像模型的站内完整接入指南。grok-imagine-image-2.0 是真实模型 ID;旧模型 grok-imagine-imagegrok-imagine-image-quality 仍可使用,不要混淆三个 ID。

创建 API Key

创建令牌并确认余额、可见模型与可用分组

查看当前模型价格

批量调用前核对实时价格与调用记录

当前接入范围

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

三个模型怎样选择

新接入优先测试 grok-imagine-image-2.0。现有旧模型调用无需立即迁移;先用相同提示词、比例和分辨率各生成一张,再按结果与成本选择。

调用前准备

1

创建并保护令牌

令牌管理创建 API Key。令牌只保存在服务端环境变量中,不要写入浏览器代码、公开仓库或日志。
2

确认模型与价格

模型价格页面确认当前令牌可以看到 grok-imagine-image-2.0,并核对单价仍为 $0.055。
3

先生成一张验收图

使用 n=1 完成一次真实请求,下载图片并检查像素、内容和调用记录,再增加分辨率、输出数量或并发。

文生图快速开始

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

Python SDK

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

宽高比、分辨率与质量

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

单张参考图编辑

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

两张或三张参考图编辑

多图编辑时重复提交 image[]。下面的三图请求分别提供主体、场景和风格:
上传顺序对应提示词中的 image 1、image 2、image 3。老张API已在 api2.laozhang.ai 实测三张参考图返回 1248×832 JPEG;测试日期为 2026 年 9 月 3 日。
当前上限是三张。四图与五图请求会返回上游服务错误;请在发出请求前本地计数并拒绝,避免把明确的输入边界误当成临时故障重试。

Python SDK 编辑

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

参数表

价格与计费

grok-imagine-image-2.0 当前价格为 $0.055/成功输出图片 1K/2K、Low/Medium 当前使用同一老张API公开单价。老张API售价与 xAI 官方价格是不同的计费合同;大批量任务开始前请到控制台复核,并以调用记录为最终账单依据。

错误处理

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

生产验收清单

  1. 用实际令牌生成一张 1K Low 图片;
  2. 下载 URL 或解码 Base64,检查真实 MIME 和像素;
  3. 再测试生产所需的 2K、Medium、画幅和 n
  4. 编辑使用互不重复的非敏感参考图,逐个检查主体确实进入输出;
  5. 为编辑输入设置三张上限;
  6. 1K Low 请求超时至少 60 秒,Medium 与 2K 建议 120–180 秒;
  7. 在扩大并发前核对成功率、延迟、图片张数和调用记录。

常见问题

新模型的正确 ID 是什么?

使用 grok-imagine-image-2.0,包括末尾的 .0。旧模型 grok-imagine-imagegrok-imagine-image-quality 仍是独立 ID。

价格按一次请求还是按图片张数?

按成功输出图片张数。n=10 成功返回十张时计费 0.550,不是只收一次0.550,不是只收一次 0.055。

编辑最多能上传几张参考图?

grok-imagine-image-2.0 当前最多三张,并且必须使用 multipart 文件上传。四张或五张暂不支持。

可以使用 xAI 官方 JSON 图片编辑格式吗?

当前不可以。老张API已验证的是 OpenAI 兼容 multipart 上传;JSON 图片对象会返回 400。需要官方 JSON 合同时请等待后续兼容更新。

1K、2K、Low 与 Medium 是否同价?

当前老张API公开价格均为 $0.055/成功输出图片。不同档位的延迟和上游成本不同,价格可能调整;批量调用前请复核控制台。

生成结果应该怎样保存?

URL 返回应尽快下载到自己的存储;需要响应内携带图片时使用 b64_json。不要假设临时 URL 永久有效。

来源与相关文档