Gemini 图片生成指南

本文说明如何通过 FriModel 调用 Gemini 图片模型，涵盖文生图和图片编辑。示例已使用 gemini-3.1-flash-image-preview 实际验证。

1. 基础信息

API 地址：https://api.pinniq.org

请求方法：POST

接口路径：/v1beta/models/{model}:generateContent

鉴权请求头：x-goog-api-key: YOUR_API_KEY

Content-Type：application/json

推荐先使用：

gemini-3.1-flash-image-preview

可用模型可能随平台配置变化，建议先调用 GET /v1beta/models 查询当前列表。

Gemini 图片模型不是独立的「编辑」接口：文生图和图片编辑都调用 generateContent。编辑时，把待编辑图片和编辑指令一起放入 contents[].parts[] 即可。

2. 最小请求

3. 图片编辑

单图编辑请求

图片须以 Base64 放在 inlineData 中；mimeType 必须与原文件的真实格式一致。编辑指令应具体说明要保留的主体、要修改的区域/对象，以及期望的风格、构图或文字。

text 和 inlineData 的先后顺序通常不影响调用，但推荐先放编辑指令、再放图片，便于阅读和排查。请勿把图片 URL 直接填入 text；该接口需要传入图片二进制的 Base64（或使用平台支持的文件上传/文件引用方式）。

多图参考、合成与多轮编辑

可在同一个 parts 中放入多张 inlineData，并在提示词中明确它们的身份，例如“以第一张图的人物为主体，使用第二张图的服装材质”。

若有多张图片，建议为每张图片指定编号、角色和不可改变的元素；避免只写“合成这两张图”。

连续编辑时，将上一轮响应中的 candidates[0].content 连同下一条用户编辑指令作为新的 contents 传回，可保留本轮上下文。生产环境也可每轮只提交最新图片和完整编辑要求，以控制请求体大小。

图片模型会重新生成结果，不能保证像素级局部替换。涉及人物身份、文字、Logo 或产品结构时，应在提示词中明确“保持不变”，并检查输出。

示例：两图合成的 parts 结构（data 均为对应图片的 Base64）。

[
  {"text": "以第一张图的人物为主体，穿上第二张图中的夹克；保留人物面部特征和第一张图的姿势。"},
  {"inlineData": {"mimeType": "image/png", "data": "BASE64_OF_SUBJECT"}},
  {"inlineData": {"mimeType": "image/jpeg", "data": "BASE64_OF_JACKET"}}
]

4. 请求参数

路径参数

参数	必填	说明
`model`	是	Gemini 图片模型名称

请求头

参数	必填	说明
`Content-Type`	是	固定为 `application/json`
`x-goog-api-key`	是	FriModel API Key

请求体

参数	必填	说明
`contents`	是	输入内容列表
`contents[].role`	建议	通常填写 `user`
`contents[].parts[].text`	文生图时是；编辑时建议	生成或编辑指令。编辑时写清保留项、修改项和限制条件
`contents[].parts[].inlineData.mimeType`	图片编辑时是	输入图片 MIME 类型，如 `image/png`、`image/jpeg`、`image/webp`
`contents[].parts[].inlineData.data`	图片编辑时是	输入图片的无 Data URL 前缀的 Base64 字符串
`generationConfig.responseModalities`	是	必须包含 `IMAGE`；只需图片时使用 `["IMAGE"]`，需要模型文字说明时使用 `["TEXT", "IMAGE"]`
`generationConfig.imageConfig.aspectRatio`	否	输出宽高比，如 `1:1`、`16:9`、`9:16`；未传时由模型使用默认值
`generationConfig.imageConfig.imageSize`	否	输出分辨率档位，如 `1K`、`2K`。是否支持及可选档位取决于模型；不支持时删除该字段或改用该模型支持的值

图片参数位于 generationConfig.imageConfig，不是 responseFormat.image。不同 Gemini 图片模型对宽高比、分辨率、输入图片数量和文件大小的支持范围可能不同；上线前请以 GET /v1beta/models 的模型能力及实际调用结果为准。

5. 响应读取

生成内容位于：

candidates[0].content.parts[]

图片 part 的结构：

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

inlineData.data：Base64 图片内容

inlineData.mimeType：实际图片格式

文本说明可能出现在其他 part 的 text 字段

实际测试结果：

HTTP 状态码：200

本次复测返回 MIME：image/png；实际格式以 inlineData.mimeType 为准

请求：1:1、1K

实际图片：1024x1024

保存文件时应根据 mimeType 选择扩展名，不要固定写成 PNG。

6. Python 示例

下面是单图编辑的完整示例；与文生图相比，核心差异是向 parts 追加原图的 inlineData。

7. 常见问题

编辑结果与原图差异过大

在指令中分开写“必须保留”和“仅修改”的内容。例如：保持人物脸部、发型、姿势、衣服版型不变；仅将背景替换为海边日落。 对局部修改，可增加区域描述（如“仅替换左上角天空”）。

图片编辑请求返回 400

重点检查：inlineData.data 是否为纯 Base64（不要包含 data:image/png;base64, 前缀）、mimeType 是否与文件真实格式一致、JSON 是否因未转义换行或引号而无效，以及模型是否支持图片输入。Shell 示例中的 Base64 必须压成单行。

想让模型只做局部精确修改

Gemini 的自然语言编辑为生成式编辑，并非像素级蒙版 API。可提供带有圈选/标注的参考图，并在指令中说明标注含义；若业务必须保证精确边界，应在生成后用传统图像处理或专用蒙版编辑能力完成最后一步。

没有返回图片

确认 responseModalities 中包含 IMAGE，并检查所有 parts[]，不要只读取第一个 part。

401 或 403

检查 x-goog-api-key 是否填写正确，以及 Key 是否有对应模型权限。

404

检查 URL 是否为：

/v1beta/models/{model}:generateContent

并通过 GET /v1beta/models 确认模型名称。

429 或 5xx

通常表示限流、上游繁忙或临时服务异常。建议按 2 秒、5 秒、10 秒进行有限次数的退避重试。

Base64 很大

这是正常现象。生产环境建议解码后上传到对象存储，只在业务响应中返回文件 URL，不要长期保存完整 Base64 字符串。

Gemini 图片生成指南

1. 基础信息#

2. 最小请求#

3. 图片编辑#

单图编辑请求#

多图参考、合成与多轮编辑#

4. 请求参数#

路径参数#

请求头#

请求体#

5. 响应读取#

6. Python 示例#

7. 常见问题#

编辑结果与原图差异过大#

图片编辑请求返回 400#

想让模型只做局部精确修改#

没有返回图片#

401 或 403#

404#

429 或 5xx#

Base64 很大#