Skip to main content
老张API现已提供 grok-imagine-imagegrok-imagine-image-quality 两条 Grok Imagine 图像路线,支持文生图、1K/2K、单次最多 10 张,以及通过参考图进行自然语言编辑。当前老张API按生成张数计费:标准模型 $0.02/张,高质量模型 $0.045/张;实际可用分组、价格与扣费结果以控制台和调用日志为准。
“Grok Imagine 2”是本页用于描述当前一代 Grok Imagine 图像能力的产品名称。请求中的模型 ID 不含 2,请使用 grok-imagine-imagegrok-imagine-image-quality

创建 API Key

创建令牌并确认模型分组、余额与计费模式

查看上线公告

查看发布日期、影响范围、价格与状态说明

先选模型

老张API当前按返回图片张数计费,n=4 即按 4 张计算。1K 与 2K 当前同价;上游厂商价格表与老张API价格不是同一计费合同,不应混用。价格调整时以控制台展示和最新公告为准。

当前接入范围

xAI 官方能力页列出了更多宽高比;老张API本页只承诺上表中的 5 个值。不要据此推断其他比例已通过当前网关验证。若控制台或后续公告扩大范围,本页会同步更新。
n=10 表示一次请求最多生成 10 张输出图片,不是最多上传 10 张参考图。参考图数量必须按模型和编辑路由单独判断。

前置要求

1

创建并保护 API Key

令牌管理创建 API Key。不要把密钥写进浏览器前端、公开代码仓库或日志。
2

确认模型与价格

模型价格页面确认目标令牌分组已显示模型,并核对当前单价。公告价格不追溯修改历史订单。
3

先做一张小流量验收图

使用生产同款令牌、提示词和参数生成 1 张图片,检查 HTTP 状态、data 数组、实际像素、下载结果和调用日志,再扩大 n 或并发。

文生图快速开始

使用 OpenAI Images API 兼容端点:
预期成功结果是 HTTP 200,且 data 数组包含 1 个可读取的图片结果。response_format: "url" 时请及时下载,不要把临时 URL 当作永久素材地址。

Python SDK

Python OpenAI SDK 没有为所有 xAI 扩展字段提供顶层参数,因此把 aspect_ratioresolutionresponse_format 放进 extra_body 最稳妥。

参考图编辑

只要任务依赖原图主体、构图、色彩或风格,就使用 /v1/images/edits。当前老张API兼容路由使用 multipart/form-data 文件上传;不要把参考图字段塞进 /v1/images/generations 后仅凭 HTTP 200 判断编辑成功。
多图融合时重复提交 image[],上传顺序就是提示词中的“图 1 / 图 2 / 图 3 / 图 4”。老张API当前按模型提供以下范围: 下面是标准模型四图融合的当前可运行写法:
超过当前参考图上限会返回 HTTP 400。Quality 使用最多 2 张;需要三图或四图组合时改用 grok-imagine-image,不要对同一超限请求盲目重试。
多图编辑的输出宽高比会受第一张参考图影响。实测第一张为 1280×720 时输出为 1280×720;第一张换成 1200×1200 后输出为 1024×1024。可依赖“画幅跟随第一张”,但不要假设输出像素一定与第一张完全相同。
参考图编辑不是 mask 局部重绘。模型会根据自然语言重建结果,关键身份、商标、文字和精确几何位置仍需人工验收;不要把一次成功样例当作像素级保真保证。

参数说明

下表可用于验收宽高比方向与分辨率档位;实际像素由当前模型实现决定,因此生产代码应读取输出文件尺寸,不要硬编码推断:

从其他 Images API 迁移

如果现有代码使用 size: "1536x1024"quality: "high",不要只替换模型名。Grok Imagine 当前路线使用 aspect_ratio + resolution 控制画布,并用两个模型 ID 区分标准与高质量路线。

生产验收与错误处理

  1. 对每个模型分别生成 1 张 1:1 1K 图,确认令牌、分组、价格与解析逻辑。
  2. 再测试目标比例与 2K,读取图片真实尺寸并保存原始响应。
  3. 编辑任务使用特征互不重复的非敏感测试图,逐张确认主体和标志性特征确实进入输出;只收到 HTTP 200 不算多图生效。
  4. 超过参考图上限时不应重试:Quality 减为最多 2 张;标准模型减为最多 4 张。
  5. 当前 resolution=4k 可能返回 HTTP 503,但这是参数不支持,不是暂时性服务故障;改为 1k2k
  6. 429 和网络层错误使用带抖动的指数退避;对其他 400401403 先修正请求或账户状态。
  7. 客户端超时后先查调用日志,再决定是否重发,避免同一任务重复计费。
HTTP 200 只证明请求被处理,不证明比例、参考图或业务约束都已满足。上线验收必须检查输出像素、图片内容、返回数组长度和控制台扣费记录。

常见问题

Grok Imagine 2 的模型 ID 是什么?

使用 grok-imagine-imagegrok-imagine-image-quality。不要添加 2,例如 grok-imagine-2-image 不是本页提供的模型 ID。

两个模型如何选择?

日常素材和批量草稿先用 $0.02/张的 grok-imagine-image;需要成片细节或参考图编辑时,再用 $0.045/张的 grok-imagine-image-quality 做小样对比。最终选择应基于同一提示词、比例和分辨率的实际结果。

1K 和 2K 是否同价?

按本次上线价格,两档在老张API中同价并按生成张数计费。价格可能调整,批量任务开始前请到控制台复核。

为什么只写 5 种宽高比?

这是老张API当前文档化并承诺的接入范围,不是对 xAI 上游全部能力的描述。上游官方资料列有更多比例,但未列入本页的值需要先在当前令牌分组中验证。

参考图编辑最多支持几张?

按模型区分:grok-imagine-image 支持 1–4 张,grok-imagine-image-quality 支持 1–2 张。需要三图或四图组合时使用标准模型;需要 mask 局部重绘或更精确控制时,请评估 GPT-Image-2

生成结果应该怎样保存?

使用 url 时在请求完成后尽快下载到自己的对象存储;需要直接嵌入或离线保存时使用 b64_json。不要依赖临时 URL 长期有效。

来源与相关文档