改圖與多圖

上傳一張或多張圖片，依文字要求修改或融合。

POST/v1/images/edits通用參數說明

開始之前

需要準備	說明
API Key	在 OfoxAI 控制台建立，取代程式碼中的 `YOUR_OFOX_API_KEY`
執行環境	cURL 需要安裝 `jq` 來解碼圖片；Python 需要 `pip install openai`；Node.js 18 以上，不需安裝相依套件
圖片	在目前目錄放一張 `input.png`；多圖融合時再放一張 `input2.png`。格式為 PNG 或 JPEG，單張 ≤ 15 MB
逾時	用戶端逾時設定為 600 秒。高品質、大尺寸或改圖可能需要等待數分鐘

程式碼中會用到的值

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

模型 IDopenai/gpt-image-2.5-sunburst範例程式碼使用 flare，改圖建議換成 sunburst

API Key將程式碼中的 YOUR_OFOX_API_KEY 換成你的 Key

Python 相依套件pip install openai

修改一張圖

以下程式碼皆原樣執行通過，結果儲存為目前目錄下的 output.png。

cURL

Terminal


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 "prompt=把背景換成木紋桌面,主體保持不變" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

Python

edit.py


import base64
from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_OFOX_API_KEY",  # 換成你的 Key
    base_url="https://api.ofox.ai/v1",
)
 
result = client.images.edit(
    model="openai/gpt-image-2.5-flare",
    image=open("input.png", "rb"),
    prompt="把背景換成木紋桌面,主體保持不變",
    quality="low",
)
 
with open("output.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))
print("已儲存 output.png")

Node.js

edit.mjs


// Node.js 18+,無需安裝任何相依套件
import { readFileSync, writeFileSync } from "node:fs";
 
const form = new FormData();
form.append("model", "openai/gpt-image-2.5-flare");
form.append("image", new Blob([readFileSync("input.png")], { type: "image/png" }), "input.png");
form.append("prompt", "把背景換成木紋桌面,主體保持不變");
form.append("quality", "low");
 
const res = await fetch("https://api.ofox.ai/v1/images/edits", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OFOX_API_KEY", // 換成你的 Key
  },
  body: form,
});
 
const json = await res.json();
if (!res.ok) throw new Error(JSON.stringify(json));
writeFileSync("output.png", Buffer.from(json.data[0].b64_json, "base64"));
console.log("已儲存 output.png");

不傳 size 時，輸出尺寸由模型決定，不一定與原圖相同。若要保持原尺寸，請明確傳入，例如 size=1024x1024。

prompt 怎麼寫

寫清楚兩件事：要改什麼，以及什麼保持不變。

情境	寫法範例
修改一張圖	把背景換成木紋桌面，主體保持不變
多圖融合	把第一張圖的主體放到第二張圖的背景上

多張圖時，依上傳順序稱為「第一張圖」「第二張圖」。若只想修改圖中的一小塊，使用局部重繪會更穩定。

多圖融合

一次傳入多張參考圖。圖片的上傳順序，對應 prompt 中的「第一張」「第二張」。需要先在目前目錄放好 input.png 與 input2.png。

cURL

Terminal


# 一次最多 16 張,每張 ≤ 15 MB
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 "image[]=@input2.png" \
  -F "prompt=把第一張圖的主體放到第二張圖的背景上" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

供應商

不需要指定供應商。三款模型的改圖介面 Azure 與 OpenAI 皆有提供，閘道會自動路由。

有內容審核方面的需求時可以指定供應商，但改圖介面只能使用請求標頭 X-OfoxAI-Provider-Type，寫在表單中的 extra_body 會被忽略。指定後若該供應商無法使用，請求不會自動切換到其他供應商。詳見指定供應商。

參數取值

改圖介面特有的參數如下。model、n、output_format 等與文生圖相同，請見文生圖 · 參數取值。

必填

image必填fileform

要修改的圖片。多張圖時，欄位名稱寫成 image[] 並重複傳入；在 Python SDK 中直接傳入清單。

▸ 詳情

參考圖也依 token 計費：一張 1024×1024 的參考圖實測計 1,024 個輸入 token，因此改圖比同尺寸的文生圖貴。

▶進階 · 1X-OfoxAI-Provider-Type展开

X-OfoxAI-Provider-Typestringheader· 可選azure_foundryopenai

一般不需要傳入，閘道會自動路由。僅在想固定某一家供應商時使用。

上傳限制

項目	限制
單張參考圖	≤ 15 MB
整個請求	≤ 50 MB
張數	閘道不限制，建議不超過 16 張
格式	PNG、JPEG

模型會將參考圖縮放至 1024px 左右處理。單張超過 5 MB 只會讓上傳變慢，不會讓效果更好。

常見錯誤

錯誤	原因	處理方式
`Invalid image file or mode`	上傳的圖片不是標準 PNG 或 JPEG	重新匯出為 PNG 或 JPEG
`Invalid file 'image[0]': unsupported mimetype`	上傳的檔案不是圖片	上傳 PNG、JPEG 或 WebP 圖片
`does not support the 'input_fidelity' parameter`	傳入了 `input_fidelity`	刪除該參數，本系列一律以高保真處理參考圖
`moderation_blocked`	提示詞或參考圖被上游安全系統攔截	修改提示詞或更換參考圖後再試
`provider_type_unavailable`	手動指定的供應商不提供此模型	移除 `X-OfoxAI-Provider-Type` 請求標頭
`Invalid size`	傳入的尺寸不滿足四項限制	請見尺寸
`404 model_not_found`	模型 ID 拼錯或大小寫不正確	從本頁複製模型 ID

其他錯誤請見完整錯誤表。

官方文件

OpenAI 官方文件描述的是直連 OpenAI 時的行為。在 OfoxAI 上呼叫時，以本系列文件的實測結論為準，例如改圖不需要指定供應商。