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

生成圖片

OpenAI Images 相容的文生圖：GPT Image、Gemini Banana 與 Seedream；Seedream 與 Gemini 也在這裡傳參考圖。

POST/v1/images/generations

按提示詞生成圖片。GPT Image 與 Gemini 回傳 data[].b64_json，Seedream 回傳 data[].url（24 小時有效）。Seedream 與兩個 Gemini 分組也在這個端點用 image / images 做圖生圖。

每個模型的參數與上限不同：在下方選擇模型，參數列隨之切換，數字取自外掛校驗程式碼匯出的規格（與 /spec/models/<model>.json 同源）。GPT Image 生成超過約 40 秒時伺服器端先回 200 並寫空白保活，此後失敗也仍是 200——請以回應體是否含 error 判斷成敗，用戶端讀逾時不少於 300 秒。

可靈與 Midjourney 也在這個端點提交，但一律非同步（202 + id，用查詢影片任務輪詢），在模型選擇裡選「可靈」「Midjourney」查看；Grok Imagine 見 Grok Imagine 生圖。

  • GPT Image 不支援官方串流欄位 partial_images，請省略；stream: true 回傳的是 HopBase Images SSE，不是逐張預覽事件。
  • output_compression、moderation、user、response_format 只在同步文生圖 JSON 與同步 multipart 編輯中透傳；JSON 編輯與非同步任務不保留這些欄位。GPT Image 非同步只保留 model、prompt、n、size、quality、background、output_format、input_fidelity 和編輯用的圖片 / mask。
  • Gemini 計費：「Gemini 全系（含生圖）」按張計費，1K / 2K / 4K 同價；「Gemini 官方直連」按 token 計費（輸出 token × 單價）。
  • Chat Completions 轉 Images 的橋接路徑只保留前 6 張參考圖；要用 14 張請直接呼叫本端點。

請求標頭

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

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

回傳

200同步成功

202非同步受理：GPT Image / Gemini 帶 Prefer: respond-async 時；可靈與 Midjourney 一律如此

created:選填integer

Unix 秒

data:必填array of object

每張圖一項

usage:選填object

可能回傳

錯誤

400參數不合規（生成前拒絕，不計費）；內容安全攔截 safety_rejected
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
GPT Image 報錯原文
# 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)
Gemini 報錯原文
# 「Gemini 全系（含生圖）」
prompt must not be empty
n must be between 1 and 10 for model gemini-3-pro-image
n=3 is too large for 4K output on model gemini-3-pro-image; at most 2 images per request at this size (response size limit); lower n or send separate requests
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K
model gemini-3-pro-image: size "big" is not valid; expected WIDTHxHEIGHT (any aspect ratio, mapped to the nearest official tier) or 1K/2K/4K
aspect_ratio "7:3" is not supported for model gemini-3-pro-image; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size "4K" is not supported for model gemini-3.1-flash-image; supported: 1K, 2K
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt
too many reference images: at most 14 are supported for this model, got 15

# 「Gemini 官方直連」
missing prompt
Gemini image generation does not support stream=true; send a non-streaming request
n must be at most 10
n=6 is too large for 2K output on model gemini-3.1-flash-image; at most 5 images per request at this size (response size limit); lower n or send separate requests
Images generations only accepts a JSON request body: ...
size 4K is not supported for model gemini-3.1-flash-image; supported tiers: 1K, 2K
size "banana" is not valid for model gemini-3-pro-image; use auto, WIDTHxHEIGHT (e.g. 1024x1024, mapped to the nearest supported aspect ratio and capped at the model's largest tier), or one of: 1K, 2K, 4K
image_config.aspect_ratio "7:3" is not supported; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_config.image_size "4K" is not supported for model gemini-3.1-flash-image; allowed values: 1K, 2K
mask is not supported for model gemini-3-pro-image; remove mask and describe the region to edit in the prompt
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
reference image 1: reference image exceeds the 20MB limit
reference image 1: reference image URL must not point to an internal address
reference image 1: reference image download returned HTTP 404
reference image 1: reference file is not a supported image type
Seedream 報錯原文
model seedream-5-0-pro only supports size 1K, 1.5K, 2K or a valid WIDTHxHEIGHT pixel size   # 例如 "size": "auto"
model seedream-5-0-lite requires the total pixel count of size to be between 3686400 and 16777216
size aspect ratio must be between 1:16 and 16:1
missing prompt
response_format only supports url
only a single output is supported (n=1)
model seedream-4-5 only supports output_format jpeg
optimize_prompt_options must be an object
image must be a URL/data URL string or an array of strings
every item in the image array must be a URL or data URL string
image must not be empty
at most 10 reference images are supported
reference image 1 is invalid: data URL must be base64-encoded
reference image 1 is invalid: unsupported image format image/svg+xml
reference image 1 is invalid: a single image must not exceed 30 MB
image edits require at least one image reference            # /v1/images/edits 未帶圖
seedream does not accept a traditional mask; ...            # /v1/images/edits 帶 "mask" 即拒，null 也一樣

相關頁面