跳到正文

GPT Image

用 GPT Image 產生和編輯圖片:參數、回傳與注意事項。

項目值
Base URLhttps://api.hop-base.com/v1
產生圖片POST /v1/images/generations
編輯圖片POST /v1/images/edits
查詢非同步任務GET /v1/images/tasks?task_id=…
密鑰分組「GPT Image 全系」;gpt-image-2.5-flare 與 gpt-image-2.5-sunburst 也可用「GPT 官方直連(Azure)」

預設同步回傳 Base64 圖片,加上 Prefer: respond-async 可改為非同步任務;Codex Plus、Codex Pro 等只含對話模型的分組的密鑰呼叫 gpt-image-* 會回傳 404。「GPT 官方直連(Azure)」分組的生圖同步回傳 Base64。

可用型號

型號模型 IDquality 檔位官方價
GPT Image 2.6 Flaregpt-image-2.6-flarelow / medium / high / xhigh / max$5 / $30/ 百萬 tokens
GPT Image 2.6 Sunburstgpt-image-2.6-sunburstlow / medium / high / xhigh / max$5 / $30/ 百萬 tokens
GPT Image 2.5 Flaregpt-image-2.5-flarelow / medium / high / xhigh / max$5 / $30/ 百萬 tokens
GPT Image 2.5 Sunburstgpt-image-2.5-sunburstlow / medium / high / xhigh / max$5 / $30/ 百萬 tokens
GPT Image 2gpt-image-2low / medium / high$5 / $30/ 百萬 tokens

選型建議:日常出圖首選 Flare;要畫質選 Sunburst,同參數下比 Flare 略慢;gpt-image-2 是通用型號,ID 是 gpt-image-2,不是 gpt-image-2.0。參考耗時(單張 1024x1024):low 檔 2.5 兩個型號約 14 秒,high 檔 Flare 約 19 秒、Sunburst 約 37 秒。

GPT Image 2.6(2026-11-04 發布)與 2.5 同價,新增 complexity 參數與 SVG、GIF 動圖輸出;Flare 是速度檔,Sunburst 是畫質檔。參考耗時(單張 1024x1024):Flare low 約 14 秒、high 約 20 秒、xhigh 約 29 秒、max 約 46 秒;Sunburst low 約 29 秒、high 約 66 秒、xhigh 約 90 秒。

請求參數

產生

POST /v1/images/generations,JSON 請求內容。

參數必填型別與限制預設說明
model必填string—上表的 ID 之一
prompt必填string,≤ 32,000 字元—去除首尾空白後不能為空
size選填auto 或 寬x高—規則見表下
quality選填auto / low / medium / high—2.5 與 2.6 另有 xhigh / max
n選填integer,1–101部分分組只支援 1
background選填auto / opaque / transparent—透明需 png / webp
output_format選填png / jpeg / webp;2.6 另有 svg / gifpng決定解碼後的格式
output_compression選填integer,0–100100僅 jpeg / webp
moderation選填auto / low—不會關閉內容安全檢查
user選填string—終端使用者識別
stream選填booleanfalsetrue 改為 Images SSE
response_format選填string—請省略
input_fidelity選填low / high—相容欄位,請省略
complexity選填low / medium / highhigh僅 2.6;出圖前的規劃強度
frame_count選填integer,2–169僅 2.6 的 gif;幀數
frame_duration_ms選填integer,20–2,000200僅 2.6 的 gif;每幀毫秒數

size 的 寬x高 須為 16 的倍數,單邊 ≤ 3840,長短邊比 ≤ 3:1,總像素 655,360–8,294,400。不接受 1K / 2K / 4K 簡寫;不合規的 size 在產生前回傳 400,不計費。

quality 越高,輸出 token 越多、費用越高。response_format 傳什麼都以 b64_json 回傳;user 不是 HopBase 帳戶 ID,也不改變計費歸屬。

僅 GPT Image 2.6。complexity 控制模型出圖前做多少規劃,不另外收費,寫其他值會回傳 400。output_format: "svg" 回傳 SVG,n 必須為 1。output_format: "gif" 回傳 GIF 動圖:此時 size 是單幀尺寸,所有幀會拼在一張邊長不超過 3840 的圖上,請用 auto 或 512x512 這類小尺寸(單幀太大會失敗;GIF 單幀不受上面的總像素下限約束)。結果仍以 b64_json 回傳,解碼後存成 .svg 或 .gif。2.6 產生的圖帶有 OpenAI 的 C2PA 內容憑證,可用任何 C2PA 驗證工具核驗。

編輯

POST /v1/images/edits 接受上表全部參數,另加參考圖與遮罩。建議用 multipart/form-data(本機檔案),也接受 JSON(URL / Data URL)。

參數必填型別與限制預設說明
image必填1–16 張—multipart 用 image 或重複 image[]
mask選填帶 alpha 通道的 PNG—透明區域表示要編輯
markup選填透明 PNG 疊加層—僅 2.6;依標註修改,不能與 mask 同用

JSON 的 image 可以是 URL / Data URL 字串、字串陣列或 {"url": …} 物件。不讀 images,不接受裸 base64 或 file_id。

**標註引導編輯(僅 GPT Image 2.6)。**在與第一張輸入圖同尺寸的透明 PNG 上畫圈、箭頭或寫註記,作為 markup 傳入:multipart 用檔案欄位,JSON 用 URL 或 Data URL。模型依標註修改,例如紅圈加註記「在這裡加一片綠葉」。markup 不能與 mask 同時使用;網關保留它的透明通道,並縮放到第一張圖的尺寸。

遠端 URL 單張 ≤ 25 MiB,Content-Type 須為 image/*,且不能指向內網位址;轉送前可能壓縮到 4 MiB。整個請求內容上限 60 MB,超過回傳 413。

非同步

在產生或編輯請求加上 HTTP header Prefer: respond-async,請求內容不變。它是 header,不是 JSON 參數。

非同步任務只保留 model、prompt、n、size、quality、background、output_format、input_fidelity、complexity、frame_count、frame_duration_ms 和編輯用的圖片 / mask / markup,其餘欄位捨棄。

回傳結果

同步

欄位型別說明
createdintegerUnix 秒
data[].b64_jsonstringBase64 圖片,解碼後按 output_format 儲存
usage.input_tokensinteger輸入 token(可能回傳)
usage.output_tokensinteger輸出 token(可能回傳)
usage.total_tokensinteger合計(可能回傳)
usage.costnumber本次扣費的人民幣金額(與 usage.cost_usd 為同一筆扣費),最多 6 位小數。計費的同步成功回應都帶
usage.cost_usdnumber本次實際從餘額扣除的美元金額,最多 8 位小數,與使用記錄裡這一條相同
usage.currencystringusage.cost 的幣別,恆為 CNY
errorobject失敗時出現:message、type、code
{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1760,
    "total_tokens": 1802,
    "cost": 0.3264,
    "cost_usd": 0.048,
    "currency": "CNY"
  }
}

同步成功回應還帶本次實際扣費:回應內容的 usage.cost、usage.cost_usd 與 usage.currency,以及值相同的回應標頭 X-HopBase-Cost、X-HopBase-Cost-USD 與 X-HopBase-Currency。產生耗時較長(約 40 秒以上)、伺服器已先送出 200 回應標頭維持連線時,回應標頭裡沒有扣費,請以回應內容的 usage.cost_usd(美元,與使用記錄一致)或 usage.cost(人民幣)對賬。未扣費的失敗不帶這些欄位。詳見扣費說明。

產生超過 40 秒:狀態碼仍是 200,請讀 error 欄位:

超過約 40 秒時,伺服器會先回傳 HTTP 200,並在回應內容開頭持續寫入空白以維持連線,完整 JSON 稍後才寫完。此後即使產生失敗,HTTP 狀態仍是 200,請以回應內容是否含 error 判斷成敗,讀取逾時設為不少於 300 秒。

串流(stream: true)

回應改為 Images SSE:等待期間送出以冒號開頭的 keepalive 註解行,最後一個 data: 事件才是完整的 Images JSON,並以 [DONE] 結束。這不是 OpenAI 原生的逐張預覽事件。

: hopbase-keepalive

data: {"created":1760000000,"data":[{"b64_json":"iVBORw0KGgoAAA..."}]}

data: [DONE]

非同步任務

提交後立即回傳 202 Accepted,回應標頭 Location 同樣指向查詢位址:

{
  "object": "image.task",
  "task_id": "你的task_id",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=你的task_id"
}

只能用 GET /v1/images/tasks?task_id=… 查詢,不支援把任務 ID 放進路徑。pending / processing / retrying 為進行中,終態是 completed 與 failed。

欄位型別說明
task_idstring任務 ID
statusstring任務狀態
result_contentstring完成後出現:Markdown,每張圖一行
errorstring僅 failed 時出現,英文原因,無錯誤碼
usage.costnumber本任務扣費的人民幣金額(與 usage.cost_usd 為同一筆扣費)
usage.cost_usdnumber本任務實際從餘額扣除的美元金額,與使用記錄相同
usage.currencystringusage.cost 的幣別,恆為 CNY
{
  "task_id": "你的task_id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "cost_usd": 0.2,
    "currency": "CNY"
  }
}

result_content 裡是相對路徑,加上 https://api.hop-base.com 即可下載。usage 在任務 completed 或 failed 後出現,只有建立任務的密鑰看得到。

範例

產生

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "一隻柴犬坐在櫻花樹下,日系水彩風格",
    "size": "1024x1024",
    "quality": "medium",
    "output_format": "png"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

curl 範例需要先安裝 jq。

SVG、GIF 動圖與標註編輯(2.6)

# SVG(n 必須為 1)
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "一架紙飛機的扁平線條圖示",
    "output_format": "svg",
    "complexity": "low"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > icon.svg

# GIF 動圖:size 是單幀尺寸
curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "一隻搖尾巴的柴犬,像素風",
    "size": "512x512",
    "output_format": "gif",
    "frame_count": 9,
    "frame_duration_ms": 200
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > shiba.gif
# 標註引導編輯:markup.png 是畫了標註的透明疊加層
curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密鑰" \
  -F "model=gpt-image-2.6-flare" \
  -F "prompt=依 markup 裡的標註修改" \
  -F "image=@plant.png" \
  -F "markup=@markup.png" \
  -F "output_format=png" \
  | jq -r '.data[0].b64_json' | base64 --decode > edited.png

編輯(多張參考圖 + 遮罩)

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密鑰" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=把遮罩區域換成一個花瓶,風格參考第二張圖" \
  -F "image[]=@scene.png" \
  -F "image[]=@style.png" \
  -F "mask=@mask.png" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "output_format=png"

JSON 寫法把檔案換成 URL:"image": ["https://example.com/scene.png", "https://example.com/style.png"],"mask": "https://example.com/mask.png"。

非同步

# 1. 提交後立即回傳 202 + task_id
curl -i https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "電影感的未來城市夜景",
    "size": "2048x2048"
  }'

# 2. 用上一步的 task_id 輪詢
curl "https://api.hop-base.com/v1/images/tasks?task_id=你的task_id" \
  -H "Authorization: Bearer sk-你的密鑰"

注意事項

  • 產生 2K / 4K 大圖時建議用非同步,避免長請求被 CDN 逾時中斷。
  • 同步請求的用戶端讀取逾時設為不少於 300 秒。
  • size 只收 auto 或 寬x高,寫檔位簡寫回傳 400。
  • xhigh / max 只有 2.5 與 2.6 的型號提供。
  • complexity、markup、SVG / GIF 輸出、frame_count、frame_duration_ms 只有 2.6 兩個型號提供。
  • GIF 輸出請用 size: "auto" 或 512x512 這類小尺寸,單幀尺寸太大會失敗。
  • background: "transparent" 需搭配 png 或 webp;gpt-image-2 的透明背景屬預覽功能。
  • 不支援官方串流欄位 partial_images(0–3),請省略。
  • 使用官方 SDK 時請保持 stream 為預設的 false。
  • 閘道會把 mask 縮放到第一張參考圖的尺寸,不保證遮罩外逐像素不變。
  • result_content 的位址不需密鑰即可開啟,請勿公開分享,並盡快下載到自己的儲存空間。

常見報錯

參數不合規在產生前回傳 400,不計費。內容安全攔截也回傳 400、不計費,error.code 為 safety_rejected。

報錯改法
size must be WIDTHxHEIGHT or auto 等 size 報錯按上方 size 規則修改
prompt must not be empty補上非空的 prompt
n must be 1 for this model in the current group拆成多次請求
/v1/images/edits requires at least one image參考圖放進 image,不要用 images
image download returned HTTP 404換成伺服器能取得的公開 URL
Your request was rejected by the safety system.改寫提示詞或更換參考圖
Request body exceeds the size limit (60 MB)(413)壓縮圖片,或改傳 URL
HTTP 200 但回應內容含 error保活開始後才失敗,按 error.message 處理

計費

按 token 計費,quality 越高輸出 token 越多:1024x1024 實測 low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 輸出 token。GPT Image 2.6 低檔輸出較多:low 約 820、medium 約 1,450,所以 2.6 的 low / medium 比 2.5 貴,high 以上相同。非同步任務的實際扣費看查詢結果的 usage.cost_usd(美元;usage.cost 為同一筆的人民幣金額),失敗通常為 0。同步請求的扣費直接看回應裡的 usage.cost_usd / usage.cost。

單價見上表各模型卡與登入後的模型廣場。

下一步