Nano Banana 2

gemini-3.1-flash-image-preview 是站点提供的 Gemini 图像生成预览模型之一。它通过统一 Gemini 兼容接口接入，适合低延迟图像生成、图像编辑、多参考图融合、角色一致性和商品图生成等场景。模型仍为 preview，请以站点模型配置和上游可用性为准。

1. 模型基本信息

项目	说明
模型 ID	`gemini-3.1-flash-image-preview`
接口类型	Gemini generateContent 兼容接口
版本状态	Preview
主要能力	文生图、图生图、图像编辑、多参考图组合、文本和图像混合响应
推荐场景	快速创意出图、角色/商品一致性、社媒素材、海报草图、批量提示词验证
默认服务地址	主节点：`http://38.76.161.111:3099`

调用路径

POST {BASE_URL}/v1beta/models/gemini-3.1-flash-image-preview:generateContent

示例：

http://38.76.161.111:3099/v1beta/models/gemini-3.1-flash-image-preview:generateContent

请求头

参数	类型	必填	说明
Authorization	string	是	Bearer Token，格式为 `Bearer YOUR_API_KEY`。
Content-Type	string	是	固定为 `application/json`。

2. 入参规范

请求体

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Generate a futuristic cyberpunk city at night with cinematic lighting and ultra-high detail."
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "1K"
    }
  }
}

顶层参数

参数	类型	必填	说明
contents	Content[]	是	请求内容。单轮请求通常只传一条 Content，多轮对话可传历史上下文。
generationConfig	GenerationConfig	否	生成配置。图像生成主要使用 `responseModalities` 和 `imageConfig`。
safetySettings	SafetySetting[]	否	安全过滤配置。每个安全分类最多传一个设置。
systemInstruction	Content	否	系统级指令，适合放全局风格、限制和角色设定。
tools	Tool[]	否	工具列表。普通图像生成通常不需要。
toolConfig	ToolConfig	否	工具调用配置，仅在传入 tools 时使用。
cachedContent	string	否	已缓存上下文名称，格式通常为 `cachedContents/{cachedContent}`。
response_format	string	否	网关扩展参数，非 Gemini 官方字段。控制网关返回图片的形态，可选 `b64_json`、`url`；其他取值会被网关静默归一为 `b64_json`。默认值由渠道配置决定，未配置时使用 `b64_json`(即官方原生 inlineData 形态)。设为 `url` 时网关会把图片上传到对象存储并以 `fileData.fileUri` 形式返回；该字段会在转发到上游前剥离，不会污染上游请求。

Content

参数	类型	必填	说明
role	string	否	内容角色，可为 `user` 或 `model`。单轮请求可省略，建议显式传 `user`。
parts	Part[]	是	内容片段列表。每个 Part 通常使用 `text`、`inlineData` 或 `fileData` 之一。

Part

参数	类型	必填	说明
text	string	否	文本 prompt。文生图时用于描述图像。
inlineData	Blob	否	内联媒体，适合传入参考图或待编辑图片。
fileData	FileData	否	文件 URI 引用，适合引用已上传文件。

inlineData 示例：

{
  "inlineData": {
    "mimeType": "image/png",
    "data": "BASE64_IMAGE_DATA"
  }
}

fileData 示例（传入参考图 URL）：

{
  "fileData": {
    "mimeType": "image/png",
    "fileUri": "https://example.com/reference.png"
  }
}

兼容 snake_case 字段名 file_data / file_uri / mime_type，与 Google 官方 SDK 命名习惯保持一致。

当 fileData.fileUri 是 HTTP/HTTPS URL 时，网关会自动下载图片，base64 编码后转写为 inlineData 再转发给上游 Gemini，方便在不维护本地文件的场景下直接传图片链接。mimeType 可省略，省略时使用响应头 Content-Type。

URL 下载的安全和限制：

项目	规则
协议	仅允许 `http://` 和 `https://`，禁止 `file://`、`ftp://` 等。
SSRF 防护	私有 IP（10/8、172.16/12、192.168/16、127/8、169.254/16）和保留地址会被拒绝。
单图大小上限	20MB，超过会返回 `IMAGE_DOWNLOAD_FAILED` 错误。
单图下载超时	30s。
并发下载	单个请求内最多 5 并发。
允许的 Content-Type	`image/jpeg`、`image/png`、`image/gif`、`image/webp`、`image/bmp`。

任一 URL 下载失败时网关会返回 400 错误，错误信息中会列出失败的具体 URL：

{
  "error": {
    "message": "failed to download 1 image(s): https://example.com/missing.png (HTTP 404)",
    "type": "invalid_request_error",
    "code": "IMAGE_DOWNLOAD_FAILED"
  }
}

generationConfig

参数	类型	必填	说明
responseModalities	string[]	否	图像生成必须包含 `IMAGE`。如需模型同时返回说明文字，可传 `["TEXT", "IMAGE"]`。
imageConfig	ImageConfig	否	图像输出配置。支持范围取决于模型和上游通道。
candidateCount	integer	否	返回候选数量。图像模型通常建议保持默认值。
temperature	number	否	随机性控制，值越高越发散。
topP	number	否	nucleus sampling 阈值。
topK	integer	否	top-k sampling 数量，部分模型不允许设置。
seed	integer	否	随机种子。不保证所有上游模型都支持稳定复现。
maxOutputTokens	integer	否	主要影响文本输出。
responseMimeType	string	否	文本候选 MIME 类型，例如 `text/plain` 或 `application/json`。
responseSchema	object	否	文本 JSON 输出 schema。图像输出场景通常不需要。

imageConfig

参数	类型	必填	默认值	说明
aspectRatio	string	否	模型默认策略	生成图片宽高比。常用值包括 `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`9:16`、`16:9`、`21:9`。部分 3.x 图片模型还可能支持更长比例，最终以模型能力为准。
imageSize	string	否	通常为 `1K`	图片尺寸。常用值为 `1K`、`2K`、`4K`，部分上游可能支持 `512`。不支持时会返回参数错误。

3. 出参规范

成功响应为 GenerateContentResponse：

参数	类型	说明
candidates	Candidate[]	模型候选结果。图片通常在 `candidates[].content.parts[].inlineData`。
promptFeedback	PromptFeedback	prompt 侧安全过滤反馈。
usageMetadata	UsageMetadata	token 和模态使用量统计。
modelVersion	string	实际模型版本，是否返回取决于上游。
responseId	string	响应 ID，便于排查问题。

Candidate 常用字段：

参数	类型	说明
content	Content	生成内容。图片输出在 `content.parts[].inlineData`(默认)或 `content.parts[].fileData`(response_format 为 url 时)。
finishReason	string	结束原因，如 `STOP`、`MAX_TOKENS`、`SAFETY`、`IMAGE_SAFETY`、`NO_IMAGE`。
safetyRatings	SafetyRating[]	输出内容安全评级。
finishMessage	string	结束原因补充说明。

当请求 response_format=url 时，每个图片 Part 形如 {"fileData": {"fileUri": "<对象存储 URL>", "mimeType": "image/png"}}；未指定或为 b64_json 时维持官方 inlineData 形态。

图片保存逻辑：

4. 接入代码示例

cURL

TypeScript

Python

Go

Java

5. 常见错误码

错误响应格式：

{
  "error": {
    "code": 401,
    "message": "API key is missing. Please provide a valid API key.",
    "status": "UNAUTHENTICATED"
  }
}

HTTP 状态码	status	常见原因	处理建议
400	INVALID_ARGUMENT	JSON 格式错误、contents 为空、imageConfig 取值不被模型支持。	检查请求体，先使用最小请求体验证。
401	UNAUTHENTICATED	未传 API Key、Key 无效或已过期。	检查 `Authorization: Bearer YOUR_API_KEY`。
403	PERMISSION_DENIED	Token 被禁用、用户无权限、分组未授权该模型。	检查账号、Token、用户分组和模型授权。
404	NOT_FOUND	模型 ID 不存在或站点未启用该模型。	确认模型 ID 为 `gemini-3.1-flash-image-preview`。
429	RESOURCE_EXHAUSTED	触发限流、额度不足或余额不足。	降低并发，检查额度和余额。
500	INTERNAL	网关内部错误或响应编码异常。	稍后重试，保留 `responseId` 或请求时间用于排查。
503	UNAVAILABLE	没有可用上游通道或上游临时不可用。	稍后重试，或在后台检查通道健康状态。

Nano banana 2 API 文档（加速版）

Nano Banana 2#

1. 模型基本信息#

调用路径#

请求头#

2. 入参规范#

请求体#

顶层参数#

Content#

Part#

generationConfig#

imageConfig#

3. 出参规范#

4. 接入代码示例#

cURL#

TypeScript#

Python#

Go#

Java#

5. 常见错误码#