Gemini 图片模型接入说明

本文档说明当前项目中两个 https://wellapi.cc 特价渠道对应的大模型、请求参数、请求示例、返回值结构和返回值示例，方便其他系统直接接入。

1. 模型

模型	调用模型名称	接口地址
nano banana pro	`gemini-3-pro-image-preview`	`https://wellapi.cc/v1beta/models/gemini-3-pro-image-preview:generateContent`
nano banana 2	`gemini-3.1-flash-image-preview`	`https://wellapi.cc/v1beta/models/gemini-3.1-flash-image-preview:generateContent`

注意：两个渠道都走 Gemini 风格的同步 generateContent 接口，返回结果中通常包含图片 base64 数据，也可能由部分上游返回图片 URL。

2. 公共请求说明

2.1 请求方式

2.2 鉴权

当前后端同时传递两种鉴权形式，以兼容不同网关：

Query 参数：key={API_KEY}

Header：Authorization: Bearer {API_KEY}

实际接入时建议两者都带上。

2.3 公共请求体结构

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "图片生成提示词"
        },
        {
          "inline_data": {
            "mime_type": "image/png",
            "data": "参考图 base64，不包含 data:image/png;base64, 前缀"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "1K"
    }
  }
}

2.4 入参字段说明

字段	类型	是否必填	说明	示例
`contents`	array	是	对话内容数组。当前项目固定传 1 个 `user` 内容。	见上方 JSON
`contents[].role`	string	是	角色，固定为 `user`。	`user`
`contents[].parts`	array	是	内容片段数组，至少包含一个文本提示词。可追加参考图。	见上方 JSON
`parts[].text`	string	是	生成图片的文本提示词。	`一只橘猫坐在赛博朋克城市霓虹灯下，电影感`
`parts[].inline_data`	object	否	参考图。文生图可不传；图生图/参考图生成时传。	`{ "mime_type": "image/png", "data": "..." }`
`inline_data.mime_type`	string	传参考图时必填	参考图 MIME 类型。	`image/png`、`image/jpeg`
`inline_data.data`	string	传参考图时必填	参考图 base64 字符串，不要带 `data:image/...;base64,` 前缀。	`iVBORw0KGgo...`
`generationConfig.responseModalities`	array	是	返回模态。当前项目对这两个模型传 `IMAGE`。	`["IMAGE"]`
`generationConfig.imageConfig.aspectRatio`	string	是	图片比例。	`1:1`、`16:9`、`9:16`、`4:3`、`3:4`
`generationConfig.imageConfig.imageSize`	string	是	图片清晰度/尺寸档位。	`1K`、`2K`、`4K`

2.5 支持的常用图片比例

当前前端常用值：

1:1

2:3

3:2

3:4

4:3

4:5

5:4

9:16

16:9

21:9

如果前端选择 Auto，当前项目后端/前端会按 1:1 处理。

2.6 支持的常用 imageSize

1K

2K

4K

nanobanana2还有 512 档位，1K/2K/4K 使用。

3. 模型一：gemini-3-pro-image-preview

3.1 渠道信息

项	值
模型名称	`gemini-3-pro-image-preview`
Base URL	https://wellapi.cc
Path	`/v1beta/models/gemini-3-pro-image-preview:generateContent`
完整接口	`https://wellapi.cc/v1beta/models/gemini-3-pro-image-preview:generateContent?key={API_KEY}`

3.2 文生图请求示例

3.3 带参考图请求示例

4. 模型二：gemini-3.1-flash-image-preview

4.1 渠道信息

项	值
模型名称	`gemini-3.1-flash-image-preview`
Base URL	https://wellapi.cc
Path	`/v1beta/models/gemini-3.1-flash-image-preview:generateContent`
完整接口	`https://wellapi.cc/v1beta/models/gemini-3.1-flash-image-preview:generateContent?key={API_KEY}`

4.2 文生图请求示例

4.3 带参考图请求示例

5. 返回值说明

5.1 常见成功返回结构：base64 图片

上游常见返回是 Gemini candidates 结构，图片可能使用 snake_case：inline_data.mime_type，也可能使用 camelCase：inlineData.mimeType。

snake_case 示例：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inline_data": {
              "mime_type": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 128,
    "candidatesTokenCount": 32,
    "totalTokenCount": 160
  }
}

camelCase 示例：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

字段说明：

字段	类型	说明
`candidates`	array	候选结果数组。通常取第一个候选。
`candidates[].content.parts`	array	模型返回的内容片段。图片数据通常在其中一个 part 内。
`inline_data.mime_type` / `inlineData.mimeType`	string	图片 MIME 类型，如 `image/png`。
`inline_data.data` / `inlineData.data`	string	图片 base64 字符串。保存图片时需要先 base64 decode。
`finishReason`	string	生成结束原因。成功通常是 `STOP`。
`usageMetadata`	object	用量信息。不同上游可能不返回或字段不同。

5.2 可能的 URL 图片返回结构

部分上游可能直接返回图片 URL。当前项目后端也兼容这种结构：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://example-cdn.com/generated/image.png"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

字段说明：

字段	类型	说明
`type`	string	当值为 `image` 时表示图片内容。
`source.type`	string	当值为 `url` 时表示图片以 URL 形式返回。
`source.url`	string	生成后的图片地址。

5.3 接入方建议的返回解析逻辑

解析 JSON 根对象。

递归遍历所有对象和数组。

优先查找 inline_data.data + inline_data.mime_type。

同时兼容 inlineData.data + inlineData.mimeType。

如果 data 看起来是 http:// 或 https:// 开头，则按图片 URL 处理。

如果存在 { "type": "image", "source": { "type": "url", "url": "..." } }，也按图片 URL 处理。

如果没有找到图片数据，应记录完整返回体用于排查。

6. 错误返回示例

不同网关错误结构可能不同，常见格式如下：

{
  "error": {
    "code": 400,
    "message": "Invalid request body",
    "status": "INVALID_ARGUMENT"
  }
}
{
  "error": {
    "code": 401,
    "message": "API key not valid",
    "status": "UNAUTHENTICATED"
  }
}

常见 HTTP 状态码：

状态码	含义	建议处理
`400`	请求体格式错误或参数不支持	检查 JSON 结构、`aspectRatio`、`imageSize`、base64 是否正确。
`401` / `403`	API Key 错误或无权限	检查 `key` 和 `Authorization`。
`429`	请求过多或额度限制	做退避重试，或降低并发。
`500` / `502` / `503`	上游服务异常	做短暂重试，仍失败则提示用户稍后再试。
超时	生成耗时过长或参考图过大	减少参考图数量/大小，降低 `imageSize`，增大客户端超时时间。

7. 接入注意事项

不要在日志、前端代码或公开文档中暴露真实 API Key。

参考图 base64 不要带 data:image/png;base64, 前缀，只传纯 base64 字符串。

参考图建议控制数量和大小；图片越多、越大，越容易触发超时或响应体过大。

imageSize=4K 生成时间和返回体积通常明显更大，客户端需要设置更长超时时间。

当前项目对 tejia2 设置了较长超时和少量 IO 重试；外部系统接入时建议也做超时、429/5xx 重试和失败提示。

返回图片可能是 base64，也可能是 URL，接入方应同时兼容。

Nano Banana Pro及Nano banana 2 API文档（图片base64返回）

Gemini 图片模型接入说明

1. 模型

2. 公共请求说明

2.1 请求方式

2.2 鉴权

2.3 公共请求体结构

2.4 入参字段说明

2.5 支持的常用图片比例

2.6 支持的常用 imageSize

3. 模型一：gemini-3-pro-image-preview

3.1 渠道信息

3.2 文生图请求示例

3.3 带参考图请求示例

4. 模型二：gemini-3.1-flash-image-preview

4.1 渠道信息

4.2 文生图请求示例

4.3 带参考图请求示例

5. 返回值说明

5.1 常见成功返回结构：base64 图片

5.2 可能的 URL 图片返回结构

5.3 接入方建议的返回解析逻辑

6. 错误返回示例

7. 接入注意事项

8. 最小接入伪代码

Nano Banana Pro及Nano banana 2 API文档（图片base64返回）

Gemini 图片模型接入说明#

1. 模型#

2. 公共请求说明#

2.1 请求方式#

2.2 鉴权#

2.3 公共请求体结构#

2.4 入参字段说明#

2.5 支持的常用图片比例#

2.6 支持的常用 imageSize#

3. 模型一：gemini-3-pro-image-preview#

3.1 渠道信息#

3.2 文生图请求示例#

3.3 带参考图请求示例#

4. 模型二：gemini-3.1-flash-image-preview#

4.1 渠道信息#

4.2 文生图请求示例#

4.3 带参考图请求示例#

5. 返回值说明#

5.1 常见成功返回结构：base64 图片#

5.2 可能的 URL 图片返回结构#

5.3 接入方建议的返回解析逻辑#

6. 错误返回示例#

7. 接入注意事项#

8. 最小接入伪代码#

Gemini 图片模型接入说明

1. 模型

2. 公共请求说明

2.1 请求方式

2.2 鉴权

2.3 公共请求体结构

2.4 入参字段说明

2.5 支持的常用图片比例

2.6 支持的常用 imageSize

3. 模型一：gemini-3-pro-image-preview

3.1 渠道信息

3.2 文生图请求示例

3.3 带参考图请求示例

4. 模型二：gemini-3.1-flash-image-preview

4.1 渠道信息

4.2 文生图请求示例

4.3 带参考图请求示例

5. 返回值说明

5.1 常见成功返回结构：base64 图片

5.2 可能的 URL 图片返回结构

5.3 接入方建议的返回解析逻辑

6. 错误返回示例

7. 接入注意事项

8. 最小接入伪代码