Banana 图像模型接入文档

本文档适用于 Token5U 站点提供的三个 Banana / Gemini 图像生成模型：

模型名称	模型 ID
Nano Banana	`gemini-2.5-flash-image`
Nano Banana 2	`gemini-3.1-flash-image-preview`
Nano Banana Pro	`gemini-3-pro-image-preview`

这三个模型均通过统一 Gemini generateContent 兼容接口接入，适用于文生图、图生图、图像编辑、多参考图融合、角色一致性、商品图、海报和设计稿等场景。

1. 基本信息

项目	说明
接口类型	Gemini `generateContent` 兼容接口
默认服务地址	`https://api.token5u.cn`
API 版本	`v1beta`
鉴权方式	`Authorization: Bearer YOUR_API_KEY`
环境变量建议	`TOKEN5U_API_KEY`

调用路径

三个模型的完整请求地址：

https://api.token5u.cn/v1beta/models/gemini-2.5-flash-image:generateContent
https://api.token5u.cn/v1beta/models/gemini-3.1-flash-image-preview:generateContent
https://api.token5u.cn/v1beta/models/gemini-3-pro-image-preview:generateContent

请求头

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

2. 模型差异

模型 ID	版本状态	主要能力	推荐场景
`gemini-2.5-flash-image`	Stable / Preview 状态以当前上游为准	文生图、图生图、图像编辑、角色一致性、图像和文本混合响应	低延迟出图、轻量编辑、商品图处理、角色一致性
`gemini-3.1-flash-image-preview`	Preview	文生图、图生图、图像编辑、多参考图组合、文本和图像混合响应	快速创意出图、角色/商品一致性、社媒素材、海报草图、批量提示词验证
`gemini-3-pro-image-preview`	Preview	文生图、图生图、图像编辑、复杂指令遵循、文本渲染、图像和文本混合响应	复杂构图、精细文字、产品图、设计稿和高质量成图

3. 入参规范

请求体

{
  "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"
    }
  }
}

顶层参数

参数	类型	必填	说明
`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`。

response_format 说明：

默认或传 b64_json 时，图片会以官方原生 inlineData 形态返回。

传 url 时，网关会把图片上传到对象存储，并以 fileData.fileUri 形态返回。

该字段会在转发到上游前剥离，不会污染上游 Gemini 请求。

4. Content 与 Part

Content

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

Part

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

inlineData 示例：

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

fileData 示例：

{
  "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"
  }
}

5. 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`	否	上游默认值	图片尺寸。`gemini-2.5-flash-image` 建议先省略；3.x 模型常用 `1K`、`2K`、`4K`。不支持时会返回参数错误。

6. 出参规范

成功响应为 GenerateContentResponse：

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

Candidate 常用字段：

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

当请求 response_format=url 时，每个图片 Part 形如：

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

未指定或为 b64_json 时，维持官方 inlineData 形态。

7. 接入代码示例

下面示例默认使用 gemini-3.1-flash-image-preview。如需切换模型，只要替换 URL 或 SDK 参数中的模型 ID：

gemini-2.5-flash-image
gemini-3.1-flash-image-preview
gemini-3-pro-image-preview

Banana 生图

Banana 图像模型接入文档

1. 基本信息

调用路径

请求头

2. 模型差异

3. 入参规范

请求体

顶层参数

4. Content 与 Part

Content

Part

URL 下载限制

5. generationConfig

imageConfig

6. 出参规范

7. 接入代码示例

cURL

cURL：返回图片 URL

cURL：图生图 / 参考图 URL

Banana 生图

Banana 图像模型接入文档#

1. 基本信息#

调用路径#

请求头#

2. 模型差异#

3. 入参规范#

请求体#

顶层参数#

4. Content 与 Part#

Content#

Part#

URL 下载限制#

5. generationConfig#

imageConfig#

6. 出参规范#

7. 接入代码示例#

cURL#

cURL：返回图片 URL#

cURL：图生图 / 参考图 URL#

Banana 图像模型接入文档

1. 基本信息

调用路径

请求头

2. 模型差异

3. 入参规范

请求体

顶层参数

4. Content 与 Part

Content

Part

URL 下载限制

5. generationConfig

imageConfig

6. 出参规范

7. 接入代码示例

cURL

cURL：返回图片 URL

cURL：图生图 / 参考图 URL