Gemini 图像生成
使用本接口输入文本描述或参考图片，创建图像生成任务，支持文生图（Text-to-Image）与图生图（图像编辑 / Image Editing）。Gemini 图像模型统称 Nano Banana，内置思考（Thinking）过程，生成的图像以 Base64 编码返回，并带有 SynthID 水印。
接口地址
http
POST /v1beta/models/<Model ID>:generateContent认证
| 方式 | 说明 |
|---|---|
| Bearer Token | 在请求头中携带 Authorization: Bearer <API_key> 用于验证账户信息。 |
鉴权说明： 如遇到不能识别
Authorization参数的情形，可将鉴权信息通过x-goog-api-key请求头传递：httpx-goog-api-key: <API Key>
请求头
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
Content-Type | string | 是 | 请求体的媒介类型，请设置为 application/json |
Authorization | string | 是 | Bearer API_key，用于验证账户信息 |
说明： 模型 ID 以 URL 路径中的
<Model ID>占位符指定（如/v1beta/models/ge-3.1-fl-im:generateContent），请求体中无需再传模型字段。
请求体
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
contents | array | 是 | - | 输入内容列表，可包含文本与图片，详情见下方子表格 |
generationConfig.responseModalities | array | 是 | ["TEXT"] | 输出模态，图像生成需设置为 ["IMAGE"]；需要同时返回文本与图像时设置为 ["TEXT","IMAGE"] |
generationConfig.imageConfig | object | 否 | - | 图像生成配置（宽高比、分辨率、人物等），详情见下方子表格 |
tools | array | 否 | - | 工具配置，如 [{ "googleSearch": {} }] 可基于实时信息联网生成图像 |
contents 详细参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
contents[].role | string | 否 | 消息角色，取值 user / model；省略时默认为 user |
contents[].parts | array | 是 | 内容片段列表，支持文本与图片，详情见下方 parts 子表格 |
parts 详细参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
parts[].text | string | 否 | 文本提示词，用于描述期望生成的图像或编辑指令 |
parts[].inline_data | object | 否 | 内嵌图片数据，用于图生图（图像编辑）场景，与 text 二选一或同时使用 |
parts[].inline_data.mime_type | string | 条件必填 | 图片 MIME 类型，如 image/png、image/jpeg、image/webp |
parts[].inline_data.data | string | 条件必填 | 图片的 Base64 编码内容（不含 data:...;base64, 前缀） |
imageConfig 详细参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
imageConfig.aspectRatio | string | 否 | 1:1 | 生成图像的宽高比，可选值见下方列表 |
imageConfig.imageSize | string | 否 | 1K | 输出图像分辨率，取值 1K、2K、4K，ge-3.1-fl-im 额外支持 0.5K（512px）。K 必须大写，小写（如 1k）会被拒绝 |
imageConfig.personGeneration | string | 否 | PERSON_GENERATION_UNSPECIFIED（未指定时默认为此值） | 是否允许生成人物图像。旧模型取值为 dont_allow / allow_adult / allow_all；Nano Banana 2.1 及之后的模型取值为 PERSON_GENERATION_UNSPECIFIED / ALLOW_ALL / ALLOW_ADULT / ALLOW_NONE，详见下方说明 |
宽高比（aspectRatio）取值
- ge-3.1-fl-im / ge-3-pr-im / ge-2.5-fl-im：
1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 - ge-3.1-fl-im 额外支持：
1:4、1:8、4:1、8:1
请求示例
文生图
通过 responseModalities 请求图像输出，使用文本提示词生成一张图像。官方推荐将 responseModalities 设置为 ["TEXT", "IMAGE"]，允许模型在返回图像的同时附带文本说明；设置为 ["IMAGE"] 则仅返回图像。
bash
curl --location --request POST 'https://neolink.com/api/v1beta/models/<Model ID>:generateContent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API Key>' \
--data-raw '{
"contents": [
{
"parts": [
{
"text": "一只可爱的橘猫，戴着圆框眼镜，坐在窗台边看报纸，午后阳光洒落"
}
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "2K",
"personGeneration": "ALLOW_NONE"
}
}
}'python
import base64
import requests
url = "https://neolink.com/api/v1beta/models/<Model ID>:generateContent"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer <API Key>",
}
payload = {
"contents": [
{
"parts": [
{
"text": "一只可爱的橘猫，戴着圆框眼镜，坐在窗台边看报纸，午后阳光洒落"
}
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {
"aspectRatio": "1:1",
"imageSize": "2K",
"personGeneration": "ALLOW_NONE"
}
}
}
resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
data = resp.json()
# 遍历返回的 parts：文本片段直接打印，图像片段解码保存
for part in data["candidates"][0]["content"]["parts"]:
if part.get("text"):
print(part["text"])
elif "inlineData" in part:
image = part["inlineData"]["data"]
with open("output.png", "wb") as f:
f.write(base64.b64decode(image))图生图（图像编辑）
在 parts 中同时传入参考图片（inline_data）与编辑指令文本，模型基于参考图执行图像编辑。
Base64 编码说明：
inline_data.data为图片文件进行 Base64 编码后的字符串，参考脚本如下：
bash
#!/usr/bin/env bash
set -euo pipefail
IMAGE_PATH="./input.jpg"
if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
B64FLAGS="--input"
else
B64FLAGS="-w0"
fi
base64 $B64FLAGS "$IMAGE_PATH" > base64.txtbash
curl --location --request POST 'https://neolink.com/api/v1beta/models/<Model ID>:generateContent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API Key>' \
--data-raw '{
"contents": [
{
"parts": [
{
"text": "将图片中的背景替换为海边日落，画面保持写实风格"
},
{
"inline_data": {
"mime_type": "image/jpeg",
"data": "<Base64 Code>"
}
}
]
}
],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"personGeneration": "ALLOW_NONE"
}
}
}'python
import base64
import requests
url = "https://neolink.com/api/v1beta/models/<Model ID>:generateContent"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer <API Key>",
}
# 读取本地图片并编码
with open("input.jpg", "rb") as f:
image_base64 = base64.b64encode(f.read()).decode("utf-8")
payload = {
"contents": [
{
"parts": [
{
"text": "将图片中的背景替换为海边日落，画面保持写实风格"
},
{
"inline_data": {
"mime_type": "image/jpeg",
"data": image_base64
}
}
]
}
],
"generationConfig": {
"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"personGeneration": "ALLOW_NONE"
}
}
}
resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
data = resp.json()
# 提取返回图像并保存
for part in data["candidates"][0]["content"]["parts"]:
if "inlineData" in part:
image = part["inlineData"]["data"]
with open("output.png", "wb") as f:
f.write(base64.b64decode(image))
break多轮图像编辑
将上一轮模型返回的图像放入对话历史（role: "model" 的 parts 中），即可在原有图像基础上继续编辑，实现多轮迭代修改。
注意：
ge-3.1-fl-li-im（Nano Banana 2 Lite）不支持多轮编辑。
bash
curl --location --request POST 'https://neolink.com/api/v1beta/models/<Model ID>:generateContent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API Key>' \
--data-raw '{
"contents": [
{
"role": "user",
"parts": [
{
"text": "生成一张客厅照片，浅色沙发，落地窗"
}
]
},
{
"role": "model",
"parts": [
{
"inline_data": {
"mime_type": "image/png",
"data": "<上一轮生成的图像 Base64>"
}
}
]
},
{
"role": "user",
"parts": [
{
"text": "把沙发换成深蓝色丝绒材质，其他保持不变"
}
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {
"aspectRatio": "16:9"
}
}
}'python
import base64
import requests
url = "https://neolink.com/api/v1beta/models/<Model ID>:generateContent"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer <API Key>",
}
def generate(contents):
payload = {
"contents": contents,
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {"aspectRatio": "16:9"},
},
}
resp = requests.post(url, headers=headers, json=payload, timeout=60)
resp.raise_for_status()
return resp.json()
# 第一轮：生成初始图像
contents = [
{"role": "user", "parts": [{"text": "生成一张客厅照片，浅色沙发，落地窗"}]}
]
first = generate(contents)
image_part = next(
p for p in first["candidates"][0]["content"]["parts"] if "inlineData" in p
)
# 第二轮：将模型返回的图像放入历史，继续编辑
contents.append({"role": "model", "parts": [image_part]})
contents.append(
{"role": "user", "parts": [{"text": "把沙发换成深蓝色丝绒材质，其他保持不变"}]}
)
second = generate(contents)
for part in second["candidates"][0]["content"]["parts"]:
if "inlineData" in part:
with open("output_round2.png", "wb") as f:
f.write(base64.b64decode(part["inlineData"]["data"]))
break说明： 对话历史中
role: "model"的图像片段需完整保留上一轮返回的inlineData（含mimeType与data），Python 示例中可直接将响应里的 part 对象原样追加到contents；使用 cURL 时将其转换为 snake_case（inline_data、mime_type）。
支持模型Id：
ge-3.1-fl-im（Nano Banana 2）——综合性能与成本的最佳平衡，最推荐的图像模型。支持最高 4K、512px 小图，最多 10 个物体 / 4 个角色的一致性参考，支持 Google 搜索与图片搜索互联生成、视频转图像ge-3.1-fl-li-im（Nano Banana 2 Lite）——最快最便宜的图像模型，仅支持 1K 分辨率，不支持联网搜索与多轮编辑，最多 14 个物体的高保真参考ge-3-pr-im（Nano Banana Pro）——专业级图像模型，最高 4K，适合复杂指令与专业素材生产。支持最多 6 个物体 / 5 个角色 / 3 个风格参考，支持交错输出文本与图像、联网搜索ge-2.5-fl-im（Nano Banana）——前代模型，固定 1024px 分辨率，最多 3 张参考图，建议迁移到 Nano Banana 2 Lite
<Model ID>需替换为具体模型 ID，即 列出模型 返回的name去掉models/前缀后的名称，如ge-3.1-fl-im；具体可用模型、分辨率与参考图数量以平台实际为准。
personGeneration取值说明：
- 旧模型（Nano Banana 2.1 之前）：
dont_allow、allow_adult、allow_all- Nano Banana 2.1 及之后的模型：
PERSON_GENERATION_UNSPECIFIED（默认值）、ALLOW_ALL、ALLOW_ADULT、ALLOW_NONE
旧模型 Nano Banana 2.1 及之后 说明 dont_allowALLOW_NONE禁止生成人物 allow_adultALLOW_ADULT仅允许成年人 allow_allALLOW_ALL允许所有人物，包括儿童 —— PERSON_GENERATION_UNSPECIFIED（默认值）未指定时默认为此值，由模型决定是否生成人物
响应体
| 参数名 | 类型 | 说明 |
|---|---|---|
candidates | array | 生成的候选结果列表 |
candidates[].content | object | 模型生成的内容 |
candidates[].content.role | string | 消息角色，固定为 model |
candidates[].content.parts | array | 内容片段列表，图像生成时包含 inlineData |
candidates[].content.parts[].inlineData.mimeType | string | 生成图像的 MIME 类型，如 image/png |
candidates[].content.parts[].inlineData.data | string | 生成图像的 Base64 编码数据 |
candidates[].finishReason | string | 停止原因：STOP（正常结束）/ MAX_TOKENS / SAFETY / RECITATION / IMAGE_SAFETY / PROHIBITED_CONTENT 等 |
usageMetadata | object | Token 用量信息 |
usageMetadata.promptTokenCount | int | 输入 Prompt 的 token 数 |
usageMetadata.candidatesTokenCount | int | 生成的响应 token 数 |
usageMetadata.totalTokenCount | int | 输入与输出的总 token 数 |
modelVersion | string | 实际使用的模型版本 |
响应示例
json
{
"candidates": [
{
"content": {
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "<Base64 Code>"
}
}
],
"role": "model"
},
"finishReason": "STOP"
}
],
"usageMetadata": {
"promptTokenCount": 11,
"candidatesTokenCount": 1290,
"totalTokenCount": 1301
},
"modelVersion": "ge-3.1-fl-im"
}说明：
- 返回的图像数据为 Base64 编码字符串（
inlineData.data字段），需在客户端解码后使用或保存为图片文件，解码参考脚本见上文"图生图（图像编辑）"一节。- 图像模型内置思考（Thinking）过程，默认开启，用于先优化构图再输出最终图像；所有生成图像均带 SynthID 水印。
- 通过
tools启用 Google 搜索可基于实时信息生成图像（ge-3.1-fl-im还支持 Google 图片搜索），该能力在ge-3.1-fl-li-im上不支持。