用 GPT Image 2 生成原生 4K 圖像:寬高比與放大工作流
目標型號:
gpt-image-2
推理介面:https://api.toapis.com/v1/images/generations
相關閱讀:GPT Image 2 API 指南 · 局部重繪與畫布外擴 · 全球鏡像與代理 · API 尺寸參考
1. 核心摘要與性能速覽 (TL;DR)
- 任務:用一次
gpt-image-2請求,按你真正需要的寬高比,生成文件中的 4K 檔圖像,用於頭圖或印刷場景。 - 約定:向
POST /v1/images/generations發送型號gpt-image-2。size是寬高比(1:1、16:9以及其他已文件化的比例)。resolution是1k、2k或4k。官方參考為每一對組合公布了對應的像素尺寸。 - 不要發送:
size: "2048x2048"、在精確型號gpt-image-2上使用quality: "hd",或臆造一個upscale: true欄位,聲稱能把 2048 px 渲染變成3840x2160。4K 是一等公民的resolution值。 - 非同步協定:提交調用返回任務
id。輪詢GET /v1/images/generations/{id}(或GET /v1/tasks/{id}),直到completed或failed。4K 任務可能比 1K 打樣更久;用戶端逾時並不等於任務失敗。 - FinOps:先用
1k打樣,把已接受的提示詞提升到4k,並確認即時分檔費率。不要把舊的 1024 px / 2048 px 價格行複製進預測。
2. 寬高比、解析度檔位與原生 4K 輸出
目前 gpt-image-2 約定把形狀和檔位分開:size 選擇寬高比,resolution 選擇品質檔位,服務再由二者推導像素寬高。所以「一張 4K 圖」並不總是 3840x2160——該尺寸是 size: "16:9" 加上 resolution: "4k" 的文件化結果。正方形 4K 輸出的文件化尺寸是 2880x2880。
官方參考列出的預設比例為:
1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、21:9、9:21
也可以傳入 auto,由上遊自行選擇,但最終比例和像素尺寸將無法保證。精確型號 gpt-image-2 沒有文件化的 custom 像素尺寸欄位;自定義 width:height 比例(例如 7:4)寫在 gpt-image-2-vip 和 gpt-image-2-official 上,並受其限制約束(邊長鬚為 16 的倍數、長邊最多 3,840 px、比例至多 3:1、總像素介於 655,360 與 8,294,400 之間)。
精確型號 gpt-image-2 的官方尺寸對照表如下:
| size | 1k | 2k | 4k |
|---|---|---|---|
1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
3:2 | 1536x1024 | 2048x1360 | 3520x2336 |
2:3 | 1024x1536 | 1360x2048 | 2336x3520 |
4:3 | 1024x768 | 2048x1536 | 3312x2480 |
3:4 | 768x1024 | 1536x2048 | 2480x3312 |
5:4 | 1280x1024 | 2560x2048 | 3216x2576 |
4:5 | 1024x1280 | 2048x2560 | 2576x3216 |
16:9 | 1536x864 | 2048x1152 | 3840x2160 |
9:16 | 864x1536 | 1152x2048 | 2160x3840 |
2:1 | 2048x1024 | 2688x1344 | 3840x1920 |
1:2 | 1024x2048 | 1344x2688 | 1920x3840 |
21:9 | 2016x864 | 2688x1152 | 3840x1648 |
9:21 | 864x2016 | 1152x2688 | 1648x3840 |
這張表旁邊需要同時記住兩點:
- 目前 ToAPIs Playground 在 4K 下仍保留
3:2和2:3,但會去掉5:4和4:5。上表仍為這兩個比例列出了 4k 像素值。若產品需要 4k 的5:4或4:5,請用即時請求確認,不要把 Playground 的門禁直接當成 API 限制。 - 不同界面會出現小寫(
4k)和大寫(4K)。官方gpt-image-2示例使用小寫;Playground 配置使用1K/2K/4K。用戶端請遵循 API 參考,不要把大小寫當成第二個參數。

圖 1:解析度是一等公民的請求欄位。文件化的路徑是直接請求 4k,而不是發明一個後處理放大開關。
ToAPIs 沒有文件化的 upscale: true 開關,可以把原生 2048 px 渲染變成 3840x2160。如果你已有 1K 或 2K 圖像並希望得到更大的結果,支援的做法是發起一次新的生成(可選地把草稿放入 reference_images),並將 resolution 設為 "4k"。除非你已在自己的素材上測過,否則不要承諾字體清晰度、「300 DPI 印刷母版」或無僞影放大。
精確型號 gpt-image-2 還接受可選的 background: "transparent",以及最多 14 個 reference_images URL。它在目前 Playground 約定中不暴露 quality;quality 是 gpt-image-2-vip 等型號上的欄位。
3. 生產級實作:cURL 與 Python
本系列的國際示例使用 https://api.toapis.com。官方文件要求中國大陸使用者使用 https://toapis.cn。每個環境只保留一個源站。
步驟 1:用 cURL 直接請求原生 4K
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
"size": "16:9",
"resolution": "4k",
"n": 1,
"response_format": "url"
}'
按文件,該請求對應 3840x2160。若需要正方形 4K 母版,將 size 改為 1:1(文件化為 2880x2880)。若需要 9:16 豎版,使用 size: "9:16"(文件化為 2160x3840)。
步驟 2:Python 先打樣再提升
先在 1k 迭代,持久化已接受的提示詞(以及可選的參考圖 URL),再以 4k 重新提交。輪詢輔助函數與鏡像與代理指南使用同一套非同步約定。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_image(
prompt: str,
size: str = "16:9",
resolution: str = "1k",
model: str = "gpt-image-2",
reference_images: list[str] | None = None,
) -> str:
payload = {
"model": model,
"prompt": prompt,
"size": size,
"resolution": resolution,
"n": 1,
"response_format": "url",
}
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_image_task(task_id: str, deadline_s: int = 300) -> str:
poll_url = f"{BASE}/v1/images/generations/{task_id}"
interval = 2.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(
f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
)
if __name__ == "__main__":
prompt = (
"Wide architectural photograph of a concrete pavilion at dusk, "
"still water in the foreground, no typography, no logos"
)
draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
print("Draft:", draft_id, poll_image_task(draft_id))
final_id = dispatch_image(prompt, size="16:9", resolution="4k")
print("4K:", final_id, poll_image_task(final_id, deadline_s=300))
給 4K 輪詢的時限應長於 1K 打樣。請立即持久化任務 id,這樣即使用戶端逾時,仍可通過後續狀態查詢解決。若日後把用戶端切到 gpt-image-2-vip(自定義比例、quality)或 gpt-image-2-official,請一次只改一個變數,並重讀該型號的參考——計費單位不會自動相同。
4. 錯誤處理與狀態碼對照
下表只是排查起點,並不保證與 ToAPIs 的精確錯誤碼一一對應。即便 HTTP 提交成功,仍須讀取任務的 status。
| HTTP 狀態 | 常見類別 | 建議操作 |
|---|---|---|
400 | 欄位無效或不支援的組合 | 確認 size 是已文件化的比例、resolution 是 1k / 2k / 4k,並且沒有發送 2048x2048 這類像素字元串或未文件化的 upscale 開關 |
401 | API 密鑰缺失或無效 | 在 ToAPIs 控制臺輪換密鑰,並確認 Authorization 頭 |
429 | 速率或並發限制 | 若響應含 Retry-After 請遵守;加入抖動後退避;僅在安全時重試 |
5xx 或網絡逾時 | 閘道或上遊暫時異常 | 重新提交前先查詢任務狀態;用戶端逾時後,4K 任務仍可能處於 in_progress |
5. 定價與 FinOps ROI
- 不要沿用舊單價,例如 1024 px 的
$0.024或 2048 px 的$0.072。這些行屬於已經過時的尺寸約定。 - GPT Image 2 模型指南 目前展示的 ToAPIs 投放對照價,是標準
gpt-image-2在1K/2K/4K下每張$0.015/$0.020/$0.025。請只把它當作列表對照價,並確認適用於你的帳戶以及實際調用的型號 ID。 - 節省成本的循環是:先在
1k打樣,再把已接受的提示詞(和參考圖)提升到4k。兩次成功提交就是兩張計費圖像,除非帳戶條款另有說明。文件中沒有「同一提示詞免費放大」的捷徑。 - 官方廠商的 token 價格與 ToAPIs 的按次價格不可混用。若改用
gpt-image-2-vip或官方渠道型號,請重讀該型號的價目。 - 背景閱讀見 GPT Image 2 定價文章,寫入預測前請用即時目錄核對每一個數字。
6. 常見問題
詳見 frontmatter 中的 FAQ。摘要:4K 是一等公民的 resolution 值,不是 upscale 開關;像素尺寸同時取決於 size 和 resolution;不要把 1024x1024 當作 size;若需要 4k 的 5:4 / 4:5,請用即時 API 確認;1K / 2K / 4K 列表價須在帳戶中核對。
7. 行動清單
- 在 ToAPIs 開發者門戶 建立密鑰。
- 為每個環境設定一個基址(
https://api.toapis.com,或在需要時使用https://toapis.cn),並用size: "16:9"、resolution: "1k"對 cURL 片段做冒煙測試。 - 把同一提示詞提升到
resolution: "4k",並確認該比例的文件化像素尺寸(16:9為3840x2160)。 - 持久化任務
id,給 4K 輪詢更長的時限,並在429時遵守Retry-After。 - 接下來:若要編輯已有畫面,閱讀 局部重繪與畫布外擴指南;更完整的參數表見 API 指南。







