tutorial6 分鐘閱讀

用 GPT Image 2 生成原生 4K 圖像:寬高比與放大工作流

按目前 GPT Image 2 約定生成原生 4K:把 size 設為寬高比,把 resolution 設為 4k。文件中沒有 upscale: true 開關,4K 的像素尺寸取決於你選擇的比例。

ToAPIs Engineering & Evaluation Team
TL;DR - 核心要點
  • 精確型號 gpt-image-2 把 resolution 作為一等公民檔位:1k、2k 和 4k。要原生 4K,在 POST /v1/images/generations 中發送 resolution: "4k",而不是服務端的 upscale: true 開關,也不是 1024x1024 這種 size 字元串。
  • size 是寬高比(1:1、16:9 以及其他已文件化的比例)。官方參考公布了像素對照表:16:9 在 4k 檔是 3840x2160,1:1 在 4k 檔是 2880x2880。
  • 目前 Playground 在 resolution 為 4K 時會去掉 5:4 和 4:5,儘管 API 尺寸表仍列出了這兩個比例的 4k 像素值。若你需要它們,請以即時參考和實際請求為準。
  • 任務是非同步的:請持久化任務 id,並輪詢 GET /v1/images/generations/{id}。用戶端逾時並不等於任務失敗,在 4k 檔尤其如此。
  • 不要用舊的 1024px / 2048px 單價做預算。請在帳戶中確認該模型 ID 的即時分檔費率。

用 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 的官方尺寸對照表如下:

size1k2k4k
1:11024x10242048x20482880x2880
3:21536x10242048x13603520x2336
2:31024x15361360x20482336x3520
4:31024x7682048x15363312x2480
3:4768x10241536x20482480x3312
5:41280x10242560x20483216x2576
4:51024x12802048x25602576x3216
16:91536x8642048x11523840x2160
9:16864x15361152x20482160x3840
2:12048x10242688x13443840x1920
1:21024x20481344x26881920x3840
21:92016x8642688x11523840x1648
9:21864x20161152x26881648x3840

這張表旁邊需要同時記住兩點:

  • 目前 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 參考,不要把大小寫當成第二個參數。

粗顆粒的 2×2 節點網格經六邊形閘道流入更細的高解析度網格

圖 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

bash
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 重新提交。輪詢輔助函數與鏡像與代理指南使用同一套非同步約定。

python
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 開關
401API 密鑰缺失或無效在 ToAPIs 控制臺輪換密鑰,並確認 Authorization 頭
429速率或並發限制若響應含 Retry-After 請遵守;加入抖動後退避;僅在安全時重試
5xx 或網絡逾時閘道或上遊暫時異常重新提交前先查詢任務狀態;用戶端逾時後,4K 任務仍可能處於 in_progress

WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)


5. 定價與 FinOps ROI

Estimated cost=successful billable images×current account rate for that model, size, and resolution\text{Estimated cost} = \text{successful billable images} \times \text{current account rate for that model, size, and resolution}

  • 不要沿用舊單價,例如 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 指南。

本文提及的模型與介面

OpenAIIMAGE

GPT-Image-2

當前費率:3 credits /request
OpenAIIMAGE

GPT-Image-2 VIP

當前費率:3.38 credits /request

相關技術文章

tutorial6 分鐘閱讀

掌握 GPT Image 2 圖像編輯 API 的局部重繪與畫布外擴

按目前 GPT Image 2 約定編輯已有圖像:gpt-image-2 用參考圖做提示詞引導修改,gpt-image-2-official 用蒙版做精確局部重繪,兩者都走非同步的 generations 介面。

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2