GPT Image

預設同步回傳 Base64 圖片，加上 Prefer: respond-async 可改為非同步任務；對話分組的金鑰呼叫 gpt-image-* 會回傳 404。

可用型號

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

請求參數

產生

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

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，也不改變計費歸屬。

編輯

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

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

遠端 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 和編輯用的圖片 / mask，其餘欄位捨棄。

回傳結果

同步

{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1760,
    "total_tokens": 1802
  }
}

串流（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": "你的task_id",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "currency": "CNY",
    "cost_cny": 1.36,
    "cost_usd": 0.2
  }
}

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。

編輯（多張參考圖 + 遮罩）

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的金鑰" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=把遮罩區域換成一個花瓶，風格參考第二張圖" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "[email protected]" \
  -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 兩個型號提供。
• background: "transparent" 需搭配 png 或 webp；gpt-image-2 的透明背景屬預覽功能。
• 不支援官方串流欄位 partial_images（0–3），請省略。
• 使用官方 SDK 時請保持 stream 為預設的 false。
• 閘道會把 mask 縮放到第一張參考圖的尺寸，不保證遮罩外逐像素不變。
• result_content 的位址不需金鑰即可開啟，請勿公開分享，並盡快下載到自己的儲存空間。

常見報錯

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

# 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。非同步任務的實際扣費看查詢結果的 usage.cost（cost_cny / cost_usd 按固定 1 USD = 6.8 CNY 換算），失敗通常為 0。

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

下一步

• 其他生圖系列與選型見圖片總覽
• 其他系列：Gemini 生圖、Seedream、Grok Imagine 生圖、可靈生圖、Midjourney
• 完整欄位見 API 參考：生成圖片、編輯圖片、查詢生圖任務
• 報錯時看報錯速查