Grok Imagine 2.0 Ext
Grok Imagine Image 2.0 官方图像生成与编辑
- grok-imagine-image-2.0 官方异步图片接口
- 支持文生图、单图编辑与最多 3 张图片的多图参考
- 支持 1–10 张输出、1K / 2K 分辨率、14 种宽高比
- 提交后返回任务 ID,通过任务状态接口获取最终图片
- 推荐固定响应版本 2026-07-27,并使用 Idempotency-Key 防止重复扣费
POST
异步图片接口。 提交成功后返回任务 ID,请通过获取任务状态接口轮询最终结果。
不传
image_urls 即文生图;传入 image_urls 即图片编辑或多图参考。接入概览
异步任务
提交后返回任务 ID,通过任务状态接口获取最终结果。
生成与编辑
一个接口同时支持文生图、单图编辑和多图参考。
统一轮询
使用返回的
data.id 请求任务状态接口,直到任务完成或失败。提交成功时 HTTP 状态为
202,任务 ID 位于 data.id。使用 data.poll_url 或 GET /v1/tasks/{task_id} 轮询任务状态。模型能力
quality 的发送规则:
- 可选
low、medium,默认medium; - 请求含参考图时不要发送
quality; - 添加参考图时,应清除表单中遗留的
quality。
Authorizations
string
必填
推荐请求头
Body
string
默认值:"grok-imagine-image-2.0"
必填
固定值:
grok-imagine-image-2.0string
必填
图片生成或编辑的文本描述。去除首尾空格后不能为空,最多 8000 个字符。多图参考时,可以按数组顺序在提示词中使用
<IMAGE_0>、<IMAGE_1>、<IMAGE_2> 引用图片。integer
默认值:"1"
输出图片张数,取值为
1–10。string
默认值:"auto"
图片宽高比。支持:
允许值完整列表:
1:1、3:4、4:3、9:16、16:9、2:3、3:2、9:19.5、19.5:9、9:20、20:9、1:2、2:1、auto。新接入不要发送像素尺寸字符串。画面比例由
aspect_ratio 控制,清晰度档位由 resolution 控制。string
默认值:"1k"
图片清晰度档位:
1k(默认)2k
string
仅
grok-imagine-image-2.0 文生图支持:lowmedium(2.0 文生图默认)
array
参考图片数组,允许
1–3 张。省略本字段即文生图。数组元素支持:- 公网可访问的绝对
http://或https://URL; - JPEG、PNG、WebP 的 Base64 Data URL。
- 不接受相对 URL、裸 Base64 或其它格式的 Data URL;
- Data URL 解码后单张不超过 10 MiB;
- 数组顺序会保留;
- 重复图片按多张输入处理并按张计费;
- 没有参考图时应省略本字段,不要发送空数组。
使用示例
2.0 文生图
单图编辑
quality。
多图参考
Response
integer
HTTP 业务状态码,提交成功时为
202。string
本次请求的排查 ID。联系支持或记录错误时请保留。
string
任务 ID,用于查询任务状态。
string
异步任务固定为
generation.task。string
提交成功时为
pending。integer
提交时通常为
0。string
任务查询路径。也可使用
GET /v1/tasks/{task_id} 查询。轮询直到任务进入
completed 或 failed。完整字段请参阅获取任务状态。上传本地参考图
如果用户选择本地文件,可先上传到平台,再把返回的url 放入生成请求的 image_urls。
file:
- 支持 JPEG、PNG、WebP;
- 单张图片不超过 10 MiB;
- 使用
FormData时不要手动设置Content-Type,客户端会自动添加 multipart boundary。
获取预估价格
价格应以报价接口返回的final_usd 为准,不要在客户端硬编码价格或自行计算最终金额。
报价参数
示例:
输入图片从第 1 张开始计费,费用按输入张数计算,不再乘输出数量
n。前端只需把 image_urls.length 作为 input_images,并展示报价返回的 final_usd。
需要读取当前 Web 登录用户的个性化报价时,请携带 Session Cookie:
n、aspect_ratio、resolution、quality 或参考图数量变化后,应重新报价。建议使用 200–300ms 防抖,并取消上一笔未完成的请求,防止旧响应覆盖新价格。
幂等与重试
图片生成会产生费用。每次用户确认的一次逻辑生成都应创建一个Idempotency-Key。
- 首次请求创建一个 UUID;
- 同一次请求的网络重试复用原 UUID 和完全相同的请求 Body;
- 修改模型、提示词、图片或其它参数后创建新 UUID;
- 不要在每次自动重试时创建新 UUID;
- 同一 Key 重试时,
X-APIMart-Response-Version也必须保持一致。
浏览器取消请求只表示客户端不再等待响应,不代表服务端生成已经取消,也不代表一定不会计费。
错误处理
统一错误结构:
建议记录
request_id、Idempotency-Key、模型名、HTTP 状态和错误 code。不要记录 API Key、完整 Data URL、用户隐私图片或包含敏感信息的完整提示词。
TypeScript 服务端封装
以下代码应运行在业务后端或 BFF,不要放入包含长期 API Key 的浏览器产物。taskId 调用获取任务状态,直到任务状态变为 completed 或 failed。
前端联动规则
最小上线要求:
- 固定调用
POST /v1/images/generations; - 固定发送
X-APIMart-Response-Version: 2026-07-27; - 每次逻辑生成创建一个幂等 Key,重试时复用;
- 参考图统一通过
image_urls传入,最多 3 张; - 尺寸统一使用
aspect_ratio + resolution; - 从提交响应中读取任务 ID;
- 使用报价接口的
final_usd展示预估价格; - 通过任务状态接口轮询至
completed或failed。