跳到正文
HopBase 文檔
登入控制台

Gemini 生圖

用 Gemini 生成和編輯圖片：參數、返回與注意事項。

項目值
Base URLhttps://api.hop-base.com/v1
生成（含參考圖編輯）POST /v1/images/generations
編輯（僅「Gemini 全系（含生圖）」）POST /v1/images/edits
查詢非同步任務GET /v1/images/tasks?task_id=…
金鑰分組「Gemini 全系（含生圖）」或「Gemini 官方直連」

Gemini 生圖（暱稱 Banana）使用 OpenAI Images 介面，同步返回 Base64 圖片，兩個分組的編輯入口與計費方式不同。

可用型號

型號模型 ID尺寸檔位官方價
Gemini 3 Pro Image（Banana Pro）gemini-3-pro-image1K / 2K / 4K$0.1344起/ 張
Gemini 3.1 Flash Image（Banana 2）gemini-3.1-flash-image1K / 2K$0.0672/ 張
Banana 2 預覽版gemini-3.1-flash-image-preview1K / 2K$0.0672/ 張
Gemini 3.1 Flash Lite Image（Banana 2 Lite）gemini-3.1-flash-lite-image1K$0.0336/ 張
Gemini 2.5 Flash Image（Banana）gemini-2.5-flash-image1K$0.0387/ 張

選型建議：要 4K 只能用 gemini-3-pro-image；gemini-3.1-flash-image 的 1K 與 2K 同價；多參考圖合成不要用 Lite，它未針對多參考圖最佳化。

兩個分組的差異：

分組/v1/images/edits計費
Gemini 全系（含生圖）支援按交付張數
Gemini 官方直連返回 404，參考圖放在 generations按 token

「Gemini 官方直連」還能在 /v1/chat/completions 裡調用圖片模型，圖片以 markdown 內嵌 data URL 返回。

請求參數

生成

POST /v1/images/generations，JSON 請求體。請求體用 OpenAI Images 結構，不要傳 Gemini 原生 generateContent 結構。

參數必填型別與限制預設說明
model必填字串，見上表—以當前金鑰 GET /v1/models 的返回為準
prompt必填字串，去除首尾空白後非空—生成或編輯指令
size選填auto、任意比例的 寬x高，或 1K / 2K / 4K—換算成比例與檔位，見下文
n選填整數 1–101另按檔位封頂，見下文
google.image_config.aspect_ratio選填10 個官方比例1:1優先於 size
google.image_config.image_size選填型號檔位內的 1K / 2K / 4K1K優先於 size
image / images選填URL / Data URL，字串或字串陣列—參考圖，同時傳時以 images 為準
quality、response_format、output_format選填任意—傳了不生效

aspect_ratio 可選值：1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9。

image_config 有三種等價寫法，同時出現時按下面的順序取第一個：

  • google.image_config
  • extra_body.google.image_config（OpenAI SDK 的寫法）
  • 頂層扁平的 aspect_ratio / image_size

顯式寫出超過型號檔位的 image_size 返回 400。

size 寫 寬x高 時從不因比例被拒：映射到最接近的官方比例，檔位按長邊推導，並靜默降到型號最高檔位、不報錯。

例如 gemini-3.1-flash-image 傳 4096x4096 返回 2K 圖。檔位簡寫超出型號檔位時則返回 400。

n 另按輸出檔位封頂：4K ≤ 2、2K ≤ 5、1K ≤ 10（回應體積上限），超出返回 400。

參考圖

兩個分組都在 generations 的 image / images 裡傳參考圖，僅限 JSON。每項是 http(s) URL 或 Data URL 字串，URL 須能被服務端取得，不能指向內網地址。

分組數量單張大小
Gemini 全系（含生圖）最多 14 張，超出返回 400遠端 URL ≤ 25 MiB
Gemini 官方直連官方上限 14 張，網關不校驗解碼後 ≤ 20 MiB

「Gemini 全系（含生圖）」會把超過 4 MiB 的參考圖自動壓縮後再生成。gemini-2.5-flash-image 官方最多 3 張參考圖。Data URL 示例：data:image/png;base64,iVBORw0KGgo…，MIME 須與圖片一致。

編輯（僅「Gemini 全系（含生圖）」）

POST /v1/images/edits 推薦 multipart/form-data，也接受 JSON（參考圖為 URL / Data URL）。至少要帶 1 張參考圖。

參數必填型別與限制預設說明
image / image[]必填檔案或 URL 字串，可重複—參考圖
model、prompt必填同「生成」——
size、n選填同「生成」——
aspect_ratio、image_size選填同「生成」的 image_config—multipart 欄位名

「Gemini 官方直連」沒有這個端點，調用返回 404；改圖請在 generations 裡帶參考圖。兩個分組都不支援 mask，傳入返回 400。

非同步

加 HTTP header Prefer: respond-async 後，立即返回 202 Accepted 與 task_id。生成 2K / 4K 大圖時建議使用，可避免長請求被 CDN 逾時中斷。

返回結果

同步返回 OpenAI Images JSON，圖片在 data[].b64_json。

欄位型別說明
createdintegerUnix 秒
modelstring請求的模型 ID
data[].b64_jsonstringBase64 圖片資料
data[].mime_typestring圖片格式，可能是 image/jpeg
usageobject可能返回，含輸入、輸出與總 token
usageMetadataobject「Gemini 官方直連」可能返回，Gemini 官方用量欄位
{
  "created": 1760000000,
  "model": "gemini-3-pro-image",
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ...",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1120,
    "total_tokens": 1162
  }
}

非同步任務

提交後立即返回：

{
  "task_id": "imgtask_EXAMPLE",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=imgtask_EXAMPLE"
}
只能用查詢參數 task_id 查詢，不支援把任務 ID 放進路徑。
狀態含義
pending / processing / retrying進行中，繼續輪詢
completed完成，讀 result_content
failed失敗，只返回 error 字串，沒有錯誤碼

完成後的回應：

{
  "task_id": "imgtask_EXAMPLE",
  "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 每張圖一行 ![image](/assets-runtime/…)，是相對路徑，需自行拼上 https://api.hop-base.com。該網址無需金鑰即可開啟，請勿公開分享，並盡快下載到自己的儲存空間。

示例

文生圖

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "灑滿陽光的木桌上放著一隻陶瓷茶壺，產品攝影",
    "google": {
      "image_config": { "aspect_ratio": "16:9", "image_size": "2K" }
    }
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

curl 示例需要先安裝 jq。若 data[].mime_type 是 image/jpeg，請把副檔名改為 .jpg。

參考圖編輯

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-你的金鑰" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "把第一張圖的杯子換成第二張圖的配色，其餘不變",
    "images": [
      "https://example.com/cup.png",
      "https://example.com/palette.png"
    ],
    "size": "1024x1024"
  }'

注意事項

  • 只有「Gemini 全系（含生圖）」提供 /v1/images/edits，另一個分組請在 generations 裡傳參考圖。
  • 結果是 Base64，可能是 JPEG，儲存前請看 data[].mime_type。
  • 不支援 mask，局部修改請在 prompt 中描述區域。
  • 不能輸出透明背景，background: "transparent" 返回 400。
  • 不支援 stream: true，請保持預設同步或使用非同步任務。
  • 2K / 4K 大圖建議加 Prefer: respond-async，同步請求的客戶端讀取逾時請設長一些。
  • 發付費請求前用實際金鑰調 GET /v1/models 取完整 ID，不要自己加檔位後綴。

常見報錯

參數不合規在生成前返回 400，不計費。

報錯改法
prompt must not be empty / missing prompt補上非空的 prompt
n=3 is too large for 4K output on model gemini-3-pro-image; …調小 n 或分開請求
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K換用 gemini-3-pro-image 或降檔
aspect_ratio "7:3" is not supported for model …改用官方比例
mask is not supported for Gemini image models; …去掉 mask，在 prompt 中描述區域
background=transparent is not supported …去掉 background
Gemini image generation does not support stream=true; …去掉 stream
too many reference images: at most 14 are supported …減少參考圖
reference image 1: reference image exceeds the 20MB limit壓縮圖片後重試
reference image 1: reference image download returned HTTP 404換成服務端能取得的公開 URL
400（引用模型文字）或 502模型拒答或只回文字，請改寫提示詞

計費

「Gemini 全系（含生圖）」按實際交付張數計費；「Gemini 官方直連」按 token 計費，按實際生成的檔位計。參數錯誤與部分失敗不計費；非同步任務終態後，查詢回應的 usage.cost 是實際扣費。

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

下一步

本頁目錄

可用型號請求參數生成參考圖編輯（僅「Gemini 全系（含生圖）」）非同步返回結果非同步任務示例文生圖參考圖編輯注意事項常見報錯計費下一步