原生透传层

编辑图片

给一张或多张源图加一段描述，拿到改过的图。请求体原样转发给 Grok，报错是官方原文。

POST/xai/v1/images/edits

端点

POST /xai/v1/images/edits

这是 原生透传路径。同一能力在 OpenAI 兼容层的写法见 编辑图片（OpenAI 兼容）。

请求

curl -X POST https://api.wxiai.com/xai/v1/images/edits \
  -H "Authorization: Bearer $WXIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "把背景换成夜晚的城市霓虹",
    "image": {
      "url": "https://example.com/input.png",
      "type": "image_url"
    }
  }'

不要用 OpenAI SDK 的 images.edit()

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

正确做法：用 requests / fetch 直接发 JSON。

请求参数

源图：两种写法二选一

写法一：单张源图 image

"image": {
  "url": "https://example.com/input.png",
  "type": "image_url"
}

写法二：多张源图 images（多图融合）

"images": [
  { "url": "https://example.com/a.png" },
  { "url": "https://example.com/b.png" }
]

参数	必填	说明
image	二选一	单张源图对象。与 images 互斥
images	二选一	多张源图数组，最多 5 张。与 image 互斥
prompt	是	编辑要求
model	是	图像模型，如 grok-imagine-image-2.0
n	否	生成几张编辑结果，默认 1
aspect_ratio	否	不传时跟随第一张输入图的比例
resolution	否	1k（默认）/ 2k
quality	否	low / medium / auto（默认）
response_format	否	url（默认）或 b64_json
storage_options	否	把产物存入 xAI 文件服务，见总览

源图的三种给法（可混用）

形式	例子
公网 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 对象到底放什么

官方 API schema 里 image / images 的元素只有两个字段：

字段	说明
url	公网 URL 或 base64 data URI。与 file_id 二选一
file_id	xAI 文件服务的文件 ID。与 url 二选一

xAI 官方文档的 curl 示例里还带了一个 "type": "image_url"，但它不在 API schema 中——写上不会报错，但没有任何作用。想少踩坑就直接写 {"url": "..."}。

多图融合时怎么指代每张图

按数组顺序在 prompt 里写 <IMAGE_0>、<IMAGE_1>…… 例如：

让 <IMAGE_0> 里的人穿上 <IMAGE_1> 的衣服

返回

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

字段含义与生成图片完全一致，两层返回也一样。

这一层的注意点

• image 和 images 同时传：两者互斥，只能选一种。
• 多图超过 5 张：images 上限 5 张。
• image 传成字符串：要的是对象 {"url": ...} 或 {"file_id": ...}。
• quality 默认是 medium：编辑场景下 auto 等价于 medium，比文生图更贵。
• 不支持 mask：官方图像编辑接口没有蒙版参数，需要局部重绘请用 prompt 描述区域。

相关页

• 图像生成总览 —— 源图给法、长期存储、两层差异对照
• 编辑图片（OpenAI 兼容） —— 同一能力的另一条路径
• 生成图片（原生透传） —— 从零生成
• 错误码