GPT Image
用 GPT Image 產生和編輯圖片:參數、回傳與注意事項。
| 項目 | 值 |
|---|---|
| Base URL | https://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。
可用型號
| 型號 | 模型 ID | quality 檔位 | 官方價 |
|---|---|---|---|
| GPT Image 2.6 Flare | gpt-image-2.6-flare | low / medium / high / xhigh / max | $5 / $30/ 百萬 tokens |
| GPT Image 2.6 Sunburst | gpt-image-2.6-sunburst | low / medium / high / xhigh / max | $5 / $30/ 百萬 tokens |
| GPT Image 2.5 Flare | gpt-image-2.5-flare | low / medium / high / xhigh / max | $5 / $30/ 百萬 tokens |
| GPT Image 2.5 Sunburst | gpt-image-2.5-sunburst | low / medium / high / xhigh / max | $5 / $30/ 百萬 tokens |
| GPT Image 2 | gpt-image-2 | low / 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–10 | 1 | 部分分組只支援 1 |
background | 選填 | auto / opaque / transparent | — | 透明需 png / webp |
output_format | 選填 | png / jpeg / webp;2.6 另有 svg / gif | png | 決定解碼後的格式 |
output_compression | 選填 | integer,0–100 | 100 | 僅 jpeg / webp |
moderation | 選填 | auto / low | — | 不會關閉內容安全檢查 |
user | 選填 | string | — | 終端使用者識別 |
stream | 選填 | boolean | false | true 改為 Images SSE |
response_format | 選填 | string | — | 請省略 |
input_fidelity | 選填 | low / high | — | 相容欄位,請省略 |
complexity | 選填 | low / medium / high | high | 僅 2.6;出圖前的規劃強度 |
frame_count | 選填 | integer,2–16 | 9 | 僅 2.6 的 gif;幀數 |
frame_duration_ms | 選填 | integer,20–2,000 | 200 | 僅 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,其餘欄位捨棄。
回傳結果
同步
| 欄位 | 型別 | 說明 |
|---|---|---|
created | integer | Unix 秒 |
data[].b64_json | string | Base64 圖片,解碼後按 output_format 儲存 |
usage.input_tokens | integer | 輸入 token(可能回傳) |
usage.output_tokens | integer | 輸出 token(可能回傳) |
usage.total_tokens | integer | 合計(可能回傳) |
usage.cost | number | 本次扣費的人民幣金額(與 usage.cost_usd 為同一筆扣費),最多 6 位小數。計費的同步成功回應都帶 |
usage.cost_usd | number | 本次實際從餘額扣除的美元金額,最多 8 位小數,與使用記錄裡這一條相同 |
usage.currency | string | usage.cost 的幣別,恆為 CNY |
error | object | 失敗時出現: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 秒時,伺服器會先回傳 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_id | string | 任務 ID |
status | string | 任務狀態 |
result_content | string | 完成後出現:Markdown,每張圖一行 |
error | string | 僅 failed 時出現,英文原因,無錯誤碼 |
usage.cost | number | 本任務扣費的人民幣金額(與 usage.cost_usd 為同一筆扣費) |
usage.cost_usd | number | 本任務實際從餘額扣除的美元金額,與使用記錄相同 |
usage.currency | string | usage.cost 的幣別,恆為 CNY |
{
"task_id": "你的task_id",
"status": "completed",
"result_content": "",
"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.pngcurl 範例需要先安裝 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的位址不需密鑰即可開啟,請勿公開分享,並盡快下載到自己的儲存空間。
- 標準取值依據 OpenAI Images 文件與官方編輯規範。
output_compression、moderation、user、response_format只在同步 JSON 產生與同步 multipart 編輯中透傳;JSON 編輯與非同步任務不保留這些欄位。n傳更大值時,只支援 1 的分組回傳 400;n≤ 0 按 1 處理。input_fidelity是相容欄位,GPT Image 2 預設以高保真處理參考圖。- 參考圖張數由官方校驗:閘道不數張數,超出後可能被拒絕或只使用部分圖片。
- 官方未明列所有參考圖合計的 MB 上限;JSON 裡單個 URL / Data URL 字串最長 20,971,520 字元。
- 4 MiB 是轉送前的壓縮目標,不是上傳拒絕門檻;Base64 編碼會使資料量增加約 1/3。
- Data URL 範例:
data:image/png;base64,iVBORw0KGgo…,須是完整編碼且 MIME 與圖片相符。 - 非同步任務提交時只檢查餘額是否大於 0,不做金額預留。
常見報錯
參數不合規在產生前回傳 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 處理 |
# size: 按上表尺寸規則修改
size must be WIDTHxHEIGHT or auto
size side length exceeds 3840px (4096x2048)
size width and height must be multiples of 16 (1000x1000)
size aspect ratio must not exceed 3:1 (3840x1024)
size total pixel count must be at least 655360 (512x512=262144)
size total pixel count must not exceed 8294400 (3840x3840=14745600)
# prompt 為空
prompt must not be empty
# edits JSON: 參考圖放在 "image",用字串或 {"url": ...}
# 不讀取 "images"
/v1/images/edits requires at least one image
image object is missing the url field
image must be a data URL or an http(s) URL
# 遠端參考圖:需為回傳 image/* 的公開 URL,單張 ≤ 25 MiB
image download returned HTTP 404
image is too large
image Content-Type is not image/*: text/html
reference image URL must not point to an internal address
image is too large, please compress it to under 4MB and retry
# 內容安全攔截 (error.code: safety_rejected)
Your request was rejected by the safety system.
# HTTP 413
Request body exceeds the size limit (60 MB)計費
按 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。
單價見上表各模型卡與登入後的模型廣場。
下一步
- 其他生圖系列與選型見圖片總覽
- 其他系列:Gemini 生圖、Seedream、Grok Imagine 生圖、可靈生圖、Midjourney
- 完整欄位見 API 參考:生成圖片、編輯圖片、查詢生圖任務
- 報錯時看報錯速查