局部重绘

用 mask 圈出一块区域，只重画这一块，其余部分保持原样。

POST/v1/images/edits通用参数说明

开始前

需要准备	说明
API Key	在 OfoxAI 控制台创建，替换代码里的 `YOUR_OFOX_API_KEY`
运行环境	cURL 需要装 `jq` 来解码图片；Python 需要 `pip install openai`，生成 mask 还需要 `pip install pillow`；Node.js 18 及以上，不用装依赖
图片	当前目录放一张 `input.png`，和一张同尺寸的 `mask.png`。没有 mask 的话，下面第 1 步教你生成
超时	客户端超时设为 600 秒。高画质、大尺寸或改图可能要等好几分钟

代码里要用到的

API 地址https://api.ofox.ai/v1

模型 IDopenai/gpt-image-2.5-flare

API Key把代码里的 YOUR_OFOX_API_KEY 换成你的 Key

Python 依赖pip install openai pillowpillow 用来生成 mask

mask 的要求

原图

mask中间透明，其余不透明

→

结果只重画透明区域

示意图，不是真实生成结果

带 alpha 通道的 PNG。JPEG 和不透明的 PNG 都不行。
尺寸与原图完全一致。
透明的地方会被重画，不透明的地方保留原图。
只在改图接口生效。传到文生图接口会被忽略。

操作步骤

准备 mask

已经有 mask 的话跳过这一步。

下面这段代码读取当前目录的 input.png，把画面中间 40% 的方块设为透明，保存为 mask.png。

make_mask.py


from PIL import Image, ImageDraw
 
src = Image.open("input.png")
mask = Image.new("RGBA", src.size, (0, 0, 0, 255))          # 全不透明 = 全部保留
w, h = src.size
ImageDraw.Draw(mask).rectangle(                              # 透明区域 = 要重画的部分
    (int(w * 0.3), int(h * 0.3), int(w * 0.7), int(h * 0.7)), fill=(0, 0, 0, 0)
)
mask.save("mask.png")

发送请求

以下代码都原样运行通过，结果保存为当前目录下的 output.png。

cURL

Terminal


# mask.png:与 input.png 同尺寸、带 alpha 通道;透明区域 = 要重画的部分
curl -s https://api.ofox.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=一只橘猫坐在画面中央,背景和其他部分保持不变" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

prompt 怎么写

prompt 要描述重画后的完整画面，不要只写要加的东西。

	写法	实测结果
✅	一只橘猫坐在画面中央，背景和其他部分保持不变	中间画出了猫，其余部分不变
❌	在透明区域画一只猫	模型把「透明」当成画面内容，画出了棋盘格背景

实测效果

mask 以外的区域几乎没有变化，与原图的平均像素差异小于 2/255。

作为对比，不带 mask 直接改图，同一区域的差异是 120/255。

常见问题

现象	原因	怎么处理
报 `Invalid image file or mode`	mask 不是带 alpha 通道的 PNG	用上面第 1 步的代码重新生成
整张图都变了	mask 没生效：发到了文生图接口，或 mask 全不透明	确认调用的是 `/v1/images/edits`，并且 mask 里有透明区域
画出了棋盘格背景	prompt 里写了「透明区域」	按prompt 怎么写描述完整画面

其他报错见完整报错表。

官方文档

OpenAI 官方文档写的是直连 OpenAI 时的行为。在 OfoxAI 上调用，以本系列文档的实测结论为准，例如改图不需要指定供应商。