这一页是图像能力的共享参考——比例、分辨率、源图写法、长期存储这些两条路径都要用的东西都在这儿。

具体怎么调，看对应端点的独立页：

操作	OpenAI 兼容层	原生透传层
文生图	生成图片	生成图片
图生图 / 编辑	编辑图片	编辑图片

两个接口

接口	用途
POST /…/images/generations	只给 prompt，从零生成
POST /…/images/edits	给 prompt + 源图，改图

兼容层路径是 /v1/images/generations，原生透传路径是 /xai/v1/images/generations，其余完全一致。

图像是同步的

	图像	视频
返回方式	同步，一次请求直接拿结果	异步，先拿 ID 再轮询
要不要轮询	不要	要，见视频生成总览

所以图像接口的心智和对话接口一样：发请求 → 等响应 → 拿结果。只是等得久一点，记得把客户端超时调到 120 秒以上。

尺寸：resolution + aspect_ratio

resolution 不是 1024x1024

Grok 只认两档：1k（默认） 和 2k。

要精确控制形状就配 aspect_ratio，不要试图用像素值。

aspect_ratio

不传默认 auto，让模型按 prompt 自选。

比例	典型用途
1:1	社媒、缩略图
16:9 / 9:16	宽屏、手机竖屏、Stories
4:3 / 3:4	演示稿、人像
3:2 / 2:3	摄影
2:1 / 1:2	横幅、页头
19.5:9 / 9:19.5	现代手机屏（iPhone）
20:9 / 9:20	现代手机屏（Android）
21:9	电影宽银幕
5:2	超宽横幅
auto	模型自选

编辑接口的默认值不一样：不传 aspect_ratio 时，输出跟随第一张输入图的比例；显式传了才会按你给的比例拉伸。

resolution

值	说明
1k	默认
2k	更高分辨率，更贵更慢

quality

可选 low / medium / auto（默认）。只对 grok-imagine-image-2.0 生效。

默认 auto 时的实际行为要记住：

操作	auto 等价于
文生图	low
图像编辑	medium（更贵）

计费按实际服务的档位算。想固定档位就显式传 low 或 medium。

其他参数

参数	说明
n	生成张数，1–10，默认 1。按张计费
response_format	url（默认，返回临时地址）或 b64_json（返回 base64）
storage_options	把产物存进 xAI 文件服务，见下
user	你自己终端用户的标识，用于滥用监测

兼容层额外认 size

OpenAI 兼容路径还认 OpenAI 的 size（如 "1024x1024"），会按长边换算成 1k / 2k 并推断比例。

这是便利，官方文档里没有这个字段。原生透传路径不认它。

源图怎么给

编辑接口需要源图，三种形式可以混用：

形式	例子
公网 URL	{"url": "https://example.com/input.png"}
base64 data URI	{"url": "data:image/png;base64,iVBORw0KGgo..."}
xAI 文件 ID	{"file_id": "file-abc123"}

图片格式只支持 JPEG / PNG / WebP。

单张用 image，多张用 images（最多 5 张），两者互斥。多图时按数组顺序在 prompt 里写 <IMAGE_0>、<IMAGE_1>…… 例如：

把 <IMAGE_1> 的配色方案套到 <IMAGE_0> 的构图上

不要用 OpenAI SDK 的 images.edit()

它用 multipart/form-data，而 Grok 的图片编辑接口要求 application/json。xAI 官方文档也明确写了「不支持」。

走兼容层也一样，网关不做 multipart → JSON 的转换。用 requests / fetch 直接发 JSON。

返回字段

{
  "data": [
    {
      "url": "https://imgen.x.ai/.../image.jpg",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "cost_in_usd_ticks": 400000000
  }
}

字段	说明
data[].url	图片地址。response_format 为 url（默认）时才有
data[].b64_json	base64 图片数据（不含 data: 前缀）。response_format 为 b64_json 时才有
data[].mime_type	图片格式，如 image/png、image/jpeg、image/webp
usage.cost_in_usd_ticks	本次请求成本，单位是「USD tick」：1 美分 = 100,000,000 ticks
usage.input_tokens / output_tokens / total_tokens	grok-imagine-image-2.0 按张计费，不返回 token 字段。只有按 token 计费的图像模型才会有

图像接口的返回两层一致——都直接来自 Grok 官方，网关不改写。

把生成的图存下来

默认返回的 url 是临时地址，拿到后尽快下载转存。两种正规做法：

做法一：直接要 base64

"response_format": "b64_json"

做法二：让 xAI 长期保存

curl -X POST https://api.wxiai.com/xai/v1/images/generations \
  -H "Authorization: Bearer $WXIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "一只戴着宇航头盔的柴犬",
    "storage_options": {
      "filename": "shiba.png",
      "expires_after": 2592000
    }
  }'

字段	必填	说明
filename	是	存储用的文件名
expires_after	否	多少秒后自动过期，最大 2592000（30 天）。不传则不过期
public_url	否	是否额外生成公网直链

返回里会多出 data[].file_output，含 file_id、filename、expires_at（有 TTL 时）、public_url（申请了才有）。

存失败不影响出图：data[].storage_error 会给出原因，图片本身照常返回。

容易踩的坑

• resolution 不是 1024x1024：Grok 只认 1k / 2k 两档。
• image 传成字符串：要的是对象 {"url": ...} 或 {"file_id": ...}，不是裸 URL 字符串。
• image 和 images 同时传：两者互斥，只能选一种。
• 多图超过 5 张：images 上限 5 张。
• 本地没有 mask 参数：Grok 的图片编辑接口没有蒙版字段，需要局部重绘请在 prompt 里描述区域。
• 超时按对话接口设：出图要几十秒，默认 30 秒很可能不够。
• n 是乘数：一次生成多张按张数计费。
• 别和文本接口共用重试逻辑：出图重试成本高，只对网络类错误重试。

相关页

• 生成图片（OpenAI 兼容） · 生成图片（原生透传）
• 编辑图片（OpenAI 兼容） · 编辑图片（原生透传）
• 调用方式 —— 两条路径怎么选
• 错误码