編輯圖片

圖生圖 / 圖片編輯：GPT Image（支援 mask）、Seedream，以及「Gemini 全系（含生圖）」分組的 Gemini。

POST/v1/images/edits

基於參考圖生成或局部編輯。請求格式推薦 multipart/form-data（本地檔案，參考圖欄位 image / image[]，可重複），也接受 JSON（參考圖為 HTTP(S) URL 或 Data URL）；兩種寫法欄位同名。右側範例用 JSON，multipart 寫法見圖片生成指南。

JSON 編輯與非同步任務不保留 output_compression、moderation、user、response_format。「Gemini 官方直連」分組沒有本端點，請在生成圖片裡傳參考圖。

編輯圖片

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer $HOPBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "把參考圖改成梵谷星空風格的油畫",
    "image": "https://example.com/input.png",
    "size": "1536x1024",
    "quality": "medium"
  }'

200application/json

{
  "created": 1790222400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAA..."
    }
  ],
  "usage": {
    "input_tokens": 1310,
    "output_tokens": 1056,
    "total_tokens": 2366
  }
}

請求標頭

Authorization:必填string

Bearer sk-…：主控台「API 金鑰」中建立的金鑰，所屬分組須包含請求的模型

Prefer:選填string

respond-async：GPT Image / Gemini 立即回傳 202 Accepted、task_id 與 status_url，再用 GET /v1/images/tasks?task_id=… 輪詢。生成 2K / 4K 大圖時建議使用；Seedream 忽略此標頭、照常同步回傳

可選值respond-async

請求主體參數JSON

模型在圖片請求建構器中開啟模型文件

分組：GPT Image 全系。結果讀 data[].b64_json。參考圖最多 16 張。

model:必填"gpt-image-2"

先確認目前金鑰的 GET /v1/models 包含此 ID

prompt:必填string

生成或編輯指令；為空回傳 400 prompt must not be empty。網關不限長度，上限為官方上限

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度1–32000 字元

size:選填"auto" 或 string

例：1024x1024、2048x2048、3840x2160。不合規在生成前回傳 400、不計費；不接受 1K / 2K / 4K

限制auto 或寬x高：邊長為 16 的倍數、單邊 ≤ 3840、長短邊比 ≤ 3:1、總像素 655360–8294400

quality:選填string

檔位越高輸出 token 越多、費用越高：1024x1024 實測 low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 輸出 token

可選值autolowmediumhigh

限制網關不校驗、原樣轉發；檔位越高輸出 token 越多

n:選填integer

部分分組只支援 1，傳更大值回傳 400；≤ 0 按 1 處理

範圍1–10預設1

background:選填string

transparent 需配合 png 或 webp；2.0 透明背景屬預覽能力

可選值autoopaquetransparent

output_format:選填string

決定 b64_json 解碼後的格式

可選值pngjpegwebp

output_compression:選填integer

僅 jpeg / webp；只在同步 generations JSON 與 multipart 編輯中保留

範圍0–100預設100

moderation:選填string

不會關閉內容安全檢查

可選值autolow

user:選填string

終端使用者識別字串，不是 HopBase 帳戶 ID，也不改變計費歸屬

response_format:選填string

傳什麼都以 b64_json 回傳，不能靠 url 取得下載連結，請省略

限制傳什麼都以 b64_json 回傳，請省略

stream:選填boolean

true 改為 HopBase Images SSE（期間傳送 keepalive，最後一個 data: 事件才是 Images JSON，以 [DONE] 結束），不是 OpenAI 原生逐張預覽事件；SDK 請保持 false

限制true 回傳 HopBase Images SSE，SDK 請保持 false預設false

input_fidelity:選填string

相容欄位；GPT Image 2 預設高保真處理參考圖，請省略

可選值lowhigh

image:必填string 或 array of string

multipart 檔案（image / image[]），或 JSON 的 HTTP(S) URL / Data URL 字串、字串陣列。不讀 images，不接受裸 base64 或 file_id；轉發前可能壓縮

限制1–16 張（官方上限）；遠端 URL 單張 ≤ 26214400 位元組且須回傳 image/*。只讀 image，不讀 images

mask:選填string

透明區域表示要編輯；網關會把 mask 縮放到第一張參考圖的尺寸；不保證遮罩外逐像素不變

限制帶 alpha 通道的 PNG；透明區域表示要編輯

transparent 需要 png 或 webp
output_compression 只對 jpeg / webp 生效

model:必填"gpt-image-2.5-flare"

先確認目前金鑰的 GET /v1/models 包含此 ID

prompt:必填string

生成或編輯指令；為空回傳 400 prompt must not be empty。網關不限長度，上限為官方上限

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度1–32000 字元

size:選填"auto" 或 string

例：1024x1024、2048x2048、3840x2160。不合規在生成前回傳 400、不計費；不接受 1K / 2K / 4K

限制auto 或寬x高：邊長為 16 的倍數、單邊 ≤ 3840、長短邊比 ≤ 3:1、總像素 655360–8294400

quality:選填string

檔位越高輸出 token 越多、費用越高：1024x1024 實測 low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 輸出 token

可選值autolowmediumhighxhighmax

限制網關不校驗、原樣轉發；檔位越高輸出 token 越多

n:選填integer

部分分組只支援 1，傳更大值回傳 400；≤ 0 按 1 處理

範圍1–10預設1

background:選填string

transparent 需配合 png 或 webp；2.0 透明背景屬預覽能力

可選值autoopaquetransparent

output_format:選填string

決定 b64_json 解碼後的格式

可選值pngjpegwebp

output_compression:選填integer

僅 jpeg / webp；只在同步 generations JSON 與 multipart 編輯中保留

範圍0–100預設100

moderation:選填string

不會關閉內容安全檢查

可選值autolow

user:選填string

終端使用者識別字串，不是 HopBase 帳戶 ID，也不改變計費歸屬

response_format:選填string

傳什麼都以 b64_json 回傳，不能靠 url 取得下載連結，請省略

限制傳什麼都以 b64_json 回傳，請省略

stream:選填boolean

true 改為 HopBase Images SSE（期間傳送 keepalive，最後一個 data: 事件才是 Images JSON，以 [DONE] 結束），不是 OpenAI 原生逐張預覽事件；SDK 請保持 false

限制true 回傳 HopBase Images SSE，SDK 請保持 false預設false

input_fidelity:選填string

相容欄位；GPT Image 2 預設高保真處理參考圖，請省略

可選值lowhigh

image:必填string 或 array of string

multipart 檔案（image / image[]），或 JSON 的 HTTP(S) URL / Data URL 字串、字串陣列。不讀 images，不接受裸 base64 或 file_id；轉發前可能壓縮

限制1–16 張（官方上限）；遠端 URL 單張 ≤ 26214400 位元組且須回傳 image/*。只讀 image，不讀 images

mask:選填string

透明區域表示要編輯；網關會把 mask 縮放到第一張參考圖的尺寸；不保證遮罩外逐像素不變

限制帶 alpha 通道的 PNG；透明區域表示要編輯

transparent 需要 png 或 webp
output_compression 只對 jpeg / webp 生效

model:必填"gpt-image-2.5-sunburst"

先確認目前金鑰的 GET /v1/models 包含此 ID

prompt:必填string

生成或編輯指令；為空回傳 400 prompt must not be empty。網關不限長度，上限為官方上限

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度1–32000 字元

size:選填"auto" 或 string

例：1024x1024、2048x2048、3840x2160。不合規在生成前回傳 400、不計費；不接受 1K / 2K / 4K

限制auto 或寬x高：邊長為 16 的倍數、單邊 ≤ 3840、長短邊比 ≤ 3:1、總像素 655360–8294400

quality:選填string

檔位越高輸出 token 越多、費用越高：1024x1024 實測 low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 輸出 token

可選值autolowmediumhighxhighmax

限制網關不校驗、原樣轉發；檔位越高輸出 token 越多

n:選填integer

部分分組只支援 1，傳更大值回傳 400；≤ 0 按 1 處理

範圍1–10預設1

background:選填string

transparent 需配合 png 或 webp；2.0 透明背景屬預覽能力

可選值autoopaquetransparent

output_format:選填string

決定 b64_json 解碼後的格式

可選值pngjpegwebp

output_compression:選填integer

僅 jpeg / webp；只在同步 generations JSON 與 multipart 編輯中保留

範圍0–100預設100

moderation:選填string

不會關閉內容安全檢查

可選值autolow

user:選填string

終端使用者識別字串，不是 HopBase 帳戶 ID，也不改變計費歸屬

response_format:選填string

傳什麼都以 b64_json 回傳，不能靠 url 取得下載連結，請省略

限制傳什麼都以 b64_json 回傳，請省略

stream:選填boolean

true 改為 HopBase Images SSE（期間傳送 keepalive，最後一個 data: 事件才是 Images JSON，以 [DONE] 結束），不是 OpenAI 原生逐張預覽事件；SDK 請保持 false

限制true 回傳 HopBase Images SSE，SDK 請保持 false預設false

input_fidelity:選填string

相容欄位；GPT Image 2 預設高保真處理參考圖，請省略

可選值lowhigh

image:必填string 或 array of string

multipart 檔案（image / image[]），或 JSON 的 HTTP(S) URL / Data URL 字串、字串陣列。不讀 images，不接受裸 base64 或 file_id；轉發前可能壓縮

限制1–16 張（官方上限）；遠端 URL 單張 ≤ 26214400 位元組且須回傳 image/*。只讀 image，不讀 images

mask:選填string

透明區域表示要編輯；網關會把 mask 縮放到第一張參考圖的尺寸；不保證遮罩外逐像素不變

限制帶 alpha 通道的 PNG；透明區域表示要編輯

transparent 需要 png 或 webp
output_compression 只對 jpeg / webp 生效

model:必填"gemini-3.1-flash-image"

以目前金鑰 GET /v1/models 的回傳為準

prompt:必填string

模型拒答或只回文字時回傳 400（訊息引用該段文字）或 502：請改寫提示詞

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度≥ 1 字元

n:選填integer

並行生成。全有或全無：任一張失敗則整個請求失敗、不計費

限制按輸出檔位封頂：1K ≤ 10，2K ≤ 5範圍1–10預設1

image_size:選填string

頂層扁平寫法，等價於 google.image_config.image_size；覆蓋 size 推導的檔位

可選值1K2K

預設"1K"

aspect_ratio:選填string

頂層扁平寫法，等價於 google.image_config.aspect_ratio，優先於 size

可選值1:12:33:23:44:34:55:49:1616:921:9

預設"1:1"

size:選填"auto" 或 string

寬x高 從不因比例被拒：映射到最接近的官方比例，檔位按長邊推導並靜默降到型號最高檔位。明確寫出超過型號檔位的 1K / 2K / 4K 回傳 400；同時傳 image_size 時以它為準

可選值1K2K

限制auto、任意比例的寬x高（映射到最接近的官方比例，檔位按長邊推導並靜默降到型號最高檔位），或型號檔位

google:選填object

SDK 可寫成 extra_body.google.image_config；三種寫法等價

image:選填string 或 array of string

參考圖，放在 generations 請求體即可；同時傳時以 images 為準。「Gemini 官方直連」單張解碼後 ≤ 20 MiB，沒有 /v1/images/edits

限制參考圖：字串或字串陣列，最多 14 張

images:選填string 或 array of string

同 image，同時傳時以 images 為準

限制參考圖：字串或字串陣列，最多 14 張

mask:不支援

不支援：傳 mask 回傳 400；局部修改請在 prompt 中描述區域

background:選填any

不支援 transparent（回傳 400）

不能為"transparent"

stream:選填any

不支援，請省略或傳 false

不能為true

2K 輸出每次最多 5 張（回應體積上限）

model:必填"gemini-3.1-flash-image-preview"

以目前金鑰 GET /v1/models 的回傳為準

prompt:必填string

模型拒答或只回文字時回傳 400（訊息引用該段文字）或 502：請改寫提示詞

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度≥ 1 字元

n:選填integer

並行生成。全有或全無：任一張失敗則整個請求失敗、不計費

限制按輸出檔位封頂：1K ≤ 10，2K ≤ 5範圍1–10預設1

image_size:選填string

頂層扁平寫法，等價於 google.image_config.image_size；覆蓋 size 推導的檔位

可選值1K2K

預設"1K"

aspect_ratio:選填string

頂層扁平寫法，等價於 google.image_config.aspect_ratio，優先於 size

可選值1:12:33:23:44:34:55:49:1616:921:9

預設"1:1"

size:選填"auto" 或 string

可選值1K2K

限制auto、任意比例的寬x高（映射到最接近的官方比例，檔位按長邊推導並靜默降到型號最高檔位），或型號檔位

google:選填object

SDK 可寫成 extra_body.google.image_config；三種寫法等價

image:選填string 或 array of string

參考圖，放在 generations 請求體即可；同時傳時以 images 為準。「Gemini 官方直連」單張解碼後 ≤ 20 MiB，沒有 /v1/images/edits

限制參考圖：字串或字串陣列，最多 14 張

images:選填string 或 array of string

同 image，同時傳時以 images 為準

限制參考圖：字串或字串陣列，最多 14 張

mask:不支援

不支援：傳 mask 回傳 400；局部修改請在 prompt 中描述區域

background:選填any

不支援 transparent（回傳 400）

不能為"transparent"

stream:選填any

不支援，請省略或傳 false

不能為true

2K 輸出每次最多 5 張（回應體積上限）

model:必填"gemini-3-pro-image"

以目前金鑰 GET /v1/models 的回傳為準

prompt:必填string

模型拒答或只回文字時回傳 400（訊息引用該段文字）或 502：請改寫提示詞

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度≥ 1 字元

n:選填integer

並行生成。全有或全無：任一張失敗則整個請求失敗、不計費

限制按輸出檔位封頂：1K ≤ 10，2K ≤ 5，4K ≤ 2範圍1–10預設1

image_size:選填string

頂層扁平寫法，等價於 google.image_config.image_size；覆蓋 size 推導的檔位

可選值1K2K4K

預設"1K"

aspect_ratio:選填string

頂層扁平寫法，等價於 google.image_config.aspect_ratio，優先於 size

可選值1:12:33:23:44:34:55:49:1616:921:9

預設"1:1"

size:選填"auto" 或 string

可選值1K2K4K

限制auto、任意比例的寬x高（映射到最接近的官方比例，檔位按長邊推導並靜默降到型號最高檔位），或型號檔位

google:選填object

SDK 可寫成 extra_body.google.image_config；三種寫法等價

image:選填string 或 array of string

參考圖，放在 generations 請求體即可；同時傳時以 images 為準。「Gemini 官方直連」單張解碼後 ≤ 20 MiB，沒有 /v1/images/edits

限制參考圖：字串或字串陣列，最多 14 張

images:選填string 或 array of string

同 image，同時傳時以 images 為準

限制參考圖：字串或字串陣列，最多 14 張

mask:不支援

不支援：傳 mask 回傳 400；局部修改請在 prompt 中描述區域

background:選填any

不支援 transparent（回傳 400）

不能為"transparent"

stream:選填any

不支援，請省略或傳 false

不能為true

2K 輸出每次最多 5 張（回應體積上限）
4K 輸出每次最多 2 張（回應體積上限）

model:必填"gemini-3.1-flash-lite-image"

以目前金鑰 GET /v1/models 的回傳為準

prompt:必填string

模型拒答或只回文字時回傳 400（訊息引用該段文字）或 502：請改寫提示詞

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度≥ 1 字元

n:選填integer

並行生成。全有或全無：任一張失敗則整個請求失敗、不計費

限制按輸出檔位封頂：1K ≤ 10範圍1–10預設1

image_size:選填string

頂層扁平寫法，等價於 google.image_config.image_size；覆蓋 size 推導的檔位

可選值1K

預設"1K"

aspect_ratio:選填string

頂層扁平寫法，等價於 google.image_config.aspect_ratio，優先於 size

可選值1:12:33:23:44:34:55:49:1616:921:9

預設"1:1"

size:選填"auto" 或 string

可選值1K

限制auto、任意比例的寬x高（映射到最接近的官方比例，檔位按長邊推導並靜默降到型號最高檔位），或型號檔位

google:選填object

SDK 可寫成 extra_body.google.image_config；三種寫法等價

image:選填string 或 array of string

參考圖，放在 generations 請求體即可；同時傳時以 images 為準。「Gemini 官方直連」單張解碼後 ≤ 20 MiB，沒有 /v1/images/edits

限制參考圖：字串或字串陣列，最多 14 張

images:選填string 或 array of string

同 image，同時傳時以 images 為準

限制參考圖：字串或字串陣列，最多 14 張

mask:不支援

不支援：傳 mask 回傳 400；局部修改請在 prompt 中描述區域

background:選填any

不支援 transparent（回傳 400）

不能為"transparent"

stream:選填any

不支援，請省略或傳 false

不能為true

model:必填"gemini-2.5-flash-image"

以目前金鑰 GET /v1/models 的回傳為準

prompt:必填string

模型拒答或只回文字時回傳 400（訊息引用該段文字）或 502：請改寫提示詞

限制去除首尾空白後不能為空，否則 400「prompt must not be empty」長度≥ 1 字元

n:選填integer

並行生成。全有或全無：任一張失敗則整個請求失敗、不計費

限制按輸出檔位封頂：1K ≤ 10範圍1–10預設1

image_size:選填string

頂層扁平寫法，等價於 google.image_config.image_size；覆蓋 size 推導的檔位

可選值1K

預設"1K"

aspect_ratio:選填string

頂層扁平寫法，等價於 google.image_config.aspect_ratio，優先於 size

可選值1:12:33:23:44:34:55:49:1616:921:9

預設"1:1"

size:選填"auto" 或 string

可選值1K

限制auto、任意比例的寬x高（映射到最接近的官方比例，檔位按長邊推導並靜默降到型號最高檔位），或型號檔位

google:選填object

SDK 可寫成 extra_body.google.image_config；三種寫法等價

image:選填string 或 array of string

參考圖，放在 generations 請求體即可；同時傳時以 images 為準。「Gemini 官方直連」單張解碼後 ≤ 20 MiB，沒有 /v1/images/edits

限制參考圖：字串或字串陣列，最多 3 張

images:選填string 或 array of string

同 image，同時傳時以 images 為準

限制參考圖：字串或字串陣列，最多 3 張

mask:不支援

不支援：傳 mask 回傳 400；局部修改請在 prompt 中描述區域

background:選填any

不支援 transparent（回傳 400）

不能為"transparent"

stream:選填any

不支援，請省略或傳 false

不能為true

回傳

200同步成功

202帶 Prefer: respond-async 時

created:選填integer

Unix 秒

data:必填array of object

每張圖一項

usage:選填object

可能回傳

錯誤

400參數不合規（生成前拒絕，不計費）

401沒帶金鑰、金鑰無效或已過期（missing_api_key / invalid_api_key / api_key_expired）

402餘額或金鑰 / 成員 / 部門額度用完（insufficient_quota）

404模型不在這把金鑰的分組裡（model_not_found），或路徑不屬於該分組（route_not_found）

413請求體超過 60 MB（request_too_large）

429帳戶或金鑰並行已達上限（user_concurrency_limit / apikey_concurrency_limit），帶 Retry-After

請求標頭

請求主體參數JSON

回傳

錯誤

相關頁面