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 接口，返回结果中图片以 URL 形式直接出现在 parts[].text 字段中，而非 base64 数据。

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

nano banana 2 还有 512 档位，nano banana pro 仅支持 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`

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`

4.2 文生图请求示例

4.3 带参考图请求示例

5. 返回值说明

⚠️ 重要：两个模型的实际返回结构与标准 Gemini inline_data 结构不同。图片 URL 直接以纯文本形式出现在 candidates[0].content.parts[0].text 字段中，而非 base64 或 source.url 嵌套结构。接入方须以此为准进行解析。

5.1 gemini-3-pro-image-preview 返回示例

图片 URL 为带鉴权 token 的临时链接（abd.wellapi.xin 域名），有效期有限，请及时下载或转存。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "https://abd.wellapi.xin/api/generations/3cfb9eeb-b1af-4376-970d-5e1a7c224744/image?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJwb3NlIjoib3BlbmFwaS1nZW5lcmF0aW9uLWltYWdlIiwiZ2VuZXJhdGlvbklkIjoiM2NmYjllZWItYjFhZi00Mzc2LTk3MGQtNWUxYTdjMjI0NzQ0IiwiYWN0b3JJZCI6ImNtcTdtc2llajA2NHh6NDl4a3ZhcGZla20iLCJhY3RvclR5cGUiOiJhcGlLZXkiLCJpYXQiOjE3ODI4MzM5MzUsImV4cCI6MTc4Mjg0MTEzNX0.XWFfq9rUase1NFVqW27wshxNKuA5WjfbzH6oRuUINO4"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "modelVersion": "Nano_Banana_Pro",
  "usageMetadata": {
    "promptTokenCount": 96,
    "candidatesTokenCount": 1548,
    "totalTokenCount": 1644
  }
}

text字段的值为图片的url。

5.2 gemini-3.1-flash-image-preview 返回示例

图片 URL 为公开 CDN 静态链接（file1.aitohumanize.com 域名），可直接访问。

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "https://file1.aitohumanize.com/file/52032f4491534bbca42ebef18ddd1ae5.png"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "modelVersion": "gemini-3.1-flash-image-preview",
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 11145,
    "totalTokenCount": 11161
  }
}

text字段的值为图片的url。

5.3 返回字段说明

字段	类型	说明
`candidates`	array	候选结果数组，通常取第一个（`index: 0`）。
`candidates[0].content.role`	string	固定为 `model`。
`candidates[0].content.parts`	array	模型返回的内容片段数组。
`candidates[0].content.parts[0].text`	string	图片 URL，直接为可访问的 HTTP(S) 地址。
`candidates[0].finishReason`	string	生成结束原因，成功时为 `STOP`。
`candidates[0].index`	number	候选结果索引，固定为 `0`。
`modelVersion`	string	实际调用的模型版本标识。pro 渠道返回 `Nano_Banana_Pro`，flash 渠道返回 `gemini-3.1-flash-image-preview`。
`usageMetadata.promptTokenCount`	number	输入 token 数。
`usageMetadata.candidatesTokenCount`	number	输出 token 数（图片计费单位）。
`usageMetadata.totalTokenCount`	number	总 token 数。

5.4 两个模型返回 URL 差异对比

模型	图片 URL 域名	URL 类型	注意事项
`gemini-3-pro-image-preview`	`abd.lingting.xin`	带 JWT token 的临时鉴权链接	有过期时间，需在有效期内下载或转存，不可长期引用
`gemini-3.1-flash-image-preview`	`file1.aitohumanize.com`	公开 CDN 静态链接	可直接访问，稳定性依赖上游 CDN

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

1. 解析 JSON 根对象。
2. 取 candidates[0].content.parts[0].text。
3. 判断该字段值是否以 http:// 或 https:// 开头。
   - 是 → 即为图片 URL，直接使用或转存。
   - 否 → 记录完整返回体，上报异常。
4. 对 gemini-3-pro-image-preview 返回的 URL，建议立即下载/转存，
   避免 JWT token 过期后无法访问。

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 生成时间通常明显更长，客户端需要设置更长超时时间。

gemini-3-pro-image-preview 返回的图片 URL 携带 JWT token，存在过期时间，务必在获取后立即下载或转存到自有存储，不可将该 URL 直接持久化或长期展示。

gemini-3.1-flash-image-preview 返回的是公开 CDN 链接，可直接使用，但稳定性依赖上游，生产环境建议同样转存。

Nano Banana Pro 及 Nano Banana 2 API 文档

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 gemini-3-pro-image-preview 返回示例

5.2 gemini-3.1-flash-image-preview 返回示例

5.3 返回字段说明

5.4 两个模型返回 URL 差异对比

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

6. 错误返回示例

7. 接入注意事项

8. 最小接入伪代码

Nano Banana Pro 及 Nano Banana 2 API 文档

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 gemini-3-pro-image-preview 返回示例#

5.2 gemini-3.1-flash-image-preview 返回示例#

5.3 返回字段说明#

5.4 两个模型返回 URL 差异对比#

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

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 gemini-3-pro-image-preview 返回示例

5.2 gemini-3.1-flash-image-preview 返回示例

5.3 返回字段说明

5.4 两个模型返回 URL 差异对比

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

6. 错误返回示例

7. 接入注意事项

8. 最小接入伪代码