GPT Image 2 / 2.5 API — Generation and Image Editing

Use generations for text-to-image and multipart edits for reference images with GPT Image 2, Sunburst and Flare. Includes single-image, multi-image, Python and async examples.

GPT Image 2 / 2.5:生成與圖像編輯

在撰寫請求前先選擇端點:文字轉圖像使用 /images/generations;圖像轉圖像使用 /images/edits 並上傳圖像檔案。 在提示詞中提到「參考圖像 1」並不會附加任何圖像。

模型與端點

模型 ID	文字轉圖像	圖像轉圖像
`gpt-image-2`	`/images/generations`	`/images/edits` + 圖像檔案
`gpt-image-2.5-sunburst`	`/images/generations`	`/images/edits` + 圖像檔案
`gpt-image-2.5-flare`	`/images/generations`	`/images/edits` + 圖像檔案

這些是不同的模型 ID。切換模型時請明確修改 model;GPT Image 2.5 不是 GPT Image 2 的別名。請在市集查看目前的可用性與帳戶定價。

操作	方法與端點	請求格式
文字轉圖像	`POST https://apimaster.ai/v1/images/generations`	JSON
圖像轉圖像 / 編輯	`POST https://apimaster.ai/v1/images/edits`	`multipart/form-data` 附上實際圖像檔案
非同步圖像編輯	`POST https://apimaster.ai/v1/images/edits/async`	與編輯相同的多部分檔案;回傳任務 ID
非同步文字轉圖像	`POST https://apimaster.ai/v1/images/generations/async`	JSON;回傳任務 ID
查詢任務	`GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID`	Bearer 認證

若要取得圖像編輯的任務回應,請使用 /images/edits/async。 上傳與同步編輯相同的檔案與欄位,然後查詢 /tasks/{task_id}。請勿將編輯請求移至 generations/async。這些任務端點沿用了既有的非同步合約:非同步上游可以即時回傳任務,而同步上游可能會在閘道回傳任務 ID 之前就完成編輯。這並不保證立即在背景執行。這些模型請勿使用 Chat Completions。

認證與逾時

建立 API 金鑰並傳送 Authorization: Bearer YOUR_API_KEY。JSON 生成請求使用 Content-Type: application/json。對於檔案上傳,請讓 cURL 或您的 HTTP 函式庫產生多部分邊界;請勿手動設定 Content-Type 標頭。

基本請求請預留至少 180 秒,較高解析度請預留 300 秒,高難度編輯或高品質請求請預留 600 秒。用戶端逾時並不代表上游請求已停止。請避免立即重複提交。

文字轉圖像:JSON 生成

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

對於 Sunburst 或 Flare,請將模型 ID 替換為 gpt-image-2.5-sunburst 或 gpt-image-2.5-flare。請勿在此範例中加入參考圖像;請使用下方的編輯範例。

圖像轉圖像:上傳單一參考

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

請將 reference.png 替換為實際存在的本機圖像。@ 告訴 cURL 上傳檔案位元組;image=reference.png 只會傳送檔名字串。此端點模式同樣適用於 gpt-image-2 和 gpt-image-2.5-sunburst。

圖像轉圖像:上傳多個參考

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

請依照提示詞所述順序,為每個檔案重複相同的 image[] 欄位。n 是輸出圖像的數量,而非參考圖像的數量。參考圖像數量限制取決於所選模型與可用路由;請勿假設有通用的 16 張圖像上限。請從單一參考與 n=1 開始,再視需要增加輸入。

Python 編輯範例

請安裝 requests。此範例會上傳真實檔案,並處理 URL 與 base64 兩種圖像回應。

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

若有多個檔案,請將重複的 ("image[]", (filename, file_object, mime_type)) 項目以清單形式傳遞給 files。在請求完成前,請保持每個檔案為開啟狀態。

非同步圖像編輯

當您的應用程式使用任務 ID 時,請搭配 GPT Image 2、Sunburst 或 Flare 使用此端點。檔案上傳規則、參考順序、能力限制與認證方式與同步編輯相同。

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

提交後會回傳 data[0].task_id。請使用相同的模型 ID 輪詢:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

已完成的追蹤任務具有以下結構;每張生成的圖像都會包含在內:

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

任務屬於提交該任務的帳戶。請使用該帳戶的有效 API 金鑰進行查詢。提交失敗會回傳錯誤而非可用的任務;一旦任務 ID 已回傳,請持續輪詢該任務,而不要再次提交編輯。請參閱下方的輪詢狀態表。

既有的 URL 或 base64 整合

如果您的輸入是 URL,請在應用程式中下載該圖像,並將其位元組上傳至 /images/edits。如果是 base64 資料 URI,請將內容解碼為檔案或位元組緩衝區後再上傳。請勿將 URL 或 base64 文字當作檔案上傳來提交。

部分 GPT Image 2 路由在 generations 上支援 image_urls 擴充功能。這並不是可攜的圖像編輯合約,且不可假設其適用於 GPT Image 2.5。 新的整合應使用上方的多部分編輯範例。包含 image_urls、image 或 images 的 JSON 請求,並不等同於將檔案上傳至編輯端點。

參數與能力限制

欄位	用法
`model`	必填;請使用上表中的確切模型 ID
`prompt`	必填;描述結果與參考順序
`image` / `image[]`	編輯時實際上傳的檔案;基本範例請使用 PNG 或 JPEG
`n`	輸出圖像數量;請從 `1` 開始;上限取決於路由
`size`	選填;`1024x1024` 是基本範例;其他像素尺寸或長寬比取決於路由
`resolution`	選填的路由特定擴充功能,例如 `1k`、`2k`、`4k`;並非每個模型/路由都支援每個層級
`quality`	選填;可接受的值與成本取決於路由
`background`、`output_format`、`output_compression`	選填;透明度與輸出編碼需要路由支援
`mask`	僅限 GPT Image 2,且需可用的編輯路由支援上傳遮罩;目前的 GPT Image 2.5 多部分處理器不支援

對於 GPT Image 2,遮罩支援必須與一般參考編輯分開確認。相容的 PNG 遮罩必須符合輸入尺寸並包含 Alpha 通道。目前的 GPT Image 2.5 多部分端點會拒絕上傳的遮罩檔案;請勿在上方的 Sunburst 或 Flare 範例中加入遮罩。在未確認所選路由之前,請勿假設支援 JSON mask_url 的替代做法。

只傳送您需要的選填欄位。這些欄位可能會改變可用的路由與價格;明確設定預設值不一定等同於省略它。沒有任何固定的像素尺寸表或進階參數清單可以一致地套用於所有三個模型 ID。實際定價與支援的能力以市集與請求回應為準。

同步回應

成功的生成或編輯會在 data 中回傳圖像條目:

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

視路由與輸出格式而定,條目也可能改為包含 b64_json。請將其解碼為圖像位元組。請及時下載暫時性的結果 URL。HTTP 200 回應或僅憑圖像數量並不能證明參考細節被保留;請將結果與輸入進行比對檢查。

非同步任務:提交與輪詢

對於文字轉圖像,請在不含參考圖像的情況下,以 JSON 提交至 generations/async。對於圖像編輯,請使用上方的多部分 edits/async 範例。兩者使用相同的任務查詢端點:

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

提交回應的外層結構通常會回報 submitted;上游也可能已回報完成狀態。第一次輪詢時任務可能已經完成。任務 ID 並不保證立即回應:如果所選上游是同步的,平台會等待生成完成後才回傳任務。請保留足夠的提交逾時時間。

請使用與提交時相同的模型 ID 進行輪詢:

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

任務狀態	處理方式
`pending`、`submitted`、`processing`、`in_progress`	等待;3–5 秒後再次查詢
`succeeded`、`success`、`completed`	讀取 `data.result.images` 中的每個條目;追蹤任務使用字串型 `url`,而舊版上游回應可能使用 URL 陣列
`failed`、`error`、`cancelled`	停止輪詢並檢查錯誤

請設定有限的整體輪詢期限,例如 10 分鐘。若期限已過,請保留任務 ID 以供稍後檢查,而不要自動建立另一個付費任務。任務查詢回應與同步圖像回應的結構不同。

參考圖像疑難排解

確認實際的請求路徑是 /v1/images/edits 或 /v1/images/edits/async,而非 generations 或 generations/async。
確認多部分內容在 image 或重複的 image[] 下包含檔案位元組,並具有自動產生的邊界。提示詞文字、檔名與參考數量無法取代檔案。
檢查確切的模型 ID。GPT Image 2 的擴充功能不會自動被 Sunburst 或 Flare 支援。
如果任務/日誌詳情中沒有預覽,請勿斷定未發送任何圖像:日誌可能會省略 base64 資料與已上傳檔案的內容。反之,日誌中記錄的參考數量也不能證明上游確實使用了這些圖像。
使用包含獨特文字或形狀的簡單參考圖像進行測試,並在不描述那些細節的情況下要求更換背景。以目視比較輸出結果。
若需支援,請保留請求 ID(X-Oneapi-Request-Id)、任務 ID(如存在)、模型、端點、時間戳記、已清理的請求欄位與參考圖像。切勿分享您的 API 金鑰。

若收到 400 回應,請檢查端點與參數的相容性;401 表示認證失敗;429 表示速率/配額限制。若發生逾時或上游失敗,請保留請求/任務 ID,並在重新提交前先檢查既有任務或用量紀錄。