tutorial6 分鐘閱讀

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

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

ToAPIs Engineering & Evaluation Team
TL;DR - 核心要點
  • 目前 ToAPIs 圖像約定是非同步的 POST /v1/images/generations,不是同步的 multipart /v1/images/edits,也不是名為 gpt-image-2-edit 的目錄型號。
  • 精確型號 gpt-image-2 通過 reference_images(僅限公開 URL,最多 14 張)做提示詞引導編輯。帶 Alpha 蒙版的像素級局部重繪,文件寫在 gpt-image-2-official 上,欄位是 mask_url 加上 image_urls。
  • size 是寬高比(如 1:1 或 16:9),resolution 是 1k、2k 或 4k 檔位。不要把 1024x1024 這種像素字元串當作 size。
  • 文件中沒有單獨的 outpaint 開關。要擴展畫布,把 size 改成目標比例,把原圖作為參考圖傳入,並在提示詞裡說明如何外擴。
  • 請持久化任務 id,並輪詢 GET /v1/images/generations/{id}。用戶端逾時並不等於任務失敗。

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

目標型號:gpt-image-2、gpt-image-2-official
推理介面:https://api.toapis.com/v1/images/generations
相關閱讀:GPT Image 2 API 指南 · 4K 寬高比工作流 · 全球鏡像與代理 · 官方局部重繪參考


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

  • 任務:替換已有圖像的局部區域(局部重繪),或把畫布擴展到新的寬高比(畫布外擴),同時不要發明第二套未文件化的介面。
  • 約定:只使用目錄中真實存在的型號。精確型號 gpt-image-2 接受 prompt、作為比例的 size、值為 1k / 2k / 4k 的 resolution,以及可選的 reference_images。帶蒙版的局部重繪文件寫在 gpt-image-2-official 上,欄位是 image_urls 加上 mask_url。
  • 不屬於目前約定:名為 gpt-image-2-edit 的型號、同步的 multipart POST /v1/images/edits,或 size: "1024x1024"。這些形態出現在舊稿中,不應再複製到新用戶端。
  • 輸入輸出:先用 POST /v1/uploads/images 上傳原圖和蒙版,再傳入返回的公開 URL。reference_images、image_urls 和 mask_url 都不接受 base64。
  • 非同步協定:提交調用返回任務 id。輪詢 GET /v1/images/generations/{id},直到 completed 或 failed。用戶端逾時並不等於任務失敗。

2. 可編程圖像編輯的實際價值

用提示詞從零生成只是第一步。生產環境中的商品圖、廣告和設計系統,更常見的需求是定向修改:更換單品、清理背景,或把方形包裝圖拉成寬屏頭圖,同時儘量保留光線和主體特徵。

目前 ToAPIs 的 GPT Image 2 系列把這些工作放在同一條路徑上:POST /v1/images/generations,區別只在型號:

任務型號 ID如何指向原圖是否使用蒙版
提示詞引導的編輯或風格遷移gpt-image-2reference_images(URL 列表,最多 14 張)該型號無文件化蒙版欄位
像素級局部重繪gpt-image-2-officialimage_urls(URL 列表,最多 16 張)須與首圖一起提供 mask_url
畫布外擴兩個型號均可把原圖作為參考圖,並把 size 改成目標比例沒有單獨的 outpaint 開關

在精確型號 gpt-image-2 上,image_urls 是 reference_images 的向後兼容別名,閘道會做歸一化。官方渠道參考裡的示例把 image_urls 與 mask_url 一起使用。請按你實際調用的型號,使用對應參考中的欄位名。

可用的局部重繪蒙版是帶 Alpha 通道的 PNG,像素尺寸必須與第一張參考圖一致。透明像素(alpha = 0)是重繪區域,不透明像素應被保留。可在流水線中用 Pillow 等工具生成蒙版,先上傳,再只發送 URL。

畫布外擴是一種工作流,不是單獨的介面。如果你有一張 1:1 包裝圖,需要 16:9 頭圖:把原圖作為參考圖,將 size 設為 16:9,顯式指定 resolution 檔位,並在提示詞中要求保留主體、擴展場景。一種實用變體是把原圖合成到更大的透明畫布上,上傳後再作為參考圖——仍然走 /v1/images/generations,仍然沒有 outpaint: true 這類開關。

蒙版島狀畫框經六邊形閘道流入擴展後的畫布

圖 1:原圖畫布與內部蒙版區域經過 ToAPIs 閘道;文件化路徑仍是 POST /v1/images/generations,mask_url 僅用於 gpt-image-2-official。

size 與 resolution 的約定與文生圖相同:size 是 1:1 或 16:9 這樣的比例,resolution 是 1k、2k 或 4k。精確型號 gpt-image-2 在目前 Playground 約定中不暴露 quality 欄位;quality(low / medium / high)出現在 gpt-image-2-official 上。像素對照表見 4K 工作流指南。


3. 生產級實作:cURL 與 Python

本系列的國際示例使用 https://api.toapis.com。官方文件要求中國大陸使用者使用 https://toapis.cn。每個環境只保留一個源站。路徑、型號 ID 和 Bearer 頭保持不變。

步驟 1:上傳原圖(如需蒙版,一併上傳)

bash
curl -X POST "https://api.toapis.com/v1/uploads/images" \
  -H "Authorization: Bearer $TOAPIS_API_KEY" \
  -F "file=@./product.png"

響應中包含 data.url。若調用的是 gpt-image-2-official,請對蒙版 PNG 再執行一次同樣的上傳。不要在生成請求裡內聯 base64。

步驟 2:在精確型號 gpt-image-2 上做提示詞引導編輯

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": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
    "size": "1:1",
    "resolution": "1k",
    "n": 1,
    "response_format": "url",
    "reference_images": ["https://example.com/product.png"]
  }'

步驟 3:在 gpt-image-2-official 上做蒙版局部重繪

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-official",
    "prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "image_urls": ["https://example.com/photo.png"],
    "mask_url": "https://example.com/mask.png"
  }'

步驟 4:Python 提交與輪詢

欄位名請與你所調用型號的 API 參考保持一致。下面的片段使用文件中的圖像狀態路徑,以及 completed / failed 狀態。

python
import os
import time
import requests

API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def upload_image(path: str) -> str:
    with open(path, "rb") as handle:
        res = requests.post(
            f"{BASE}/v1/uploads/images",
            headers=HEADERS,
            files={"file": handle},
            timeout=60,
        )
    res.raise_for_status()
    url = res.json().get("data", {}).get("url")
    if not url:
        raise RuntimeError(f"Unexpected upload envelope: {res.text}")
    return url


def dispatch_edit(payload: dict) -> str:
    res = requests.post(
        f"{BASE}/v1/images/generations",
        headers={**HEADERS, "Content-Type": "application/json"},
        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__":
    source = upload_image("product.png")
    # Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
    task_id = dispatch_edit(
        {
            "model": "gpt-image-2",
            "prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
            "size": "16:9",
            "resolution": "1k",
            "n": 1,
            "response_format": "url",
            "reference_images": [source],
        }
    )
    print("Task:", task_id)
    print("Image:", poll_image_task(task_id))

若要改為蒙版局部重繪,請先上傳與首圖尺寸一致的 RGBA 蒙版,將 model 改為 gpt-image-2-official,並發送 image_urls 與 mask_url。請把型號 ID、size 和 resolution 與任務記錄一起保存,以便日後更換型號時是一次明確的決策。


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

下表只是排查起點,並不保證與 ToAPIs 的精確錯誤碼一一對應。即便 HTTP 提交成功,仍須讀取任務的 status。

HTTP 狀態常見類別建議操作
400欄位無效或不支援的組合確認型號 ID、size 是已文件化的比例、resolution 是 1k / 2k / 4k、URL 可公開訪問;若使用蒙版,須是與首圖同尺寸、帶 Alpha 通道的 PNG,且型號為 gpt-image-2-official
401API 密鑰缺失或無效在 ToAPIs 控制臺輪換密鑰,並確認 Authorization 頭
429速率或並發限制若響應含 Retry-After 請遵守;加入抖動後退避;僅在安全時重試
5xx 或網絡逾時閘道或上遊暫時異常重新提交前先查詢任務狀態;使用有上限的重試策略

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}

  • 不要沿用規劃舊稿中的單價,例如固定的 $0.024 / $0.048「標準 vs HD」組合。這些數字已與目前目錄脫節;目前目錄按型號 ID 計價,標準 GPT Image 2 的投放頁對照還按解析度檔位區分。
  • GPT Image 2 模型指南 目前展示的 ToAPIs 投放對照價,是標準 gpt-image-2 在 1K / 2K / 4K 下每張 $0.015 / $0.020 / $0.025。請把它視為列表對照價,而不是合同帳單。官方渠道型號和帳戶折扣可能不同;請確認你實際調用的型號費率。
  • 選擇 api.toapis.com 還是 toapis.cn 只是源站選擇,並不是文件中的折扣。FinOps 收益來自用 1k 打樣、避免用戶端逾時後重複提交,以及選對型號(gpt-image-2 與 gpt-image-2-official),而不是臆造一個更便宜的「編輯」型號。
  • 背景閱讀見 GPT Image 2 定價文章,寫入預測前請用即時目錄核對每一個數字。

6. 常見問題

詳見 frontmatter 中的 FAQ。摘要:精確型號 gpt-image-2 沒有文件化的 mask_url 或 /v1/images/edits;蒙版局部重繪寫在 gpt-image-2-official 上;蒙版必須是同尺寸的 RGBA PNG,並以 URL 傳遞;畫布外擴是改 size 並傳入參考圖;計費須按準確的型號 ID 在帳戶中確認。


7. 行動清單

  • 在 ToAPIs 開發者門戶 建立密鑰。
  • 為每個環境設定一個基址(https://api.toapis.com,或在需要時使用 https://toapis.cn),並用 POST /v1/uploads/images 上傳一張原圖。
  • 用 gpt-image-2 做一次提示詞引導編輯冒煙測試:傳入 reference_images,size: "1:1",resolution: "1k"。
  • 若需要像素級蒙版,切換到 gpt-image-2-official,上傳與首圖尺寸一致的 RGBA 蒙版,並發送 image_urls 與 mask_url。
  • 持久化任務 id,在有限時限內輪詢 GET /v1/images/generations/{id},並在 429 時遵守 Retry-After。
  • 接下來:若要提高 resolution,閱讀 4K 寬高比指南;更完整的參數表見 API 指南。

本文提及的模型與介面

OpenAIIMAGE

GPT-Image-2

當前費率:3 credits /request
OpenAIIMAGE

gpt-image-2-official

當前費率:Input 800 credits/1M, Output 4,800 credits/1M

相關技術文章

tutorial6 分鐘閱讀

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

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

TO
ToAPIs Engineering & Evaluation Team
#GPT Image 2