Skip to main content
POST
图片编辑:根据指令编辑参考图或融合多图
右侧的交互式 Playground 支持直接上传本地图片。请在 Authorization 中填入你的 API Key(格式:Bearer sk-xxx),选择 image 文件并填入 promptmodel 后一键发送即可。
🔴 本接口必须使用 multipart/form-data 文件上传发送 JSON 到 /v1/images/edits固定返回 400
如果你是照着 xAI / 上游厂商的文档接入的,请特别注意:上游文档写的是 JSON + 公网图片 URL 的形式({"image": {"type": "image_url", "url": "..."}}),这套写法在 API易 网关上走不通,请以本页为准。好消息是文件上传不需要图床——直接传本地文件即可,比准备公网 URL 更省事。文件字段名只能是 imageimage[];写成 images / image_file 会返回 415prompt 必填,缺失返回 400。
场景说明:本页用于「基于一张或多张参考图改图 / 多图融合」。如需纯文本生成图片,请使用 文生图接口
⚠️ 输出画幅跟随输入图,改不了resolutionaspect_ratio 在本端点传入不报错也不生效——编辑结果的尺寸恒等于输入参考图的尺寸(输入 1280×720 就输出 1280×720,输入 1024×1024 就输出 1024×1024)。需要改变输出画幅,请先自行裁剪或缩放参考图再上传。
多图融合顺序有意义image[] 可重复传入 1–3 张参考图,上传顺序就是提示词中「图1 / 图2 / 图3」的引用依据。建议在提示词里显式指代,例如「把图1的主体放进图2的场景,沿用图2的画风」。

代码示例

Python(OpenAI SDK · 单图编辑)

Python(原生 requests · 单图编辑)

Python(多图融合 · 1–3 张)

cURL

Node.js(原生 fetch + FormData)

浏览器 JavaScript

参数说明速查

本系列不支持 mask 局部重绘。要局部修改请在提示词里描述清楚修改范围,例如「只把围巾改成红色,其余部分完全保持不变」——模型对这类约束遵循度很好。

编辑效果与提示词写法

编辑接口会保留输入图的画风、构图、配色与主体身份,只改提示词指定的部分。为了拿到稳定结果,建议:
**显式声明「其余保持不变」**是这个模型上最有效的技巧。多图融合时则要显式指代「图1 / 图2」,对应 image[] 的上传顺序。

响应格式

响应字段陷阱
  • data[] 每项只有 urlb64_json 二选一,取决于 response_format,不会同时出现。
  • 不返回 revised_prompt,解析时不要假设它存在。
  • b64_json纯 base64,不带 data:image/...;base64, 前缀,可直接 base64.b64decode
  • created 恒为 0,不能当时间戳用。
  • 输出尺寸由输入图决定,不要按请求参数去预判返回图的宽高。
usage 不能用来核账prompt_tokens 恒为 1000 × n,是占位值。编辑与文生图同价,按次固定计费,真实扣费请以 API易 控制台账单为准。

授权

Authorization
string
header
必填

在 API易控制台获取的 API Key

请求体

multipart/form-data
model
enum<string>
默认值:grok-imagine-image
必填

模型 ID

可用选项:
grok-imagine-image,
grok-imagine-image-quality
prompt
string
必填

编辑指令。建议明确「改什么」并声明「其余保持不变」,例如 Change the scarf color to bright RED. Keep everything else exactly the same.

示例:

"Change the scarf color to bright RED. Keep everything else exactly the same."

image
file
必填

参考图文件。多图融合时用 image[] 重复传入(1–3 张), 顺序即 prompt 中「图1/图2/图3」的引用依据。格式 png / jpg / webp。

n
integer
默认值:1

生成图片数量,取值 1–10。与参考图数量无关

必填范围: 1 <= x <= 10
示例:

1

response_format
enum<string>
默认值:url

返回格式。url 返回图片直链;b64_json 返回纯 base64(不带 data: 前缀)

可用选项:
url,
b64_json
示例:

"url"

响应

成功生成图片

created
integer

创建时间戳。本模型恒返回 0,不可用于计时

示例:

0

data
object[]

图片结果数组,长度等于请求的 n

usage
object

占位值,不能用于核账。 prompt_tokens 恒为 1000 × n