很多開發者在接入 gpt-image-2 的圖片編輯接口時都會卡在同一個問題上：翻遍 images/edit 的 API Reference 頁面，只看到"GPT image 模型最多可傳 16 張圖"這一句，卻找不到單張圖片的大小限制。是沒有限制？還是文檔漏寫了？
答案是：限制存在，而且很明確——單張圖片必須小於 50MB，支持 PNG、WebP、JPG 三種格式。只不過這條規則沒有寫在 Reference 頁面的參數表裏，而是寫在另一份 Image Generation 使用指南文檔中，兩份文檔的信息割裂讓不少人撲了個空。
本文會把 gpt-image-2 API 的圖片上傳限制一次性講透：數量、大小、格式、mask 規則、分辨率約束，以及一個比 50MB 上限更值得關注的實戰問題——爲什麼我們不建議你真的傳 50MB 的圖。
gpt-image-2 API 圖片上傳限制：官方完整規格
先把結論放在最前面。gpt-image-2 通過 v1/images/edits 端點接收輸入圖片，完整的官方限制如下表所示。
gpt-image-2 圖片上傳限制速查表
| 限制項 | 官方規格 | 文檔出處 |
|---|---|---|
| 單次最多圖片數 | 16 張（GPT image 系列模型） | API Reference：images/edit |
| 單張圖片大小 | < 50MB | Image Generation 使用指南 |
| 支持格式 | PNG、WebP、JPG | Image Generation 使用指南 |
| 傳圖方式 | image_url 或 file_id 二選一 |
API Reference：images/edit |
| mask 蒙版 | 與原圖同格式同尺寸、< 50MB、必須含 alpha 通道 | Image Generation 使用指南 |
| 單次生成數量 n | 1-10 張 | API Reference：images/edit |
也就是說，理論上一次 edit 請求最多可以攜帶 16 張接近 50MB 的圖片。但"理論上限"和"工程上該怎麼用"是兩回事，後文會展開。
這裏有個容易踩的坑值得單獨說明：新版 API 的 images 參數接收的是對象數組，每個對象提供 image_url 或 file_id 其中之一。file_id 來自 Files API 預上傳，適合複用的素材庫場景；image_url 支持公網地址或 base64 data URL，適合一次性請求。兩種方式的 50MB 限制是一致的。
🎯 快速驗證建議：如果你不確定自己的圖片是否會觸發限制，最直接的方式是發一個真實請求看報錯信息。我們建議通過 API易 apiyi.com 的 OpenAI 兼容接口做這類邊界測試，平臺的日誌面板能完整看到請求體大小和錯誤詳情，排查比裸調官方接口更直觀。
gpt-image-2 上傳大小爲什麼在文檔裏"找不到"
回到開頭的疑問：爲什麼 Reference 頁面只寫了 16 張，不寫大小？這其實是 OpenAI 文檔結構的設計取捨。images/edit 的 Reference 頁面是按"參數 Schema"組織的，images 參數在 Schema 層面只是一個對象數組，數量上限屬於數組約束，所以被寫了進去；而文件大小、格式屬於"運行時校驗"，被歸類到了 Image Generation 指南的敘述性文字裏。
類似的"藏在指南里"的規則還有幾條，做圖片編輯功能前最好一併確認：
- mask 蒙版三要求：必須與被編輯圖片同格式、同尺寸，文件同樣小於 50MB，且必須包含 alpha 通道——用 JPG 當 mask 是最常見的報錯原因，因爲 JPG 沒有 alpha 通道。
- 分辨率不是任意的：gpt-image-2 的
size參數支持自定義分辨率，但有硬約束——最長邊不超過 3840px，寬高都必須是 16px 的倍數，寬高比不超過 3:1，總像素需落在 655,360 到 8,294,400 之間。 - 輸入圖會計費：edit 請求中的參考圖按圖像輸入 token 計費，
input_fidelity: high時消耗的輸入 token 會明顯增加。
gpt-image-2 分辨率與 size 參數約束
| 約束維度 | 規則 | 示例 |
|---|---|---|
| 最長邊 | ≤ 3840px | 3840×2160（4K 橫版）可用 |
| 邊長對齊 | 寬高均爲 16px 倍數 | 1024、1536、2048 均合法 |
| 寬高比 | ≤ 3:1 | 2048×1152 合法，3072×1024 合法 |
| 總像素 | 655,360 – 8,294,400 | 低於 768×854 量級會被拒 |
| 常用預設 | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | 豎版同理對調 |
如果你的業務需要頻繁在不同分辨率之間切換，建議把這張約束表做成請求前的本地校驗，在客戶端就攔截非法尺寸，比等 API 返回 400 錯誤節省一次往返。在 API易 apiyi.com 的文檔中心也整理了 gpt-image-2 的參數校驗清單，可以直接對照實現。
gpt-image-2 實戰：50MB 是上限，1.5MB 纔是甜點
知道了 50MB 的硬上限，更重要的問題是：實際工程裏應該傳多大的圖？我們的建議是單張控制在 1.5MB 左右，儘量不超過 5MB。這不是拍腦袋，背後有三層原因。
第一層是 base64 膨脹。如果你用 data URL 方式內嵌圖片，base64 編碼會讓體積膨脹約 33%——一張 40MB 的原圖編碼後接近 53MB，疊加 JSON 結構後請求體可能直接超限。16 張圖全用 base64 內嵌時，這個問題會被放大 16 倍，大體積素材務必改用 file_id 預上傳通道。
第二層是傳輸與解碼耗時。超過 5MB 之後，上傳時間加服務端解碼時間呈非線性增長，在網絡波動時還容易觸發超時重試，反而拖慢整體出圖速度。1.5MB 左右的圖片在普通家庭寬帶下 1-2 秒即可完成上傳，是穩定性和質量的平衡點。
第三層是畫質收益遞減。gpt-image-2 在處理輸入圖時會先做內部預處理，輸入分辨率遠超輸出分辨率時，多出來的像素基本被浪費。一張 3840px 長邊、壓縮到 2MB 以內的 JPG，與 40MB 的無損 PNG 在編輯效果上幾乎沒有可感知差異，成本和耗時卻差一個量級。
gpt-image-2 圖片大小實踐建議
| 原圖情況 | 建議處理 | 預期效果 |
|---|---|---|
| < 1.5MB | 直接上傳 | 最佳速度與穩定性 |
| 1.5MB – 5MB | 可直接傳，建議轉 JPG/WebP | 速度可接受 |
| 5MB – 20MB | 壓縮至長邊 ≤ 3840px + 質量 85 | 畫質幾乎無損，耗時大幅下降 |
| 20MB – 50MB | 必須壓縮，改用 file_id 上傳 | 避免 base64 膨脹超限 |
| > 50MB | 超出硬上限，必須壓縮 | 否則直接報錯 |
💡 批量場景提示：電商摳圖、批量風格化這類高併發場景，建議在上傳前用 sharp 或 Pillow 統一做"長邊 3840px + JPG 質量 85"的預壓縮。我們在 API易 apiyi.com 的企業客戶案例中驗證過，這一步平均能把單次 edit 請求的端到端耗時降低 40% 以上，且畫質投訴爲零。
gpt-image-2 API 快速上手：多圖編輯代碼示例
gpt-image-2 走標準 OpenAI 接口協議，下面是一個攜帶多張參考圖的最簡編輯示例，通過 API易轉發只需替換 base_url：
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # API易統一接口
）
def to_data_url（path）：
with open（path， "rb"） as f:
b64 = base64.b64encode（f.read（））.decode（）
return f"data:image/jpeg；base64，{b64}"
result = client.images.edit（
model="gpt-image-2"，
image=[to_data_url（"product.jpg"）， to_data_url（"style-ref.jpg"）]，
prompt="將產品圖融合參考圖的霓虹賽博風格，保持產品主體不變"，
input_fidelity="high"， # 高保真保留輸入細節，輸入 token 消耗更多
size="2048x2048"，
quality="high"
）
print（result.data[0].b64_json[:64]） # 返回 base64 編碼的結果圖
幾個參數要點：input_fidelity 設爲 high 時人臉、Logo 等細節保留度顯著提升，代價是圖像輸入 token 計費增加；quality 與 size 是決定輸出成本的兩個主要槓桿；n 參數單次最多生成 10 張。計費方面，gpt-image-2 按 token 計價：文本輸入 $5/M，圖像輸入 $8/M（緩存命中 $2/M），圖像輸出 $30/M。換算成單張圖，1024×1024 的 low 檔約 $0.006，medium 檔約 $0.05，high 檔約 $0.21，輸出側永遠是成本大頭。
另外注意官方的速率限制按賬戶層級區分：Tier 1 僅 5 張圖/分鐘，Tier 4 爲 150 張/分鐘，Tier 5 爲 250 張/分鐘。新賬戶層級低，批量任務很容易撞限流。通過 API易 apiyi.com 這類聚合平臺調用可以繞開單賬戶層級限制，適合需要大併發出圖的生產環境。
gpt-image-2 與上一代模型的上傳限制差異
如果你的項目是從 gpt-image-1 或 DALL·E 2 遷移過來的，還需要留意幾處代際差異。最大的變化在 DALL·E 2 到 GPT image 系列之間：DALL·E 2 的 edit 接口只接受一張正方形 PNG，且必須小於 4MB；到了 GPT image 系列，才放寬到 16 張、50MB、三種格式。很多老項目裏寫死的"PNG + 4MB 壓縮"預處理邏輯，遷移後其實可以大幅簡化。
gpt-image-2 相對 gpt-image-1 的升級則主要體現在分辨率和成本上。gpt-image-1 只支持 1024×1024、1536×1024、1024×1536 三種固定輸出；gpt-image-2 開放了自定義分辨率，最高支持到 3840px 長邊的 4K 輸出。價格方面，gpt-image-2 的圖像輸入從 $10/M 降到 $8/M，圖像輸出從 $40/M 降到 $30/M，還新增了 $2/M 的緩存命中檔，重複參考圖場景的成本下降明顯。
gpt-image-2 與歷代模型上傳限制對比
| 對比項 | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| 輸入圖數量 | 1 張 | 最多 16 張 | 最多 16 張 |
| 單張大小上限 | < 4MB | < 50MB | < 50MB |
| 輸入格式 | 僅正方形 PNG | PNG/WebP/JPG | PNG/WebP/JPG |
| 輸出分辨率 | 固定方圖 | 3 種固定尺寸 | 自定義，最長邊 3840px |
| 圖像輸出價格 | 按張計費 | $40/M tokens | $30/M tokens（緩存輸入 $2/M） |
| input_fidelity | 不支持 | 支持 | 支持，高保真細節更強 |
遷移代碼時基本只需要改 model 參數，但建議同步把分辨率校驗和壓縮策略按本文前面的約束表更新一遍。如果想先驗證遷移效果再動生產代碼，可以在 API易 apiyi.com 上用同一組素材分別調用兩代模型，直觀對比編輯質量和實際計費差異。
gpt-image-2 圖片上傳常見問題 FAQ
Q1：gpt-image-2 單張圖片到底能傳多大？
硬上限是 50MB，支持 PNG、WebP、JPG。這條限制寫在 OpenAI 的 Image Generation 使用指南里，而不是 images/edit 的 Reference 參數表中，所以只看 Reference 頁面會找不到。實戰建議控制在 1.5-5MB，體驗最優。
Q2：16 張圖的數量限制是怎麼用的？
images 參數最多接收 16 個圖片對象，每個對象用 image_url 或 file_id 指定一張圖。模型會把多張圖作爲聯合參考，適合"產品圖 + 風格圖 + 構圖參考"的組合編輯場景。注意 16 張是輸入上限，輸出數量由 n 參數控制，上限 10 張。
Q3：mask 蒙版報錯"invalid mask"通常是什麼原因？
九成是 alpha 通道問題。mask 必須與被編輯圖片同格式、同尺寸，且必須包含 alpha 通道——JPG 不支持 alpha 通道，所以 mask 必須用 PNG。透明區域代表"允許重繪"，不透明區域保持原樣。
Q4：base64 上傳和 file_id 上傳怎麼選？
小圖（< 5MB）、一次性請求用 base64 data URL 最省事；大圖或需要多次複用的素材，用 Files API 預上傳拿 file_id，既避開 base64 的 33% 體積膨脹，又能跨請求複用。如果拿不準，可以在 API易 apiyi.com 控制檯兩種方式各跑一次，對比實際耗時後再定方案。
總結：gpt-image-2 上傳限制的三個關鍵數字
回到最初的問題，gpt-image-2 圖片編輯 API 的上傳限制可以濃縮成三個數字：16 張（單次輸入圖數量上限，寫在 Reference）、50MB（單張大小上限，寫在使用指南）、1.5MB（工程實踐的甜點大小）。文檔把數量和大小拆在兩個頁面，是造成"只看到 16 張"困惑的根源。
落地建議也很簡單：上傳前統一壓縮到長邊 3840px 以內、JPG 質量 85 左右；mask 永遠用帶 alpha 通道的 PNG；大素材走 file_id 通道。把這三件事做成請求前的固定預處理，基本可以告別上傳相關的所有報錯。
如果你需要在國內穩定調用 gpt-image-2，或者想把限流上限提到生產級，可以通過 API易 apiyi.com 的統一接口接入，兼容 OpenAI SDK 原生寫法，改一行 base_url 即可遷移。
參考資料：OpenAI API Reference: developers.openai.com/api/reference/resources/images/methods/edit
作者: APIYI Team
專注 AI 大模型 API 聚合與最佳實踐，更多模型評測與接入指南歡迎訪問 API易 apiyi.com。
