Skip to main content
POST
图片编辑:根据指令编辑或融合参考图
右側的互動式 Playground 支援直接上傳本地圖片。請在 Authorization 中填入你的 API Key(格式:Bearer sk-xxx),選擇 image / mask 檔案並填入 promptmodel 後一鍵傳送即可。
場景說明:本頁用於「基於一張或多張參考圖改圖 / 融合生成 / mask 局部重繪」。請求為 multipart/form-data 格式。如需純文本生成圖片,請使用 文生圖介面
🖥️ 瀏覽器 Playground 限制(重要)本介面的響應包含純 base64 字串(數 MB 量級)。受瀏覽器渲染限制,右側 Playground 在收到響應後可能彈出 請求時發生錯誤: unable to complete request ——實際請求已經成功,只是瀏覽器無法把這麼長的 base64 顯示出來。推薦做法(小白零踩坑):
  • 直接複製下方”程式碼示例”中的 Python / Node.js / cURL 到本地執行,程式碼會自動 base64.b64decode 並把圖片儲存為本地檔案
  • 如要在瀏覽器裡試 Playground,用極小的參考圖(< 50KB) 並把 size 設為最小檔(如 1024x1024)、quality 改為 low
⚠️ 關鍵差異(從 gpt-image-1.5 遷移注意)
  • 不要傳 input_fidelity —— gpt-image-2 強制啟用高保真,傳了會 400 報錯
  • 編輯請求的輸入 token 明顯更高 —— 因為參考圖按 Vision 計費規則換算成大量 token,預算要留足
  • background: transparent 不支援 —— 改用 opaque 或自行後處理
  • 多圖融合最多 16 張 —— image[] 欄位重複傳入,超過會報錯
📎 多圖融合順序有意義image[] 欄位可重複傳入多張參考圖,順序將作為 prompt 中「圖1/圖2/圖3」的引用依據。建議在 prompt 中顯式指代,例如:
把圖1的人物放進圖2的場景,沿用圖3的色彩風格
單張檔案上限 50MB(multipart 檔案上傳),格式 png / jpg / webp;實踐中建議先壓到 1.5MB 以內再上傳(詳見下方「上傳大小限制速查」)。

程式碼示例

Python(OpenAI SDK · 單圖編輯)

Python(OpenAI SDK · 多圖融合)

cURL(多圖融合)

cURL(mask 局部重繪)

Node.js(原生 fetch + FormData · 多圖融合)

引數說明速查

quality 不要傳舊版 DALL·E 的 standard / hd 只接受 low / medium / high / auto 四個官方列舉值。舊值在不同後端渠道下行為不一致:有時直接 400 報錯(invalid_value),有時被靜默忽略、按 auto 檔跑出結果(費用不可控)。請始終顯式傳四個官方值之一。

上傳大小限制速查

總請求體積別頂滿:雖然單圖上限 50MB、最多 16 張,但多張大圖同時接近上限時,單個請求體會非常大,容易在閘道 / CDN / 超時層面失敗。實踐中建議每張先壓到 1.5MB 以內(JPEG 品質 80-90),成功率和出圖速度都會明顯更好——輸出畫質與輸入圖體積無關。

參考圖格式要求與預處理

/v1/images/edits 只接受 png / jpg / webp 三種標準格式。如果收到下面這個 400:
大機率是參考圖並非標準 JPEG/PNG。最常見的坑是手機原拍照片的 MPO 格式(Multi-Picture Object,多幀 JPEG 容器):華為 Mate 系列等機型直出的 .jpg 內嵌 HDR 增益圖副幀,實為 MPO。這類檔案的檔案頭同為 FFD8副檔名和 file 命令都顯示 JPEG,肉眼無法分辨,只有按幀解析(如 Pillow)才能識別。報錯裡的「image 1」指第 N 張參考圖(序號從 1 開始),可按序號定位問題圖。
2026-07 實測:MPO 圖 5 次上傳全部 400;同一批圖重編碼為標準 JPEG/PNG 後,保持 3072×4096 原解析度上傳全部成功——問題出在格式,不在尺寸/體積。該錯誤在入口校驗階段快速返回(約 4 秒),不計費
判別與修復Image.open(f).format 返回 "MPO" 即需轉換。上傳鏈路統一做一次重編碼即可,順帶相容 HEIC 等其它手機格式:
業務是「使用者上傳實拍圖」的場景(家裝效果圖、商品實拍等),建議在服務端上傳鏈路統一重編碼,而不是逐張排查——手機 HDR 照片會持續出現。更多輸入圖片處理技巧見 圖片 API 呼叫須知與最佳實踐

mask 局部重繪要求

  • 與原圖相同尺寸PNG 格式,單張小於 4MB
  • 必須帶 alpha 通道:透明區域(alpha=0)= 要重繪的部分,不透明區域 = 保留
  • mask 僅對第一張 image 生效
  • mask 作為「軟引導」而非精確邊界,模型可能在蒙版周圍擴充套件 / 收斂
多輪迭代:把上一次的輸出作為下一次的 image[] 輸入,配合新的編輯指令,可逐步精調畫面。每一輪都按 token 實計,預算時留意累計成本。

響應格式

b64_json 欄位是純 base64不含 data:image/...;base64, 字首,與 gpt-image-2-all 不同。客戶端需自行 decode 寫檔案,或在瀏覽器端拼字首渲染。
編輯請求的 input_tokens 通常顯著高於同尺寸文生圖,原因是參考圖按 Vision 計費規則換算——具體消耗多少可以直接讀 usage.input_tokens_details.image_tokens,與文本部分(text_tokens)是分開計的。多圖融合時 image_tokens 會隨參考圖數量嚴格線性增加(2026-07 實測:4 張 1024² = 4 × 1024 tokens),量化資料見 多圖輸入的價格影響。詳細欄位說明見 概覽頁「如何檢視每次呼叫的真實 token 數」

授權

Authorization
string
header
必填

在 API易控制台获取的 API Key

主體

multipart/form-data
model
enum<string>
預設值:gpt-image-2
必填

模型名称,固定为 gpt-image-2

可用選項:
gpt-image-2
prompt
string
必填

编辑/融合指令。多图场景可用「图1/图2/图3」指代 image 上传顺序

範例:

"把图1的人物放进图2的场景,沿用图3的色彩风格"

image
file[]
必填

参考图,可重复多次(最多 16 张)。单图直接传一次,多图重复传同名 image 字段(例如 -F [email protected] -F [email protected]),按上传顺序对应 prompt 中的「图1/图2/...」。multipart 文件上传单张小于 50MB,格式 png/jpg/webp;实践建议压到 1.5MB 以内

mask
file

掩码图(可选,仅对第一张 image 生效)。要求:

  • 与原图相同尺寸
  • PNG 格式且小于 4MB
  • 必须带 alpha 通道(alpha=0 表示要重绘的区域,不透明区域保留)
size
string
預設值:auto

输出尺寸(同文生图)。预设或满足约束的自定义尺寸

範例:

"1536x1024"

quality
enum<string>
預設值:auto

画质档位

可用選項:
auto,
low,
medium,
high
output_format
enum<string>
預設值:png

输出格式

可用選項:
png,
jpeg,
webp
output_compression
integer

输出压缩率(0–100),仅 jpeg/webp 生效

必填範圍: 0 <= x <= 100
background
enum<string>
預設值:auto

背景模式。auto 或 opaque。不支持 transparent

可用選項:
auto,
opaque

回應

成功生成图片

created
integer
範例:

1776832476

data
object[]

生成结果数组(本模型单次返回 1 张)

usage
object

本次调用 token 用量