Gemini 香蕉生图文档

本页说明如何用 Google Generative Language v1beta 协议调用 We-AI 的 Gemini 香蕉生图（俗称 Nano Banana）。标准 Google 协议的客户端（官方 google-genai SDK、各类 Gemini 兼容工具）只要把 Base URL 指到网关即可直接出图 / 改图。

如果你的客户端走的是 OpenAI 的 /v1/images/generations、/v1/images/edits，请阅读 Gemini 兼容 OpenAI 协议接入指南。

核心结论：

生成图片使用同步接口：POST /v1beta/models/{model}:generateContent
查看可用模型使用：GET /v1beta/models
只做图片生成 / 改图；没有文本、对话、countTokens、embedContent
文生图、图生图（改图）走同一个接口，区别只在于请求里带不带参考图
有两个分组（aistudio香蕉、adobe香蕉），协议相同，支持的模型和参数略有差别，见下方「两个分组的区别」

官方参考：

接入线路

当前可用入口如下，接入时选择其中一个作为 BASE_URL 即可：

https://us-la.we-token.cc/：国际加速路线。
https://asian-acc.we-token.cc/：亚太加速路线。
https://sub2api.we-token.cc/：国内加速路线。
https://sub2api.aitu.art/：Aitu 独立站点入口；它是早先单独的独立站点，与 we-token.cc 的用户体系不打通。

us-la.we-token.cc、asian-acc.we-token.cc 和 sub2api.we-token.cc 都是 We-AI 的 we-token.cc 站点，用户体系相同，区别只是加速区域不同。sub2api.aitu.art 是早先单独的独立站点，与 we-token.cc 的用户体系不打通，API Key、余额和账号信息请以对应站点后台为准。

两个分组的区别

Gemini 香蕉有两个分组，用哪个取决于你的 API Key 属于哪个分组（创建 API Key 时选择的分组）。两个分组的协议、接口路径、请求体结构完全相同，差别如下：

项	`aistudio香蕉`	`adobe香蕉`
Nano Banana Pro `gemini-3-pro-image`	✅	✅
Nano Banana 2 `gemini-3.1-flash-image`	✅	✅
Nano Banana 2.1 `gemini-nano-banana-2.1`	✅	❌
不传 `imageSize` 时	`1K`（与 Google 官方默认一致）	`2K`
思考档位 `thinkingLevel`	✅ 支持	不支持（传了忽略）
返回图片格式	按 Google 实际返回，目前基本是 `image/jpeg`	通常是 `image/png`
`usageMetadata`	Google 返回了就是真实值；没返回时按 Google 官方每图 token 数估算	估算值

后文凡是没有特别注明分组的内容，两个分组都适用。

一、接口概览

Gemini 香蕉生图当前使用两个主要接口。

用途	方法	路径	说明
查看模型列表	`GET`	`/v1beta/models`	用于确认当前可用模型、模型 ID 和平台返回字段。
同步生成图片	`POST`	`/v1beta/models/{model}:generateContent`	用于文生图、图生图、改图。

协议路径还包含流式 :streamGenerateContent，但网关一次性出整图，不推荐使用流式接口（见后文）。

示例中的 BASE_URL 请替换成你的平台入口，例如：

txt

https://us-la.we-token.cc
https://asian-acc.we-token.cc
https://sub2api.we-token.cc
https://sub2api.aitu.art

二、鉴权方式

鉴权使用 We-AI 的 API Key，请求头格式如下：

http

Authorization: Bearer sk-xxxx
Content-Type: application/json

后续所有请求示例都使用 Authorization: Bearer ${API_KEY}。请不要把真实 API Key 写进前端代码、公开仓库或聊天截图。

三、查看模型列表

建议接入前先请求模型列表，确认当前可用模型：

bash

curl "${BASE_URL%/}/v1beta/models" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json"

Windows PowerShell 中建议使用 curl.exe：

powershell

curl.exe "$($env:BASE_URL.TrimEnd('/'))/v1beta/models" `
  -H "Authorization: Bearer $($env:API_KEY)" `
  -H "Content-Type: application/json"

如果模型列表返回为空、401 或 404，请优先检查：

BASE_URL 是否正确。
API_KEY 是否有效。
是否把 /v1beta 重复写进了 BASE_URL。
当前账号是否开通了 Gemini 香蕉生图模型。

四、支持的模型

调用名（`{model}`）	俗称	说明	分组	参考图上限	n
`gemini-3-pro-image`	Nano Banana Pro	质量优先	两个分组都有	14	强制1
`gemini-3.1-flash-image`	Nano Banana 2	速度优先、便宜	两个分组都有	14	强制1
`gemini-nano-banana-2.1`	Nano Banana 2.1	新一代 flash，比例更多、支持三档思考	仅 `aistudio香蕉`	14	强制1

说明：

末尾带 -preview 的写法是别名：gemini-3-pro-image-preview ≡ gemini-3-pro-image，gemini-3.1-flash-image-preview ≡ gemini-3.1-flash-image。
adobe香蕉 另外认 gemini-3.0-pro-image（及 -preview）作为 Pro 的别名；aistudio香蕉 不认这个写法，会返回 404。
模型名区分大小写。计费、日志按上面的调用名归类（别名归并到基础名）。

模型名规则

模型名只使用基础名，不带比例和清晰度后缀（例如 gemini-3-pro-image-preview-4k 会返回 404）；比例、清晰度通过请求体的 generationConfig.imageConfig（aspectRatio / imageSize）控制。

五、请求体结构

jsonc

{
  "contents": [{
    "parts": [
      { "text": "把所有 text part 拼成最终 prompt" },
      { "inlineData": { "mimeType": "image/png", "data": "<base64>" } },          // 可选，参考图（改图）
      { "fileData": { "mimeType": "image/jpeg", "fileUri": "https://..." } }      // 可选，参考图用公网 URL 传
    ]
  }],
  "generationConfig": {
    "responseModalities": ["IMAGE"],          // 可选，见下
    "imageConfig": {
      "aspectRatio": "16:9",                  // 可选，见下方支持列表
      "imageSize": "2K"                       // 可选，见下
    },
    "thinkingConfig": {
      "thinkingLevel": "high"                 // 可选，仅 aistudio香蕉，见下
    }
  }
}

字段说明：

字段	必填	说明
`contents[].parts[].text`	是	所有 text part 拼成一个 prompt。至少要有一个非空 text，否则返回 `400`。
`contents[].parts[].inlineData`	否	参考图，纯 base64。有参考图 = 改图（image2image）。
`contents[].parts[].fileData.fileUri`	否	参考图的公网 `http(s)://` 地址，由服务端下载。和 `inlineData` 可以混用，合计算张数。
`generationConfig.imageConfig.aspectRatio`	否	见下方支持列表。
`generationConfig.imageConfig.imageSize`	否	清晰度档位：`1K` / `2K` / `4K`（大小写不敏感）。不传时 `aistudio香蕉` 为 `1K`、`adobe香蕉` 为 `2K`。
`generationConfig.thinkingConfig.thinkingLevel`	否	思考档位，仅 `aistudio香蕉` 生效，见下方「思考档位」。
`generationConfig.responseModalities`	否	解析但忽略——网关永远只回一张图。传 `["IMAGE"]` 或不传都行。

支持的 aspectRatio：

通用：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9。
超宽 / 超长比例 1:4、4:1、1:8、8:1：adobe香蕉 两个模型都支持；aistudio香蕉 只有 gemini-nano-banana-2.1 支持，gemini-3-pro-image、gemini-3.1-flash-image 都不支持。
aistudio香蕉 传了不支持的比例不报错，按不传处理（由模型按提示词决定画面形状）。例如 gemini-3.1-flash-image 传 1:8，照常返回 200，但出图不是 1:8（实测回 1408×768）——需要超宽 / 超长图请用 gemini-nano-banana-2.1。adobe香蕉 请只传上面列出的比例。

实际输出像素由「比例 + 分辨率档」决定，不等于 imageSize 的字面正方形。例如 2:3 / 2K 实测回 1696×2528，16:9 / 1K 回 1376×768，gemini-nano-banana-2.1 的 4:1 / 4K 回 8256×2048、1:8 / 1K 回 352×2928、8:1 / 1K 回 2928×352。把 imageSize 理解成“清晰度档位”，把 aspectRatio 理解成“形状”，二者独立。

思考档位（仅 aistudio香蕉）

thinkingLevel 控制模型出图前的思考量，取值 minimal / medium / high（大小写不敏感）。每个模型支持的档位不同：

模型	支持的档位	不传时
`gemini-3-pro-image`	`high`	Google 默认（官方为 high）
`gemini-3.1-flash-image`	`minimal`、`high`	Google 默认（官方为 minimal）
`gemini-nano-banana-2.1`	`minimal`、`medium`、`high`	Google 默认（官方为 medium）

不传、传空、传不认识的值、或传了该模型不支持的档位（例如 gemini-3.1-flash-image 传 medium）：不报错，一律按不传处理，照常出图。档位越高出图越慢；minimal 最快。

暂不支持（传了会被忽略，不报错）：tools（含 googleSearch 接地）、responseModalities 里的 TEXT、temperature 等文本采样参数。

六、文生图请求示例

curl 示例：

bash

curl -s "${BASE_URL%/}/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "a lone red maple tree on a misty hill, watercolor"}]}],
    "generationConfig": {"imageConfig": {"aspectRatio": "2:3", "imageSize": "2K"}}
  }' \
| python3 -c 'import sys,json,base64; d=json.load(sys.stdin); p=d["candidates"][0]["content"]["parts"][0]["inlineData"]; ext={"image/jpeg":"jpg","image/webp":"webp"}.get(p["mimeType"],"png"); open("out."+ext,"wb").write(base64.b64decode(p["data"])); print("saved out."+ext)'

带思考档位（aistudio香蕉，Nano Banana 2.1）：

bash

curl -s "${BASE_URL%/}/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "a cozy reading nook by a rainy window, warm light"}]}],
    "generationConfig": {
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"},
      "thinkingConfig": {"thinkingLevel": "high"}
    }
  }'

Windows PowerShell 示例：

powershell

curl.exe "$($env:BASE_URL.TrimEnd('/'))/v1beta/models/gemini-3.1-flash-image:generateContent" `
  -H "Authorization: Bearer $($env:API_KEY)" `
  -H "Content-Type: application/json" `
  -d "{`"contents`":[{`"parts`":[{`"text`":`"a lone red maple tree on a misty hill, watercolor`"}]}],`"generationConfig`":{`"imageConfig`":{`"aspectRatio`":`"2:3`",`"imageSize`":`"2K`"}}}"

七、响应结构和图片保存

jsonc

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        { "inlineData": { "mimeType": "image/jpeg", "data": "<base64>" } }
      ]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 1680,
    "totalTokenCount": 1692,
    "promptTokensDetails": [{ "modality": "TEXT", "tokenCount": 12 }]
  },
  "modelVersion": "gemini-3.1-flash-image"
}

图片在 candidates[0].content.parts[0].inlineData.data，base64。
按 inlineData.mimeType 决定文件扩展名：aistudio香蕉 目前基本是 image/jpeg，adobe香蕉 通常是 image/png。不要写死成 .png。
usageMetadata：aistudio香蕉 在 Google 返回了 token 计数时原样给出（可能含思考 token 等字段），没返回时按 Google 官方每图 token 数估算；adobe香蕉 为估算值。

aistudio香蕉 估算时使用的 Google 官方每图 token 数：

模型	输出 1 张 1K	输出 1 张 2K	输出 1 张 4K	每张参考图（输入）
`gemini-3-pro-image`	1120	1120	2000	560
`gemini-3.1-flash-image`	1120	1680	2520	1120
`gemini-nano-banana-2.1`	1120	1680	3780	1120

八、图生图 / 改图

把参考图作为 inlineData 放进 parts（最多 14 张）。base64 太长，建议用脚本拼请求体：

bash

python3 - <<'PY'
import json, base64
b64 = base64.b64encode(open("car.png","rb").read()).decode()
req = {
  "contents": [{"parts": [
    {"text": "turn this into a nighttime scene with stars and headlights on"},
    {"inlineData": {"mimeType": "image/png", "data": b64}}
  ]}],
  "generationConfig": {"imageConfig": {"aspectRatio": "16:9", "imageSize": "1K"}}
}
json.dump(req, open("req.json","w"))
PY

curl -s "${BASE_URL%/}/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @req.json \
| python3 -c 'import sys,json,base64; d=json.load(sys.stdin); p=d["candidates"][0]["content"]["parts"][0]["inlineData"]; ext={"image/jpeg":"jpg","image/webp":"webp"}.get(p["mimeType"],"png"); open("edit."+ext,"wb").write(base64.b64decode(p["data"]))'

参考图也可以直接给公网地址，由服务端下载，请求体会小很多：

json

{
  "contents": [{"parts": [
    {"text": "keep the product unchanged, change background to a clean warm studio"},
    {"fileData": {"mimeType": "image/jpeg", "fileUri": "https://example.com/reference.jpg"}}
  ]}],
  "generationConfig": {"imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}}
}

注意：

inlineData.data 只放纯 base64，不要带 data:image/png;base64, 前缀。
mimeType 要和原图格式一致，常见值是 image/png、image/jpeg、image/webp。
fileUri 必须是服务端能直接访问的 http(s):// 地址（不需要登录、不是内网地址）。
最多 14 张参考图，单张 ≤ 20 MB。aistudio香蕉 对超过 20 MB 的图会先自动压缩再用，图太大（像素过多）压不动时返回 413。

九、同步生成，不推荐流生成

网关一次性出整图，所以“流”里只有一个 chunk：

默认：返回一个 JSON 数组 [ {…同上的响应…} ]。
加 ?alt=sse：返回 SSE，一行 data: {…}\n\n。

行为和数据结构与 :generateContent 一致，只是外层包装不同。但高分辨率图片生成本身耗时较长，流式并不能明显降低最终等待时间，因此优先使用同步接口，避免使用：

txt

POST /v1beta/models/{model}:streamGenerateContent

十、错误格式

Google 风格错误：

json

{ "error": { "code": 400, "message": "...", "status": "INVALID_ARGUMENT" } }

常见状态码：

HTTP	含义	怎么处理
400	参数不合法：JSON 不合法、无 prompt、参考图超过 14 张、`imageSize` 不在可选档位（`aistudio香蕉`）等。`adobe香蕉` 的内容安全审核拒绝（`prompt_unsafe` / `image_unsafe`）也是 400。	按 `message` 修改请求；内容审核拒绝需要调整提示词或参考图。
401 / 403	API Key 无效、已禁用，或余额不足。	检查 Key 和余额。
404	模型名不对，或该模型不在你的分组里（例如 `adobe香蕉` 调 `gemini-nano-banana-2.1`）。	按第四节核对模型名和分组。
413	参考图或请求体太大。	压缩图片、减少张数，或改用 `fileData.fileUri` 传地址。
451	仅 `aistudio香蕉`：上游这次没有返回图片（不一定是内容违规）；或者提示词是 `hi`、`test` 这类无意义的探测文本。	重试一般就能出图；连续失败再调整提示词或参考图。
408	生成超时；`adobe香蕉` 上游限流、繁忙时也返回 408。	退避后重试。
429 / 502 / 503	上游限流或暂时不可用。	退避后重试。

408 / 429 / 502 / 503 通常是瞬时的，客户端退避重试即可，换个时间点一般就过。

十一、限制速查

项	`aistudio香蕉`	`adobe香蕉`
模型	`gemini-3-pro-image`、`gemini-3.1-flash-image`、`gemini-nano-banana-2.1`	`gemini-3-pro-image`、`gemini-3.1-flash-image`
参考图数量	≤ 14	≤ 14
单张参考图大小	≤ 20 MB（超过会先自动压缩）	≤ 20 MB
`imageSize`	`1K` / `2K` / `4K`（默认 `1K`）	`1K` / `2K` / `4K`（默认 `2K`）
`aspectRatio`	通用 10 种；2.1 另支持 `1:4` `4:1` `1:8` `8:1`	通用 10 种 + `1:4` `4:1` `1:8` `8:1`
`thinkingLevel`	支持	不支持（忽略）
每次出图张数	1	1

Gemini 香蕉生图文档 ​

接入线路 ​

两个分组的区别 ​

一、接口概览 ​

二、鉴权方式 ​

三、查看模型列表 ​

四、支持的模型 ​

五、请求体结构 ​

思考档位（仅 aistudio香蕉） ​

六、文生图请求示例 ​

七、响应结构和图片保存 ​

八、图生图 / 改图 ​

九、同步生成，不推荐流生成 ​

十、错误格式 ​

十一、限制速查 ​

Gemini 香蕉生图文档

接入线路

两个分组的区别

一、接口概览

二、鉴权方式

三、查看模型列表

四、支持的模型

五、请求体结构

思考档位（仅 aistudio香蕉）

六、文生图请求示例

七、响应结构和图片保存

八、图生图 / 改图

九、同步生成，不推荐流生成

十、错误格式

十一、限制速查