作者注:已經在 API易 用 Responses 的 image_generation 做“邊聊邊出圖”的開發者,遷移到獨立 Images API 後,可以按本文的方法保留連續改圖。
結論先行:只遷移出圖這一段,原有的文字對話不用動。以前靠 previous_response_id 隱式接上的“上一張圖”,現在由你的應用自己保存,並在每次改圖時明確選中,作爲原圖上傳給 POST /v1/images/edits。這樣做之後,多輪改圖的效果不變,變的只是“上一張圖”由誰來記住。
這條結論成立的前提,是 API易 在 2026-11-21 22:30(北京時間)發佈的文檔更新。五款官轉圖像模型改爲推薦走兩條獨立圖片端點。OpenAI 並沒有停用 Responses,站內的文字對話也照常可用。下文所有接口、字段和計費口徑都來自 API易 apiyi.com 文檔和 OpenAI 官方圖像生成指南。代碼屬於文檔示例,不代表實測結果。

GPT Image API 遷移知識地圖與索引
整個遷移按四步推進,每一步的輸出就是下一步的輸入:
辨認舊調用並分路由 (第1節)
└─> 輸出: 每個請求該走對話、generations 還是 edits
生成並存下第一張圖 (第2.1節)
└─> 輸出: 已校驗的 v1.png + 資產記錄
把選中的原圖交給編輯接口 (第2.2節)
└─> 輸出: v2.png + parent_asset_id 關聯
驗收和核賬 (第3節)
└─> 輸出: 可用圖片列表 + 每張驗收圖成本

| 步驟 | 依賴什麼 | 爲什麼排在這裏 | 目標 |
|---|---|---|---|
| 1 分路由 | 現有代碼裏的調用清單 | 先確定改哪裏,纔不會誤改文字對話 | 只把出圖請求切到 Images API |
| 2.1 首次出圖 | 第 1 步確定的 generations 路由 | 後續改圖需要一張真實保存的原圖 | 得到校驗過的 v1 併入庫 |
| 2.2 繼續改圖 | 第 2.1 步保存的 v1 文件 | 獨立端點不認 previous_response_id,只認你上傳的圖 |
得到 v2,並記下父子關係 |
| 3 驗收核賬 | 第 2 步的圖片與控制檯日誌 | 只有驗收通過的圖才計入成本分母 | 可交付圖片 + 可解釋的賬單 |
閱讀順序建議:第 1 節必讀;第 2 節按代碼順序跟着做;第 3 節在上線前或出現斷連、賬單疑問時查閱。
To Know:GPT Image API 遷移術語
| 術語 | 簡明解釋 |
|---|---|
| 官轉 | API易 提供的官方轉發通道模型,本文指五款圖像模型 ID |
| image_generation | Responses API 裏的圖片生成工具,舊鏈路通過它邊聊邊出圖 |
| previous_response_id | Responses 用來延續上一輪上下文的參數,獨立 Images 請求不接收 |
| multipart | 表單上傳格式,/images/edits 用它傳真實圖片二進制 |
| b64_json | 獨立圖片端點返回圖片的字段,內容是 base64 編碼的圖片 |
| parent_asset_id | 應用自行記錄的“這張圖由哪張圖改來”的關聯字段 |
1 哪些 GPT Image API 調用需要從 Responses 遷移
1.1 GPT Image API 11/21 動態的範圍與五款官轉
這次文檔更新涉及以下五個官轉模型 ID:
gpt-image-2.6-sunburstgpt-image-2.6-flaregpt-image-2.5-sunburstgpt-image-2.5-flaregpt-image-2
對應的兩條獨立圖片端點分別是 POST /v1/images/generations(JSON 請求體)和 POST /v1/images/edits(multipart 表單)。API易 不推薦繼續用 Responses 的 image_generation 鏈路出圖,原因有兩個:一是供應不穩定,二是會產生額外的工具費。另外,Chat Completions 不支持用這五款官轉圖像模型出圖,舊代碼裏如果有這種用法,也要一起歸到遷移清單裏。
需要說明的是,這次調整隻影響出圖。OpenAI 沒有停用 Responses,API易 站內的文字對話也沒有停用。所以遷移範圍只限於“請求裏調用了圖片工具或圖像模型”的那部分代碼。五款模型之間怎麼選,屬於另一個話題,可以查看 API易 apiyi.com 幫助中心的模型選型文章,本文不展開。
1.2 GPT Image API 文字對話、首次出圖與繼續改圖的路由
API易 的 FAQ 給出的組合方式是:對話模型負責判斷用戶意圖,應用再單獨調用 Images API 並自己管理圖片。按這個思路,原來一個 Responses 請求包辦的三件事,可以拆成三條路由:
| 用戶意圖 | 新路由 | 請求格式 | 圖片來源 |
|---|---|---|---|
| 純文字聊天、問答 | 保持原有文字對話接口 | 不變 | 無 |
| 第一次出圖 | POST /v1/images/generations |
JSON | 僅 prompt |
| 在某張圖上繼續改 | POST /v1/images/edits |
multipart | 應用上傳已選中的原圖 |
在原生 Responses 裏,延續改圖可以通過 previous_response_id 實現,也可以直接傳入圖片。獨立的 Images 請求不接收 previous_response_id,這就是“多輪改圖”需要由應用接管的根本原因。模型不再替你記住上一張圖,你得把那張圖的文件交給它。
如果用戶說“再紅一點”,但會話裏已經有 v1、v2、v3 好幾版,應用無法確定指的是哪一版,這時應該先向用戶確認,不要猜。默認用最新一版看起來省事,但一旦用戶其實想回到 v2 重新改,就會白白多一次扣費,還會把用戶搞糊塗。
響應解析也要跟着改:

| 鏈路 | 圖片在響應中的位置 | 上下文延續方式 |
|---|---|---|
| Responses + image_generation | output 中 type=image_generation_call 那一項的 result |
previous_response_id 或傳圖 |
| 獨立 Images API | data[0].b64_json |
應用上傳已選原圖 |
2 GPT Image API 如何續改上一張圖
下面用一個兩輪的例子說明完整流程。第一輪生成一隻藍色馬克杯,第二輪只把杯身改成磚紅色。參數沿用 API易 文檔示例:模型 gpt-image-2.5-sunburst,尺寸 1024x1024,quality=medium,output_format=png。令牌從環境變量 APIYI_KEY 讀取,以 Bearer 方式傳入。
2.1 GPT Image API 生成並校驗藍色馬克杯 PNG
第一輪調用 generations 端點,提示詞描述的是:淺灰背景,藍色陶瓷馬克杯居中,把手朝右,柔和側光,畫面裏沒有文字。拿到響應後按以下順序處理:
- 調用
raise_for_status(),先排除 HTTP 層面的失敗。 - 對
b64_json做嚴格 base64 解碼,解不開就算失敗。 - 用 Pillow 打開並調用
load(),確認文件真的能解碼成圖片。 - 確認格式是 PNG、尺寸是 1024×1024,然後保存爲
v1.png。 - 在應用裏登記這份資產,後續改圖從這裏取原圖。
第 3 步不能省。open() 只讀取文件頭,圖片數據有沒有截斷,要等到 load() 纔會暴露出來。
2.2 GPT Image API 上傳已選原圖,僅把杯身改磚紅
第二輪調用 edits 端點。data 裏傳 model、prompt、size、quality、output_format,files 裏用 image[] 字段上傳 v1.png 的真實二進制。提示詞的意思是:只把杯身改成磚紅色,杯形、把手、構圖、光線和背景都保持不變。
這一步有幾個容易出錯的地方:
- 不要傳
response_format。 - 不要手寫
Content-Type。requests 會自動生成帶 boundary 的 multipart 頭,手寫反而會把 boundary 弄丟。 - 不要把 base64 字符串當作文件上傳,上傳的必須是圖片的原始字節。
改完後用同樣的方式解碼、校驗,保存爲 v2.png。v1 要保留,同時在資產記錄裏寫上 parent_asset_id = v1。這條父子關係,就是新架構下的“多輪上下文”。還要注意,這是生成式編輯,模型會盡量保留其他區域,但不保證除杯身以外的像素逐一相同。
以下是最小完整示例(文檔示例,未在本文中實測):
import base64
import io
import os
import uuid
import requests
from PIL import Image
BASE_URL = "https://api.apiyi.com/v1" # API易 unified endpoint
API_KEY = os.environ["APIYI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
MODEL = "gpt-image-2.5-sunburst"
SIZE = "1024x1024"
# Example mid-range timeout; tune for your network and quality. No auto retry.
TIMEOUT = (10, 360)
assets = {} # asset_id -> {"path": ..., "parent_asset_id": ...}
def decode_and_check(resp, path):
resp.raise_for_status()
item = resp.json()["data"][0]
b64 = item.get("b64_json")
if not b64:
raise ValueError("no b64_json in response, check body before any resend")
raw = base64.b64decode(b64, validate=True)
img = Image.open(io.BytesIO(raw))
img.load()
if img.format != "PNG" or img.size != (1024, 1024):
raise ValueError(f"unexpected image: {img.format} {img.size}")
with open(path, "wb") as f:
f.write(raw)
return path
def save_asset(path, parent_asset_id=None):
asset_id = str(uuid.uuid4())
assets[asset_id] = {"path": path, "parent_asset_id": parent_asset_id}
return asset_id
# Round 1: text-to-image via JSON
gen_resp = requests.post(
f"{BASE_URL}/images/generations",
headers=HEADERS,
json={
"model": MODEL,
"prompt": (
"Light gray background, a blue ceramic mug centered, "
"handle facing right, soft side lighting, no text."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
timeout=TIMEOUT,
)
v1_id = save_asset(decode_and_check(gen_resp, "v1.png"))
# Round 2: edit the explicitly selected original via multipart
selected_id = v1_id # if the user's target version is unclear, ask first
with open(assets[selected_id]["path"], "rb") as f:
edit_resp = requests.post(
f"{BASE_URL}/images/edits",
headers=HEADERS, # no manual Content-Type; requests sets the boundary
data={
"model": MODEL,
"prompt": (
"Change only the mug body to brick red. Keep the mug shape, "
"handle, composition, lighting and background unchanged."
),
"size": SIZE,
"quality": "medium",
"output_format": "png",
},
files={"image[]": ("v1.png", f, "image/png")},
timeout=TIMEOUT,
)
v2_id = save_asset(decode_and_check(edit_resp, "v2.png"), parent_asset_id=selected_id)
print(assets)
示例裏 timeout=(10, 360) 只是文檔中的中檔設置,實際取值要結合你的網絡鏈路和畫質檔位來定。示例也刻意沒有寫自動重試,原因見 3.2 節。
🚀 快速驗證:把
APIYI_KEY設爲你在 API易 apiyi.com 控制檯創建的令牌,上面的腳本就能跑完兩輪流程。新用戶可以先用免費測試額度確認路由和解析邏輯,再切換生產流量。

3 GPT Image API 遷移後怎麼驗收並核賬
3.1 GPT Image API 圖片驗收的四道關
只有四道關全部通過,一張圖才能在應用裏標記爲“可用”:
- HTTP 成功:
raise_for_status()沒有拋出異常。 - 可解碼:嚴格 base64 解碼成功,Pillow
load()成功。 - 規格正確:格式和尺寸與請求一致,本例是 PNG、1024×1024。
- 視覺改動確實發生:v2 的杯身確實變成了磚紅色,杯形、把手、構圖和背景基本保持。
第 4 關需要人工檢查或單獨的審覈環節,因爲 HTTP 狀態碼看不出模型有沒有改對。只通過前三關的圖,最多算“技術上有效”,還不能交付。如果響應里根本沒有圖片,應該先檢查響應內容再決定是否重試,這個問題在幫助中心有專門的文章討論,本文不重複。
3.2 GPT Image API 舊工具費與每張驗收圖成本
遷移前後,賬單口徑是不同的:
| 項目 | 舊 Responses image_generation 鏈路 | 獨立 Images API |
|---|---|---|
| 額外費用 | 約 $0.20 的 API易 圖片工具額外調用費 | 無此項工具費 |
| 該數字的含義 | 僅指這筆額外工具費,不是整單價格,也不是 OpenAI 的通用價格 | 按量計費 |
| 適合的比較方式 | 按“每張驗收圖成本”比較 | 按“每張驗收圖成本”比較 |
不要只拿單價對比,建議統一用下面這個公式:
每張驗收圖成本 = 相關實際扣費(含所需文本調用、已扣費的失敗請求和重試)÷ 驗收通過的圖片數
分子要把所有相關扣費都算進去,包括判斷意圖的對話調用、已扣費的失敗請求和重試。分母只計入通過 3.1 節四道關的圖。如果一張通過的圖都沒有,就不要計算單張成本,因爲這時的結論應該是“流程有問題”,而不是“單價很高”。遷移能省多少錢,取決於你的重試率和驗收通過率,本文不給具體比例。
核賬的數據來自控制檯消費日誌,其中消費記錄的 type=2。如果讀取的是 quota 字段,按平臺文檔用 quota ÷ 500000 換算成金額。
斷連的處理要特別注意。獨立圖片端點是同步返回的,連接中途斷開時,這次請求可能已經扣費,而且無法通過 request ID 找回圖片。正確的順序是:先到 API易 apiyi.com 控制檯的消費日誌確認這次請求是否扣費,再決定要不要補發。這也是示例代碼沒有寫自動重試的原因,自動重試很容易在斷連時造成重複扣費。如果遇到限流或者需要切換通道,可以參考幫助中心關於通道選擇與 429 降級的文章。
遷移完成的檢驗標準很直接:文字對話照常可用;首輪出圖穩定返回可以通過四道關的 v1;每次改圖都能在資產記錄裏查到明確的 parent_asset_id;控制檯日誌裏每一筆圖片扣費都能對應到一張驗收圖、一次已知的失敗,或者一次有記錄的補發。這幾項都滿足後,就可以把剩餘的 Responses 出圖流量切到 Images API。需要多模型對照測試時,API易 apiyi.com 提供統一的 OpenAI 兼容接口,換模型時只需修改 MODEL 一個參數。
參考資料
-
API易 文檔更新:官轉圖像模型改走 Images API
- 鏈接:
docs.apiyi.com/live/2026-11/gpt-image-official-relay-images-api - 說明:五款官轉 ID、兩條獨立端點和不推薦舊鏈路的原因
- 鏈接:
-
API易 FAQ:一個 API 裏同時處理文字與圖片
- 鏈接:
docs.apiyi.com/faq/text-and-image-in-one-api - 說明:對話模型判斷意圖、應用單獨調用 Images API 的組合方式
- 鏈接:
-
OpenAI 圖像生成指南
- 鏈接:
developers.openai.com/api/docs/guides/image-generation - 說明:Responses 的延續編輯方式與響應結構
- 鏈接:
-
API易 GPT Image 2 文生圖 / 圖片編輯
- 鏈接:
docs.apiyi.com/api-capabilities/gpt-image-2/text-to-image - 鏈接:
docs.apiyi.com/api-capabilities/gpt-image-2/image-edit - 說明:請求參數、multipart 上傳與解碼校驗示例
- 鏈接:
-
API易 Responses 圖片工具 / 圖片 API 最佳實踐 / 日誌查詢
- 鏈接:
docs.apiyi.com/api-capabilities/gpt-image-2/responses-image-tool - 鏈接:
docs.apiyi.com/api-capabilities/image-api-best-practices - 鏈接:
docs.apiyi.com/api-capabilities/log-query - 說明:工具費口徑、斷連處理與消費日誌換算
- 鏈接:
作者: APIYI 技術團隊
技術交流: 遷移中遇到路由或賬單問題,歡迎通過 API易 apiyi.com 首頁聯繫我們,更多接口細節可查閱 docs.apiyi.com 文檔中心
