圖片生成 API

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

端點一覽

方法	路徑	用途	請求格式
POST	`/v1/images/generations`	文生圖	`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))

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。

HopBase 的 Azure Gemini 圖片分組標準倍率為 3.1，按 ¥6.8/$ 折算約為官方基準 token 價的 45.6%；圖片按實際 token 用量計費，最終以登錄後模型廣場為準。

Seedream 5.0 Pro · 文生圖

BytePlus Seedream 5.0 Pro 的文生圖走 /v1/images/generations，按輸出張數計費、返回 24 小時有效的簽名直鏈：

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[]=@./subject.png" \
  -F "image[]=@./style.png" \
  -F "size=2K" \
  -F "output_format=png"

Seedream 5.0 Pro 參數與計價

字段	說明
`model`	`seedream-5-0-pro`
`prompt`	圖片內容、構圖、風格或編輯指令；局部編輯可描述座標、bbox、箭頭或參考圖中的塗畫區域
`image`	可選；單個 URL / Data URL 或數組，最多 10 張。傳入後觸發單圖 / 多圖圖生圖或圖片編輯
`size`	`1K` / `2K`，或總像素 921,600–4,624,220 且寬高比 1:16–16:1 的 `寬x高`；不支持 `4K`
`output_format`	`png` / `jpeg`
`optimize_prompt_options.mode`	可選；`standard` / `fast`
`response_format`	HopBase 目前使用 `url`，返回圖片直鏈
官方基準價	只按輸出圖片計費：單張 ≤ 2.36MP（約 1K）$0.045 / 張；> 2.36MP（2K / 高像素自定義尺寸）$0.09 / 張；參考圖不重複計費
HopBase 標準展示價	目前 68 折：單張 ≤ 2.36MP 為 $0.0306 / 張；> 2.36MP 為 $0.0612 / 張（USD 等值）

目前標準分組倍率為 4.624，模型廣場按 ¥6.8/$ 折算成上面的 68 折 USD 等值；用戶專屬倍率與實際扣費以登錄後模型廣場為準。Seedream 支持同步文生圖、單圖 / 多圖圖生圖與編輯，n=1、response_format=url；不支持圖片異步任務、流式或 base64 響應。輸入單張最多 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-5-0-pro 的 Seedream / Seedance 分組密鑰；不要假設 OpenAI、Gemini 或 Claude 密鑰可跨分組調用。

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

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

常用請求字段

字段	是否必填	說明
`model`	是	`gpt-image-2` 或當前密鑰 `GET /v1/models` 返回的 Gemini Banana 圖片模型 / `seedream-5-0-pro`
`prompt`	是	圖片內容、構圖、風格與文字要求
`size`	否	`auto` 或 `WIDTHxHEIGHT`；常用 1024×1024、1536×1024、1024×1536、2048×2048
`quality`	否	`low` / `medium` / `high` / `auto`
`n`	否	生成張數；部分模型目前只支持 1
`background`	否	`opaque` / `transparent`
`output_format`	否	`png` / `jpeg` / `webp`
`image` / `mask`	僅編輯必填 / 視模型而定	`/images/edits` 僅限支持編輯的模型，可傳單張或多張參考圖。Gemini 不接受 `mask`；Seedream 最多 10 張、單張最多 30 MB，也不接受傳統 `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 Images 網關）

加入 HTTP header Prefer: respond-async 後，支持異步任務的模型會立即返回 202 Accepted、task_id 與 status_url，再由客戶端輪詢。任務狀態為 pending / processing / completed / failed。完成後 result_content 會包含已存儲圖片的 Markdown URL。部分 Gemini 模型目前仍同步返回，請以實際 HTTP 狀態碼判斷。

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

本頁目錄