OpenAI 兼容层

编辑图片

给一张或多张源图加一段描述，拿到改过的图。同步接口，和生成图片一样一次请求就返回。

POST/v1/images/edits

端点

http

POST /v1/images/edits

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

请求

bash

curl -X POST https://api.wxiai.com/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()

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

走兼容层也一样，网关不做 multipart → JSON 的转换。

正确做法：用 requests / fetch 直接发 JSON，把图片以 {"url": ...} 或 {"file_id": ...} 放进 image 字段。

请求参数

源图：两种写法二选一

写法一：单张源图 image

json

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

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

json

"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`（默认）。只对 `grok-imagine-image-2.0` 生效
`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>…… 例如：

text

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

json

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

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

这一层的注意点

image 和 images 同时传：两者互斥，只能选一种。
多图超过 5 张：images 上限 5 张。
image 传成字符串：要的是对象 {"url": ...} 或 {"file_id": ...}，不是裸 URL 字符串。
quality 默认是 medium：编辑场景下 auto 等价于 medium，比文生图更贵。
url 是临时地址：拿到后尽快下载转存。

编辑图片

端点 ​

请求 ​

请求参数 ​

源图：两种写法二选一 ​

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

返回 ​

这一层的注意点 ​

相关页 ​

端点

请求

请求参数

源图：两种写法二选一

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

返回

这一层的注意点

相关页