GPT Image 2 API 參數詳解：尺寸、解析度、長寬比與品質

GPT Image 2 API 用 model 指定模型名稱，用 size 以 WIDTHxHEIGHT 像素指定輸出尺寸，用 quality 指定品質（low、medium、high 或 auto）。API 沒有 resolution 或 aspect_ratio 欄位。想要一張 4K 的 16:9 影像，就傳送 "size": "3840x2160"。尺寸必須是 16 的倍數，兩邊都不超過 3840 像素，長寬比介於 1:3 到 3:1 之間，總像素介於 655,360 到 8,294,400 之間。

本指南逐一說明會改變畫面的每個參數，附上要傳送的確切值，以及錯誤值會回傳的錯誤。下面列出的每個錯誤都對照線上 API 核對過。

GPT Image 2 在 API 中的模型名稱是什麼？

使用 gpt-image-2 或 gpt-image-2-official。兩者是同一個模型、欄位相同；gpt-image-2 每交付一張影像收取一個固定單價，gpt-image-2-official 按每次算繪回報的 token 計費。

標題裡的名稱不能當作模型 ID 使用。gpt-image-2.0、GPT Image 2 或 chatgpt-images-2 都會回傳 HTTP 400，錯誤碼 20002。

如何設定解析度與長寬比？

用 size，單位是像素。先選好想要的長寬比和像素規模，再傳送對應的寬和高：

這與 Playground 在你選擇長寬比和 1K、2K 或 4K 預設時所用的換算完全相同。正方形 4K 止於 2880x2880，因為 3840 像素的正方形會超過總像素上限。

size: "auto" 把尺寸交給模型決定。它是預設值，也很方便，但當輸出需要配合版面或彼此一致時，請設定明確的尺寸。

OpenAI 將超過 2560×1440 的輸出描述為實驗性功能。在這裡的限制範圍內可以使用，但畫布更大並不保證細節更多。

哪些 size 值會被拒絕？

注意最後兩列。未知欄位會被拒絕，但錯誤不會指出是哪一個欄位。如果你收到 20001，而錯誤訊息是通用的 “Check the parameters against the API documentation”，請找出 API 不接受的欄位，例如 resolution、aspect_ratio 或 response_format。

應該選擇哪種品質？

quality 接受 low、medium、high 和 auto。檔位越高耗時越長，細節也越精細。xhigh 和 max 只屬於 GPT Image 2.5；把它們傳給 GPT Image 2 會回傳 20001，錯誤訊息會指出 quality。

實用的做法：構圖還在變動時用 low 打草稿，用 medium 檢查質感和小字，用 high 產出最終成品。在 gpt-image-2 上每個檔位的價格都相同。在 gpt-image-2-official 上，較高的檔位會回報更多輸出 token，所以費用更高。價格指南列出了具體數字。

auto 讓模型自行選擇檔位。比較多次執行結果時請設定明確的值，否則兩個「相同」的請求可能以不同的檔位算繪。

哪些參數控制格式和背景？

• output_format：png（預設）或 jpeg。不提供 WebP 輸出；傳送 webp 會回傳 20001，錯誤訊息會指出 output_format。
• output_compression：0 到 100，只能搭配 jpeg。
• background：auto、opaque 或 transparent。透明背景需要 png；transparent 搭配 jpeg 會回傳 20001，錯誤訊息會指出 background。
• n：每個請求 1 到 10 張影像。按實際交付的影像計費。
• moderation：auto 或 low。

參考圖和遮罩如何傳入？

以 URL 傳入，絕不能用檔案或 base64。images 接受 1 到 16 個形如 {"image_url": "https://..."} 的物件，傳送它就會讓請求變成編輯。mask 接受一個相同形狀的物件：一張與第一張參考圖尺寸相同的 PNG，其中透明的區域標示要修改的部分。參考文件列出了檔案限制。

常見問題

GPT Image 2 支援 4K 嗎？

支援，但要在上述限制範圍內。16:9 的 3840x2160 和 9:16 的 2160x3840 是最大的畫面，2880x2880 是最大的正方形。

可以傳送長寬比而不是像素嗎？

API 不接受。請先把長寬比換算成 WIDTHxHEIGHT 尺寸，可以用上面的表格，也可以用 Playground，它會在提交前顯示確切的尺寸。

預設的尺寸和品質是什麼？

兩者預設都是 auto，也就是交給模型決定。需要可預期的輸出時，請傳送明確的值。

傳送像素、設定品質、讀懂錯誤訊息

幾乎所有參數問題都是以下三種之一：把長寬比當作尺寸傳送、傳送了 API 不接受的欄位，或者值超出限制。第一種和第三種，錯誤訊息會指出欄位名稱；錯誤訊息是通用提示、沒有指出任何欄位，則是第二種。整合期間，把這一頁和 GPT Image 2 API 參考文件放在手邊。