GPT Image 2 全球鏡像與代理：為國際團隊降低存取延遲

目標模型: gpt-image-2
推理端點: https://api.toapis.com/v1/images/generations
相關閱讀: GPT Image 2 API 指南 · GPT Image 2 定價 · GPT-Image-2.6 API 指南

1. 核心摘要與性能速覽 (TL;DR)

• 任務：讓國際團隊的用戶端統一指向 ToAPIs 圖像閘道，而不是每次調用 gpt-image-2 都向廠商源站新建一條長距離連接。
• 約定：在 POST /v1/images/generations 上使用模型 ID gpt-image-2。目前文件中的欄位包括：prompt（最長 32,000 個字元）、作為寬高比的 size（如 1:1 或 16:9，不是 1024x1024 這種像素字串），以及作為檔位的 resolution（1k、2k 或 4k）。
• 區域：ToAPIs 官方文件要求中國大陸使用者使用基址 https://toapis.cn。本系列國際示例使用 https://api.toapis.com。路徑、模型 ID 和 Bearer 頭保持不變，只換源站。
• 非同步協定：圖像生成返回任務 id。輪詢 GET /v1/images/generations/{task_id}（或 GET /v1/tasks/{task_id}），直到 completed 或 failed。用戶端牆上的等待時間不等於生成時間，逾時也不等於任務失敗。
• 本文不聲稱的內容：不會給出未經核實的接入點名單、握手耗時或端到端延遲目標。這些數字請在你自己的鏈路上測量。參數細節和 SKU 對比見 API 指南 與 2.6 指南。

2. 透過 ToAPIs 閘道為國際團隊就近接入

遠距離團隊感受到的往往是兩段不同的耗時：建立連線的時間，以及模型真正渲染的時間。把它們混成一句「API 很慢」，優化對象就會找錯。前者是網路問題，可以用文件中更近的 ToAPIs 源站，並重用已建立的 HTTP 工作階段來處理；後者是生成時間，要在任務被接受之後再觀察。

ToAPIs 提供統一的圖像生成路徑。官方文件目前寫的是 https://toapis.com，並提醒中國大陸使用者把源站換成 https://toapis.cn。本系列包括 GPT Image 2 API 指南 在內的文章，則把同樣的路徑發到 https://api.toapis.com。每個環境只選一個基址，寫成設定，不要在同一服務裡混用多個源站。

圖 1：讓用戶端停留在同一個已文件化的 ToAPIs 源站上，重用工作階段，並把圖像生成當作非同步任務，而不是一次超長的同步往返。

這些路由習慣不依賴未公布的延遲數字：

• 每個環境一個源站。 新加坡和法蘭克福的服務可以共用同一模型 ID 和請求體，但不應各自發明廠商 URL。
• 復用連接。 打開 HTTP keep-alive（若用戶端已支援 HTTP/2 也可啟用），避免每次提交或輪詢都重新做 TLS。
• 把提交和等待拆開。 立即持久化任務 id。按有上限的間隔輪詢，或優先使用 任務 Webhook，把輪詢留作兜底。
• 不要把「相同提示詞走邊緣快取」當成省錢手段。 ToAPIs 並未在文件中保證重複提示詞會由邊緣快取免費返回。只要提交了兩次任務，就要按兩次計費來規劃，除非你的帳戶條款另有說明。

請求約定也容易過時。較舊的示例有時把 size 寫成 1024x1024，並帶上 quality: "standard"。目前的 gpt-image-2 API 參考和 ToAPIs 前端約定裡，size 表示寬高比（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），resolution 表示檔位（1k、2k、4k）。目前 Playground 約定裡，精確的 gpt-image-2 不暴露 quality 欄位；quality 出現在 gpt-image-2-vip 等 ID 上。請確認你實際調用的 ID。

參考圖放在 reference_images 中（僅限公開 URL，最多 14 張）。image_urls 是向後兼容的別名，會被規範成 reference_images。不要傳 base64，請先上傳。自定義比例、更多品質檔位或官方 SKU 行為，見 API 指南 和 模型指南。

3. 生產級實作：cURL 與 Python

步驟 1：用 cURL 提交

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": "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url"
  }'

步驟 2：Python 提交與輪詢

欄位名和回應包絡請以你帳戶的 API 參考為準。示例使用文件中的圖像狀態路徑以及 completed / failed 狀態。只有在應當使用中國大陸源站的環境裡，才把 BASE 換成 https://toapis.cn。

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 = "1:1",
    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 = 180) -> 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__":
    task_id = dispatch_image(
        "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography"
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

把基址、模型 ID、size 和 resolution 與任務記錄放在一起。若以後把用戶端從 gpt-image-2 換到 gpt-image-2-vip 或 2.6 的 SKU，一次只改一個變量，並重讀對應指南——計費單位並不自動相同。

4. 錯誤處理與狀態碼對照

下表只是排查起點，並不保證與 ToAPIs 的精確錯誤碼一一對應。HTTP 查詢成功後，仍然要讀取任務 status。

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

5. 定價與 FinOps ROI

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

• 不要沿用策劃稿或舊文章裡的單價。 目錄價格、解析度倍率和失敗任務的處理方式會隨 SKU 和帳戶變化。部分 GPT Image 2.x ID 按張計費；2.6 指南 說明該世代按 token 計費。請確認你實際調用的模型 ID 對應的費率。
• 換線路本身不會自動改變模型單價。 使用 api.toapis.com 還是 toapis.cn 只是基址選擇，文件並未把它寫成折扣。FinOps 收益來自避免用戶端逾時後重複提交、先用 1k 打樣，以及選對 SKU。
• 廠商直籤合同 常帶區域結算限制、年框或預付門檻。ToAPIs 計費通常是按量付費，請以帳戶目前條款為準。
• 更細的費率討論可以把 GPT Image 2 定價文章 當作背景，但寫入預測之前，請用實時目錄核對每一個數字。

6. 常見問題

結構化問答見文章 frontmatter 中的 FAQ。摘要：更換 ToAPIs 源站不會改變模型 ID 或文件中的請求形態；中國大陸使用者應遵循官方文件中的 toapis.cn 說明；圖像任務是非同步的；size 是寬高比，resolution 是檔位；文件並未保證重複提示詞可走免費邊緣快取。

7. 行動清單

• 在 ToAPIs 開發者入口 建立金鑰。
• 為每個環境設置一個基址（https://api.toapis.com，或在需要時使用 https://toapis.cn），並用 gpt-image-2、size: "1:1"、resolution: "1k" 連通測試上面的 cURL。
• 持久化任務 id，對 GET /v1/images/generations/{id} 做有截止時間的輪詢，並在 429 時遵守 Retry-After。
• 接下來：參數細節看 GPT Image 2 API 指南；若要換 SKU，看 2.6 指南；新帳戶可參考 免費額度說明。