局部重繪

用 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.io/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.io/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 上呼叫時，以本系列文件的實測結論為準，例如改圖不需要指定供應商。