Gemini 圖片模型 API
Gemini 3.1 Flash Image、Nano Banana 2.1 與 Gemini 3 Pro Image 的 OpenAI 相容協定和 Gemini 原生協定請求格式、比例、解析度與參考圖說明。
適用範圍
本頁介紹 Gemini 圖片模型。OpenAI 圖片模型請參閱 OpenAI 圖片模型 API,Grok 圖片模型請參閱 Grok 圖片模型 API。
主要差異
Gemini 圖片模型不是 OpenAI Images API 模型。請使用 /v1/chat/completions 或 Gemini 原生的 /v1beta/models/{model}:generateContent,不要送到 /v1/images/generations 或 /v1/images/edits。
模型與能力
| 模型 | 解析度 | 參考圖 | 單次張數 | 計費 |
|---|---|---|---|---|
gemini-3.1-flash-image | 1K (預設) / 2K / 4Kimage_config | 最多 14 張 (Data URI / 公開 URL) | 固定 1 張 | 按次 |
gemini-nano-banana-2.1 | 1K (預設) / 2K / 4Kimage_config | 最多 6 張 (Data URI / 公開 URL) | 固定 1 張 | 按次 |
gemini-3-pro-image | 1K (預設) / 2K / 4Kimage_config | 最多 14 張 (Data URI / 公開 URL) | 固定 1 張 | 按次 |
支援的比例:1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9
- 三個模型都按次計費,價格與解析度、參考圖張數無關。
- 每次請求只回傳 1 張圖片,
n、candidateCount不會生效;需要多張時請同時送出多個請求。 gemini-nano-banana-2.1建議每次最多傳 6 張參考圖,超過的部分可能不會被使用。
實際可用模型以控制台回傳的模型列表為準。
支援的協定
| 協定 | 端點 | 請求本文格式 | 適用情境 |
|---|---|---|---|
| OpenAI 相容協定(建議) | POST /v1/chat/completions | model + messages | OpenAI SDK、統一用戶端和大多數應用程式 |
| Gemini 原生協定 | POST /v1beta/models/{model}:generateContent | contents + generationConfig | 直接使用 Gemini SDK 或需要原生欄位 |
驗證
OpenAI 相容協定使用:
Authorization: Bearer $API_KEY
Content-Type: application/jsonGemini 原生協定也可以依 Gemini 用戶端的習慣使用 x-goog-api-key 請求標頭,填寫的同樣是你的 88API API 金鑰。請勿將真實金鑰寫入前端程式碼、日誌或公開範例。
比例與解析度
比例和解析度透過 image_config 設定:
aspect_ratio:見上方能力表。image_size:1K(預設)、2K、4K,請使用大寫K。
各檔位的輸出像素:
| 比例 | 1K | 2K | 4K |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 2:3 | 848x1264 | 1696x2528 | 3392x5056 |
| 3:2 | 1264x848 | 2528x1696 | 5056x3392 |
| 3:4 | 896x1200 | 1792x2400 | 3584x4800 |
| 4:3 | 1200x896 | 2400x1792 | 4800x3584 |
| 4:5 | 928x1152 | 1856x2304 | 3712x4608 |
| 5:4 | 1152x928 | 2304x1856 | 4608x3712 |
| 9:16 | 768x1376 | 1536x2752 | 3072x5504 |
| 16:9 | 1376x768 | 2752x1536 | 5504x3072 |
| 21:9 | 1584x672 | 3168x1344 | 6336x2688 |
- 未指定比例時,由模型依提示詞選擇畫幅;帶參考圖時,預設跟隨第一張參考圖的比例。需要固定尺寸時,請明確傳入
aspect_ratio。 - 輸出可能是 JPEG 或 PNG,請依回傳的 MIME 類型儲存,不要假定副檔名。
OpenAI 相容協定(建議)
文生圖
curl https://api.88api.ai/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"messages": [
{
"role": "user",
"content": "生成一張坐在窗邊的橘貓圖片,午後的自然光,寫實攝影風格"
}
],
"extra_body": {
"google": {
"image_config": {
"aspect_ratio": "16:9",
"image_size": "2K"
}
}
}
}'image_config 的寫法
比例和解析度必須寫在 extra_body.google.image_config 裡,欄位名稱用 aspect_ratio、image_size(底線寫法)。寫在請求最外層的 image_config、aspect_ratio、size 會被忽略;寫成 imageConfig、aspectRatio 等駝峰式寫法會被拒絕。
攜帶參考圖
curl https://api.88api.ai/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "參考第一張圖的人物,生成同一個人物的電影海報" },
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } }
]
}
],
"extra_body": {
"google": { "image_config": { "aspect_ratio": "2:3", "image_size": "2K" } }
}
}'image_url.url可以是 Data URI 或公開圖片網址。Data URI 必須帶有完整的媒體類型前綴,例如data:image/png;base64,...。- 支援 PNG、JPEG、WebP、GIF,不支援 BMP。單張建議不超過 7 MB。
- 多張參考圖按順序排列,提示詞裡可以用「第一張」「第二張」指稱。
請求欄位
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
model | string | 是 | Gemini 圖片模型名稱。 |
messages | array | 是 | OpenAI Chat Completions 訊息陣列,通常只有一則 user 訊息。 |
messages[].content | string 或 array | 是 | 純文字使用字串;文字和參考圖混合時使用內容陣列。 |
content[].image_url.url | string | 否 | 參考圖,Data URI 或公開網址。 |
extra_body.google.image_config.aspect_ratio | string | 否 | 畫面比例。 |
extra_body.google.image_config.image_size | string | 否 | 1K、2K、4K。 |
回應
圖片以 Markdown 圖片的形式放在 choices[0].message.content 裡:
{
"choices": [
{
"message": {
"role": "assistant",
"content": ""
},
"finish_reason": "stop"
}
]
}從 content 中擷取 data:<mime>;base64,... 即可取得圖片。不要把回應當成 /v1/images/generations 的 data 陣列解析。
Gemini 原生協定
文生圖
curl "https://api.88api.ai/v1beta/models/gemini-3-pro-image:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{ "text": "生成一張坐在窗邊的橘貓圖片,午後的自然光,寫實攝影風格" }
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" }
}
}'參考圖
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "參考這張圖片,生成同一個人物的電影海報" },
{ "inlineData": { "mimeType": "image/png", "data": "<BASE64_DATA>" } }
]
}
],
"generationConfig": {
"imageConfig": { "aspectRatio": "2:3" }
}
}公開圖片也可以用 fileData:{ "fileData": { "mimeType": "image/jpeg", "fileUri": "https://..." } }。
回應
圖片位於 candidates[0].content.parts[].inlineData,mimeType 為圖片類型,data 為 Base64。
串流與逾時
可以使用 stream: true,但圖片會在一個事件裡一次回傳,沒有漸進式預覽。建議使用非串流請求,並將用戶端逾時設定為 5 分鐘以上:4K 圖片通常需要 30 至 60 秒,尖峰時段會更久。
錯誤的請求方式
# 錯誤:Gemini 圖片模型不要使用 OpenAI Images API 路徑
curl https://api.88api.ai/v1/images/generations \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3-pro-image",
"prompt": "一隻橘貓"
}'這類請求會回傳 请使用 Gemini 原生接口调用 / please use the Gemini native API(請使用 Gemini 原生介面呼叫)。請改用本頁的 Chat Completions 或原生 generateContent 格式。
常見錯誤
| 錯誤訊息 | 原因 |
|---|---|
请使用 Gemini 原生接口调用 | 請求送到了 /v1/images/*。 |
extra_body.google.imageConfig is not supported, use extra_body.google.image_config instead | image_config 寫成了駝峰式寫法。 |
mime type is not supported by Gemini | 參考圖格式不受支援,例如 BMP。 |
failed to download file | 參考圖網址無法下載,請確認連結可公開存取。 |
| 提示內容審核未通過 | 提示詞或參考圖未通過安全審核,或模型只回覆了文字而沒有出圖,請調整提示詞後重試。 |
以上請求失敗不扣費。