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 或公网图片 URL。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 或公网 URL。 |
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。请改用本页的 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 | 参考图 URL 无法下载,请确认链接可公开访问。 |
| 提示内容审核未通过 | 提示词或参考图未通过安全审核,或模型只回复了文字没有出图,请调整提示词后重试。 |
以上请求失败不扣费。