圖片生成 API

HopBase 對客戶端統一提供 OpenAI Images 兼容協議。文生圖發到 POST https://api.hop-base.com/v1/images/generations；即使模型是 Gemini Banana，也不要傳 Gemini native generateContent payload，HopBase 會根據所選模型自動完成協議適配。

端點一覽

方法	路徑	用途	請求格式
POST	`/v1/images/generations`	文生圖；Seedream 也用 `image` 做圖生圖 / 編輯	`application/json`
POST	`/v1/images/edits`	圖生圖 / 圖片編輯	`multipart/form-data`（推薦）或 JSON（URL / Data URL）
GET	`/v1/images/tasks?task_id=…`	查詢異步任務	加 `Prefer: respond-async` 時使用

所有端點都使用 Authorization: Bearer sk-你的密鑰。Base URL 是 https://api.hop-base.com/v1。

文生圖 · 最短可用 curl

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一隻柴犬坐在櫻花樹下，日系水彩風格",
    "size": "2048x2048",
    "quality": "medium",
    "background": "opaque",
    "output_format": "png",
    "n": 1
  }'

文生圖 · OpenAI Python SDK

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hop-base.com/v1",
    api_key="sk-你的密鑰",
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="一隻柴犬坐在櫻花樹下，日系水彩風格",
    size="2048x2048",
    quality="medium",
    background="opaque",
    output_format="png",
    n=1,
)

image = resp.data[0]
with open("result.png", "wb") as f:
    f.write(base64.b64decode(image.b64_json))

GPT Image 模型 ID

型號	模型 ID	定位
GPT Image 2	`gpt-image-2`	上一代；支持 `auto`、1K、2K、4K
GPT Image 2.5 Flare	`gpt-image-2.5-flare`	日常出圖首選
GPT Image 2.5 Sunburst	`gpt-image-2.5-sunburst`	畫質更強，同參數下比 Flare 略慢

兩個 GPT Image 2.5 型號在 /v1/images/generations 與 /v1/images/edits 上使用同一套 OpenAI Images 協議，現有客戶端只需把 model 換成新名字。價格見價格頁與登錄後模型廣場。

GPT Image 2.5 參數

字段	GPT Image 2.5 行為
`size`	`1024x1024`、`1536x1024`、`1024x1536`、`auto`，或任意 `寬x高`：寬高須為 16 的倍數，最長邊不超過 3840，寬高比在 1:3–3:1 之間（如 `1536x864`、`2048x1152`）。不合規會明確返回 400。
`quality`	`low` / `medium` / `high` / `xhigh` / `max` / `auto`。檔位越高輸出 token 越多、費用越高：1024x1024 實測 low 約 200、high 約 1,760、xhigh 約 3,120、max 約 7,020 輸出 token。
`n`	單次可生成多張
`background`	`transparent` 需配合 `png` 或 `webp` 輸出
`output_format` / `output_compression`	`png` / `jpeg` / `webp`，可指定壓縮率
`moderation`	接受 `low`
`response_format`	傳 `url` 會被接受，但圖片仍以 `b64_json` 返回
圖片編輯	支持單張參考圖、多張參考圖（重複傳 `image[]`）以及帶 alpha 通道的 `mask` 局部重繪：mask 透明區域重繪、不透明區域逐像素保留

參考耗時（單張 1024x1024）：low 檔兩個型號約 14 秒；high 檔 Flare 約 19 秒、Sunburst 約 37 秒。

GPT Image 2.5 · 自定義尺寸文生圖

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "石板上的陶瓷茶壺產品圖，柔和的窗邊光",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "webp",
    "output_compression": 85
  }'

Gemini Banana 特殊兼容

能力	Gemini 兼容行為
請求入口	客戶端統一調用 `/v1/images/generations`，HopBase 會根據所選模型自動完成請求適配。
響應	圖片結果會統一為 OpenAI Images JSON，通常位於 `data[].b64_json`，也可能返回 `data[].url`。
圖生圖	支持圖片編輯的 Gemini 模型可調用 `/v1/images/edits`，傳入單張或多張參考圖與自然語言指令；Gemini 不提供 `mask` 區域硬限制。
尺寸	`size` 會依所選模型預先校驗，並在需要時自動適配尺寸要求。
其他參數	`quality`、`background`、`output_format`、`input_fidelity`、`n` 是否生效取決於具體模型能力，不能假設與 GPT Image 完全等價。
流式	Gemini 圖片請使用默認同步模式，不要傳 `"stream": true`；不支持流式輸出的模型會明確返回錯誤。
異步	部分模型可使用 `Prefer: respond-async`；客戶端應以實際 HTTP 狀態碼判斷是否返回 `202 task_id`。

Gemini 所需的適配由 HopBase 在服務端自動完成；客戶端的 Base URL、Bearer 密鑰和 OpenAI Images 請求結構都不需要改。

Gemini Banana 圖片模型 ID

系列	模型 ID	尺寸
Banana	`gemini-2.5-flash-image`	1K
Banana Pro	`gemini-3-pro-image` / `gemini-3-pro-image-c` `gemini-3-pro-image-preview` / `gemini-3-pro-image-preview-c`	1K / 2K / 4K
Banana 2	`gemini-3.1-flash-image` / `gemini-3.1-flash-image-c` `gemini-3.1-flash-image-preview` / `gemini-3.1-flash-image-preview-c`	1K / 2K
Banana 2 Lite	`gemini-3.1-flash-lite-image`	1K

-c 後綴在生產目錄中是獨立模型 ID，客戶端調用協議與同系列 ID 相同。不要自行添加或移除後綴；接入前用當前密鑰調 GET /v1/models，只使用實際回傳的完整 ID。

Gemini 圖片模型按實際 token 用量計費；不同套餐分組的折算倍率可能不同，最終以登錄後模型廣場為準。

Seedream 可用型號

型號	模型 ID	尺寸	輸出 / 優化模式
Seedream 5.0 Pro	`seedream-5-0-pro`	1K / 1.5K / 2K	PNG / JPEG；standard / fast
Seedream 5.0 Lite（輕量版）	`seedream-5-0-lite`	2K / 3K / 4K	PNG / JPEG；standard
Seedream 4.5	`seedream-4-5`	2K / 4K	JPEG；standard

Lite 是 Seedream 5.0 的輕量版，公開模型名為 Seedream 5.0 Lite；請勿把 seedream-5-0-lite 當作 Pro 使用。上表為官方基準價；實際售價按分組倍率折算，以登錄後模型廣場為準。💡 Pro 的 1.5K 與 1K 同價、生成效果更優，需要中小尺寸時建議優先 1.5K。⚠️ Lite 與 4.5 最小輸出 2K（總像素 ≥ 3,686,400），需要 1K 小圖請使用 Pro。

Seedream 5.0 Pro · 文生圖

Seedream 文生圖走 /v1/images/generations，按輸出張數計費、返回 24 小時有效的簽名直鏈。下面以 Pro 為例；也可換成當前密鑰返回的 Lite 或 4.5 完整 ID，並遵循對應型號參數：

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "霓虹夜色下的未來城市街景，電影感構圖",
    "size": "2048x2048",
    "response_format": "url"
  }'

Seedream 5.0 Pro · 圖生圖 / 圖片編輯（推薦 JSON）

仍調用 /v1/images/generations，增加 image 即可；可傳 1–10 個 HTTP(S) URL 或圖片 Data URL。單圖、多圖融合、參考圖重繪及帶座標 / bbox / 箭頭 / 塗畫標註的局部編輯都使用這個入口：

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的密鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5-0-pro",
    "prompt": "把第一張圖中的杯子移到桌面右側，保持其餘內容不變",
    "image": ["https://example.com/source.png"],
    "size": "2K",
    "output_format": "png",
    "response_format": "url"
  }'

Seedream 5.0 Pro · OpenAI edits 兼容入口（本機文件）

已有 OpenAI Images 編輯代碼時，可直接使用 /v1/images/edits 的 multipart 格式；HopBase 會自動完成文件與請求格式適配：

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密鑰" \
  -F "model=seedream-5-0-pro" \
  -F "prompt=根據兩張參考圖重新設計海報，保留主體與品牌配色" \
  -F "image[][email protected]" \
  -F "image[][email protected]" \
  -F "size=2K" \
  -F "output_format=png"

Seedream 共通參數

字段	說明
`model`	使用當前密鑰 `GET /v1/models` 返回的 Seedream 完整 ID
`prompt`	圖片內容、構圖、風格或編輯指令；局部編輯可描述座標、bbox、箭頭或參考圖中的塗畫區域
`image`	可選；單個 URL / Data URL 或數組。上限：Pro 10 張，Lite / 4.5 為 14 張。傳入後觸發單圖 / 多圖圖生圖或圖片編輯
`size`	按上表選擇簡寫尺寸；自定義 `寬x高` 寬高比 1:16–16:1。總像素範圍：Pro 為 921,600–4,624,220；Lite / 4.5 為 3,686,400–16,777,216（低於下限會被網關直接拒絕並提示合法區間）
`output_format`	Pro / Lite：`png` 或 `jpeg`；4.5：僅 `jpeg`
`optimize_prompt_options.mode`	Pro：`standard` / `fast`；Lite / 4.5：僅 `standard`
`response_format`	HopBase 目前使用 `url`，返回圖片直鏈

實際倍率與扣費以登錄後模型廣場為準。Seedream 支持同步文生圖、單圖 / 多圖圖生圖與編輯，n=1、response_format=url；不支持圖片異步任務或流式。輸入單張最多 30 MB / 36MP，可用 JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、HEIF。⚠️ 返回的 URL 是 24 小時有效的簽名直鏈，請及時下載留存。

Seedream 的局部編輯不是傳統 mask 硬遮罩：請把標註直接畫在參考圖上，並在 prompt 中描述座標 / bbox / 箭頭 / 塗畫區域。/v1/images/edits 若傳 mask 會明確返回 400，避免產生錯誤語義。

✅ 請使用能在 GET /v1/models 返回目標 Seedream 完整 ID 的分組密鑰；不要假設其他分組密鑰可以調用這些模型。

通用圖生圖 / 圖片編輯 · multipart curl

curl https://api.hop-base.com/v1/images/edits \
  -H "Authorization: Bearer sk-你的密鑰" \
  -F "model=gpt-image-2" \
  -F "prompt=把參考圖改成梵高星空風格的油畫" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

GPT Image 2.5 · 多參考圖 + mask 局部重繪

mask 為帶 alpha 通道的 PNG：透明像素按 prompt 重繪，不透明像素原樣保留。多張參考圖重複傳 image[] 即可。

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"

常用請求字段

字段	是否必填	說明
`model`	是	`gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst`，或當前密鑰 `GET /v1/models` 返回的 Gemini Banana / Seedream 圖片模型完整 ID
`prompt`	是	圖片內容、構圖、風格與文字要求
`size`	否	`auto` 或 `WIDTHxHEIGHT`；常用 1024×1024、1536×1024、1024×1536、2048×2048；GPT Image 2.5 另支持上文規則內的自定義尺寸
`quality`	否	`low` / `medium` / `high` / `auto`；GPT Image 2.5 另接受 `xhigh` / `max`
`n`	否	生成張數；部分模型目前只支持 1
`background`	否	`opaque` / `transparent`
`output_format`	否	`png` / `jpeg` / `webp`
`image` / `mask`	僅編輯必填 / 視模型而定	`/images/edits` 僅限支持編輯的模型，可傳單張或多張參考圖。Gemini 不接受 `mask`；Seedream 參考圖上限 Pro 10 張、Lite / 4.5 為 14 張，單張最多 30 MB，也不接受傳統 `mask`。GPT Image 2.5 支持重複傳 `image[]` 多參考圖與帶 alpha 通道的 `mask`。

圖片尺寸會按模型先做校驗；模型不支持的 2K / 4K 尺寸會直接返回 400，不會產生圖片生成費用。

同步響應（默認）

不傳 Prefer 時會等待圖片完成，返回標準 OpenAI Images JSON。圖片通常位於 data[].b64_json，部分模型可能返回 data[].url；usage 提供 token 用量。

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

⚠️ 支持流式輸出的非 Gemini 圖片模型傳 "stream": true 時會改為 SSE，期間發送 keepalive ping，最後一個 data: 事件才是 Images JSON，並以 [DONE] 結束。Gemini 圖片不支持這套 Images SSE 語義；使用官方 SDK 時建議一律保持默認同步模式。

異步任務模式（OpenAI / Gemini Images 網關）

加入 HTTP header Prefer: respond-async 後，支持異步任務的模型會立即返回 202 Accepted、task_id 與 status_url，再由客戶端輪詢。任務狀態為 pending / processing / completed / failed。完成後 result_content 會包含已存儲圖片的 Markdown URL。Gemini 圖片模型亦已支援異步任務；生成 2K / 4K 大圖時建議優先使用，可避免長時間請求被 CDN 超時中斷。

# 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-你的密鑰"

本頁目錄