Gemini 图像
Google 图像模型有两类,调用方式不同:
| 模型类型 | 可用接口 |
|---|---|
| Gemini 原生图像输出(含 Nano Banana 系列) | ① POST /v1/images/generations、POST /v1/images/edits(OpenAI 兼容)② POST /v1beta/models/{model}:generateContent(Gemini 原生) |
| Imagen | 仅 POST /v1/images/generations(不支持编辑) |
可用模型以 模型列表 返回为准(或控制台模型价格页)。
Imagen 原生的
:predict接口未开放,请使用 OpenAI 兼容的图片生成接口。
最短路径:只要拿到图片,用 OpenAI 兼容接口 + b64_json;需要图文混合输出或多轮对话改图,用 Gemini 原生 generateContent。
方式一:OpenAI 兼容图片接口
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1/images/generations(文生图)、POST /v1/images/edits(改图,仅 Gemini 图像模型) |
| 鉴权 | Authorization: Bearer YOUR_API_KEY |
| Content-Type | application/json;改图也可用 multipart/form-data |
快速示例
curl https://www.nextai-code.com/v1/images/generations \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image",
"prompt": "雨后的江南小巷,青石板反光,电影感摄影",
"size": "16:9",
"quality": "2k",
"n": 1
}'
import base64, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["NEXTAI_API_KEY"], base_url="https://www.nextai-code.com/v1")
resp = client.images.generate(
model="gemini-3.1-flash-image",
prompt="雨后的江南小巷,青石板反光,电影感摄影",
size="16:9",
quality="2k",
)
for i, item in enumerate(resp.data):
with open(f"out_{i}.png", "wb") as f:
f.write(base64.b64decode(item.b64_json))
改图(JSON,参考图用 data URL 或 http(s) 链接):
curl https://www.nextai-code.com/v1/images/edits \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.1-flash-image",
"prompt": "把背景换成金色逆光的摄影棚",
"image": ["data:image/png;base64,iVBORw0KGgo..."]
}'
改图(multipart):
curl https://www.nextai-code.com/v1/images/edits \
-H "Authorization: Bearer $NEXTAI_API_KEY" \
-F "model=gemini-3.1-flash-image" \
-F "prompt=把背景换成金色逆光的摄影棚" \
-F "image[][email protected]" \
-F "image[][email protected]"
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model |
string | 是 | 模型 ID |
prompt |
string | 是 | 提示词 |
n |
integer | 否 | 生成张数,默认 1,平台允许最大 10;模型自身上限往往更低(Imagen 一般不超过 4),超出时可能报错或返回较少张数 |
size |
string | 否 | 决定宽高比。可直接写比例(如 1:1、16:9、9:16、3:2、2:3),或写像素尺寸,平台按下列规则换算为比例:256x256 / 512x512 / 1024x1024 → 1:1,1792x1024 → 16:9,1024x1792 → 9:16,1536x1024 → 3:2,1024x1536 → 2:3。也可写 1k / 2k / 4k 表示分辨率档位 |
quality |
string | 否 | 决定分辨率档位:standard / low / medium / auto / 1k → 1K;hd / high / 2k → 2K;ultra / 4k → 4K。Gemini 图像模型传其他值会报错 |
response_format |
string | 否 | 只支持 b64_json(默认)。传 url 会报错 |
image / images |
string / array | 改图必填 | 仅 /v1/images/edits。JSON 中 image 可为字符串或字符串数组(data URL、公网可访问的 http(s) 链接或纯 base64;纯 base64 按 JPEG 处理,建议用 data URL 标明格式);images 也接受 [{"image_url":{"url":"..."}}],不支持 file_id。multipart 用 image / image[] 文件字段 |
分辨率说明
- Gemini 2 系列图像模型和初代 Nano Banana 不支持分辨率档位,
quality不改变输出尺寸;其他 Gemini 图像模型支持 1K / 2K / 4K(具体档位取决于模型)。 size写1k/2k/4k且与quality指定的档位不一致时报错。- Imagen:
size未传时宽高比默认1:1。quality只识别standard/low/medium/auto/hd/high/4k/ultra及大写1K/2K,小写2k会按 1K 处理,建议用hd指定 2K。 - 档位不承诺精确宽高,实际尺寸以生成文件为准。
Gemini 图像模型不支持的 OpenAI 参数(传了会报错):stream: true、partial_images、response_format: url、style、input_fidelity、mask、background(auto / opaque 以外的值)、moderation(auto 以外的值)、output_format(png 以外的值)、output_compression、watermark: false,以及其他未知字段。风格要求请写进 prompt。
响应
{
"created": 1734567890,
"data": [
{"b64_json": "iVBORw0KGgoAAAANSUhEUgAA...", "url": "", "revised_prompt": ""}
]
}
| 字段 | 类型 | 说明 |
|---|---|---|
created |
integer | Unix 时间戳(秒) |
data[].b64_json |
string | 图片的 base64 数据 |
- 多张结果都在
data[]中,请遍历读取,不要只取data[0]。 - Imagen 中被安全策略过滤的图片会被跳过,返回张数可能少于
n;全部被过滤时报错。 - Gemini 图像模型只返回图片,不返回模型附带的文字说明;需要文字请用方式二。
方式二:Gemini 原生 generateContent
仅适用于 Gemini 图像模型。接口、鉴权、请求与响应格式与 Gemini 原生 完全一致,区别只在 generationConfig 中声明图片输出。
| 项 | 值 |
|---|---|
| 方法与路径 | POST /v1beta/models/{model}:generateContent |
| 鉴权 | x-goog-api-key: YOUR_API_KEY、?key=YOUR_API_KEY 或 Authorization: Bearer YOUR_API_KEY |
快速示例
curl "https://www.nextai-code.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
-H "x-goog-api-key: $NEXTAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "一只戴宇航头盔的橘猫,水彩风格"}]}],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
}
}'
import os
from google import genai
from google.genai import types
client = genai.Client(
api_key=os.environ["NEXTAI_API_KEY"],
http_options=types.HttpOptions(base_url="https://www.nextai-code.com"),
)
resp = client.models.generate_content(
model="gemini-3.1-flash-image",
contents="一只戴宇航头盔的橘猫,水彩风格",
config=types.GenerateContentConfig(
response_modalities=["TEXT", "IMAGE"],
image_config=types.ImageConfig(aspect_ratio="1:1", image_size="2K"),
),
)
for i, part in enumerate(resp.candidates[0].content.parts):
if part.inline_data:
with open(f"out_{i}.png", "wb") as f:
f.write(part.inline_data.data)
elif part.text:
print(part.text)
改图:把参考图作为 inlineData part 放在文本前面:
{
"contents": [{
"role": "user",
"parts": [
{"inlineData": {"mimeType": "image/png", "data": "<base64>"}},
{"text": "把背景换成金色逆光的摄影棚"}
]
}],
"generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
}
关键参数
| 参数 | 说明 |
|---|---|
generationConfig.responseModalities |
需要图片输出时必须显式设为 ["TEXT","IMAGE"],原生接口不会自动补 |
generationConfig.imageConfig |
常用 aspectRatio、imageSize;可选值取决于模型 |
generationConfig.candidateCount |
候选数量,上限取决于模型 |
响应
图片在 candidates[].content.parts[] 中以 inlineData 返回,data 为 base64:
{
"candidates": [{
"content": {
"role": "model",
"parts": [
{"text": "这是你要的橘猫插画。"},
{"inlineData": {"mimeType": "image/png", "data": "iVBORw0KGgo..."}}
]
},
"finishReason": "STOP"
}],
"usageMetadata": {"promptTokenCount": 12, "candidatesTokenCount": 1300, "totalTokenCount": 1312}
}
遍历所有 parts,取带 inlineData 的部分解码即可。finishReason 为 SAFETY 等或存在 promptFeedback.blockReason 时表示被安全策略拦截。
错误
错误体为 OpenAI 格式 {"error": {"message": "...", "type": "...", "code": "..."}},两种方式相同。
| HTTP | 场景 | 处理 |
|---|---|---|
400 prompt_blocked |
提示词或结果被安全策略拦截,或没有返回任何候选 | 修改提示词后重试 |
| 400 | n 大于 10 |
降低 n |
| 400 或 422 | 传入了上文列出的 Gemini 不支持参数、quality 取值无法识别、size 与 quality 指定了不同分辨率、对 Imagen 调用 /v1/images/edits |
按上文修正参数,或换用 Gemini 图像模型改图。错误信息为统一提示,不会指出具体字段 |
| 5xx | 模型未产出图片(如提示词不适合生成图片、Imagen 结果全部被过滤) | 调整提示词后重试;先记录响应头 X-Oneapi-Request-Id |
方式二(原生接口)被安全策略拦截时不一定返回错误:HTTP 200 但 finishReason 为 SAFETY 等、或带 promptFeedback.blockReason,见上文响应说明。
通用错误见 错误码。