# Gemini 图像生成

使用 Gemini 图像模型生成图片、传参考图，并读取返回的图片结果。

Gemini 图像模型可以文生图，也可以参考一张或多张图片继续生成。实际接入时先调用 `/v1/models` 确认当前 API Key 可用的模型 ID。

这类模型使用聊天接口：

```http
POST /v1/chat/completions
```

不要提交到：

```http
POST /v1/images/generations
```

`/v1/images/generations` 适合 GPT Image、DALL-E、Imagen，以及明确支持 OpenAI Images 接口的图片模型。Gemini 图像模型的结果会出现在聊天消息里。

## 参数速查

| 参数 | 写法 | 说明 |
|---|---|---|
| `model` | 例如 `gemini-3.1-flash-image-preview` | 模型 ID，以模型列表为准 |
| `messages` | OpenAI Chat 格式 | 文本和参考图都放在消息里 |
| `messages[].content[].type` | `text` / `image_url` | 文本指令和图片输入 |
| `extra_body.google.image_config.aspect_ratio` | `1:1`、`16:9`、`9:16` | 控制画面比例 |

这里不使用 `size` 控制分辨率。标准图片接口里的 `size: "1024x1024"`、`1536x1024` 这类写法，不适用于 Gemini 图像模型的聊天接口场景。

## 模型 ID

常见 Gemini 图像模型可以按下面理解：

| 产品名 | 推荐模型 ID | 说明 |
|---|---|---|
| Nano Banana | `gemini-2.5-flash-image` | 适合快速图像生成与编辑 |
| Nano Banana 旧预览 | `gemini-2.5-flash-image-preview` | 旧预览 ID，优先使用非 preview 版本 |
| Nano Banana Pro / Gemini 3 Pro Image | `gemini-3-pro-image-preview` | 适合更高质量的图像生成与编辑 |
| Gemini 3.1 Flash Image | `gemini-3.1-flash-image-preview` | Flash Image 新版本 |

如果 `/v1/models` 没有返回某个 ID，就不要在业务里写死它。模型可用性以模型列表为准。

## 文生图

```bash
curl https://kaienapi.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {
        "role": "user",
        "content": "生成一张 16:9 的科技产品横版海报，白色背景，画面干净，不要文字"
      }
    ],
    "extra_body": {
      "google": {
        "image_config": {
          "aspect_ratio": "16:9"
        }
      }
    }
  }'
```

## 参考图生成

参考图放在 `messages[].content` 数组中，类型使用 `image_url`。URL 可以是公网 OSS/CDN 地址。

```bash
curl https://kaienapi.com/v1/chat/completions \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "把这张参考图转成干净的 3D 平面插画风格，保留主体轮廓和主要颜色，输出一张 1:1 图片。"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/source.png"
            }
          }
        ]
      }
    ],
    "extra_body": {
      "google": {
        "image_config": {
          "aspect_ratio": "1:1"
        }
      }
    }
  }'
```

## 多张参考图

多图时继续追加 `image_url` 条目，并在文本里说明每张图的用途。

```json
{
  "model": "gemini-3.1-flash-image-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "参考第一张图的人物和第二张图的配色，生成一张 16:9 横版海报。"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/person.png"
          }
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/style.png"
          }
        }
      ]
    }
  ],
  "extra_body": {
    "google": {
      "image_config": {
        "aspect_ratio": "16:9"
      }
    }
  }
}
```

## base64 参考图

如果图片不方便放公网 URL，也可以把 data URL 放进 `image_url.url`。

```json
{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,AAAA..."
  }
}
```

公网 URL 更适合常规业务接入。base64 请求体更大，多图时更容易遇到请求大小和超时问题。

## 宽高比

宽高比写在：

```json
{
  "extra_body": {
    "google": {
      "image_config": {
        "aspect_ratio": "16:9"
      }
    }
  }
}
```

这里使用 `aspect_ratio`。不要写成 `aspectRatio`。系统会转换成 Gemini 原生接口需要的字段。

常用比例：

| 用途 | `aspect_ratio` |
|---|---|
| 方图、头像、商品主图 | `1:1` |
| 横版海报、封面图 | `16:9` |
| 竖版封面、手机图 | `9:16` |

prompt 里也建议写清楚画幅，例如“16:9 横版海报”或“9:16 手机竖版封面”。这样比只传参数更稳。

## 16:9 实测结果

同样传入 `extra_body.google.image_config.aspect_ratio = "16:9"`，不同模型的表现不完全一样：

| 模型 ID | 纯文生图 16:9 结果 | 说明 |
|---|---|---|
| `gemini-3-pro-image-preview` | `1376x768` | 已验证横图生效 |
| `gemini-3.1-flash-image-preview` | `1376x768` | 已验证横图生效 |
| `gemini-2.5-flash-image` | `1024x1024` | 当前链路仍返回方图，不要承诺 16:9 |
| `gemini-2.5-flash-image-preview` | `1024x1024` | 当前链路仍返回方图，建议优先用非 preview ID |

所以，如果业务强依赖横图输出，优先选择 `gemini-3-pro-image-preview` 或 `gemini-3.1-flash-image-preview`，并在 prompt 中同时写明“16:9 横版”。

带参考图时，模型也可能受原图构图影响。需要严格横图时，建议在生成后检查图片实际宽高；不符合预期时提示用户重试或切换模型。

## 响应结构

响应是 Chat Completions 格式。图片通常在：

```text
choices[0].message.content
```

内容是 Markdown 图片：

```markdown
![image](data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...)
```

示例：

```json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gemini-3.1-flash-image-preview",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "![image](data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...)"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 292,
    "completion_tokens": 1471,
    "total_tokens": 1763
  }
}
```

前端可以直接展示这个 data URL。后端如果要保存结果，提取 `base64,` 后面的内容，解码成图片文件，再上传到自己的对象存储。

## 常见问题

**传了 `size` 但比例没变**

Gemini 图像模型用 `extra_body.google.image_config.aspect_ratio` 控制画幅。不要只传 `size`。

**传了 `aspect_ratio` 但没生效**

先检查字段位置。它必须放在 `extra_body.google.image_config` 下。顶层 `aspect_ratio` 是部分图片接口模型的写法，不适用于这个聊天接口示例。

如果字段位置正确但仍返回方图，检查模型 ID。`gemini-2.5-flash-image` 和 `gemini-2.5-flash-image-preview` 当前不应承诺稳定输出 16:9。

**返回“不支持图片生成接口”**

通常是请求发到了 `/v1/images/generations`。改用 `/v1/chat/completions`。

**响应里没有 `data[0].url` 或 `b64_json`**

这是正常的。Gemini 图像模型走聊天接口，图片在 `choices[0].message.content` 的 Markdown data URL 里。