docs/gemini-3-image-guide.md

# Gemini 3 Pro Image 模型调用指南

本文档详细说明了在 **Antigravity** 项目中调用 Google `gemini-3-pro-image` (Imagen 3) 模型的方法。本项目已对该模型进行了 OpenAI 协议的完全兼容封装，并扩展支持了原生的摄影宽高比、人物生成安全策略，以及**图生图 (Image-to-Image)** 功能。

## 1. 基础信息

*   **模型 ID**: `gemini-3-pro-image` (支持别名 `gemini-3-pro-image-preview`)
*   **接口路径**:
    *   `/v1/images/generations` (文生图 Text-to-Image)
    *   `/v1/images/edits` (图生图 Image-to-Image / 编辑)
    *   `/v1/chat/completions` (兼容模式)
*   **底层模型**: Google Imagen 3 (Gemini Native)

---

## 2. 文生图 (Text-to-Image)

调用 `/v1/images/generations`，支持以下参数：

### 2.1 画幅与宽高比 (Size / Aspect Ratio)

`size` 参数支持两种输入格式，系统会自动解析并映射到 Gemini 支持的标准比例：

1.  **直接输入比例 (推荐)**：如 `"16:9"`, `"4:3"`, `"1:1"`。这种方式最直观，且 100% 准确映射。
2.  **输入分辨率 (兼容)**：如 `"1920x1080"`, `"1024x1024"`。系统会自动计算其宽高比（例如 1920/1080 ≈ 1.77），并将其归一化为最接近的标准比例（16:9）。

**⚠️ 重要说明**：Gemini (Imagen 3) **不支持自定义任意像素大小**。
无论您在 `size` 中输入 `"1920x1080"` 还是 `"16:9"`，最终生成的**实际物理分辨率**仅由以下两个因素决定：
1.  **宽高比**（由 `size` 解析得出）
2.  **画质等级**（由 `quality` 参数决定：`1k`/`2k`/`4k`）

*示例：输入 `size: "1920x1080"` (16:9) 且 `quality: "standard"` (1k)，实际生成的图片尺寸为 **1376x768** (16:9 下的 1K 分辨率)，而不是 1920x1080。*

| 目标比例 | 适用场景 | `size` 参数示例 (分辨率) | 备注 |
| :--- | :--- | :--- | :--- |
| **16:9** | 宽屏、电影感 | `1920x1080`, `1280x720` | 标准宽屏 |
| **9:16** | 手机壁纸、Stories | `1080x1920`, `720x1280` | 竖屏全屏 |
| **1:1** | 头像、Instagram | `1024x1024` | 默认比例 |
| **4:3** | 传统摄影、显示器 | `1024x768`, `800x600` | |
| **3:4** | 纵向摄影 | `768x1024`, `600x800` | |
| **21:9** | 超宽屏、电影 | `2560x1080` | 电影银幕 |
| **3:2** | **[新增]** 全画幅单反 | `1500x1000` | 经典摄影比例 |
| **2:3** | **[新增]** 竖构图摄影 | `1000x1500` | 海报、立绘 |
| **5:4** | **[新增]** 大画幅 | `1280x1024` | 艺术摄影 |
| **4:5** | **[新增]** 社交媒体竖图 | `1024x1280` | Ins 最佳展示比例 |

> **提示**: 您不需要精确匹配像素值，只需宽高比接近上述比例（容差 0.05）即可自动识别。

### 2.2 画质与分辨率 (Quality)

通过 `quality` 参数控制生成的精细度。

| 参数值 (`quality`) | 对应 Gemini 设置 | 说明 |
| :--- | :--- | :--- |
| `standard` / `1k` | Image Size: `1K` | 生成速度快，适合快速验证 (默认) |
| `medium` / `2k` | Image Size: `2K` | 平衡质量与速度 |
| `hd` / `4k` | Image Size: `4K` | **极高画质**，细节最丰富，耗时稍长 |

#### 分辨率对照表 (Gemini 3 Pro Image)

| 宽高比 | 1K 分辨率 (Standard) | 2K 分辨率 (Medium) | 4K 分辨率 (HD) |
| :--- | :--- | :--- | :--- |
| **1:1** | 1024x1024 | 2048x2048 | 4096x4096 |
| **2:3** | 848x1264 | 1696x2528 | 3392x5056 |
| **3:2** | 1264x848 | 2528x1696 | 5056x3392 |
| **3:4** | 896x1200 | 1792x2400 | 3584x4800 |
| **4:3** | 1200x896 | 2400x1792 | 4800x3584 |
| **4:5** | 928x1152 | 1856x2304 | 3712x4608 |
| **5:4** | 1152x928 | 2304x1856 | 4608x3712 |
| **9:16** | 768x1376 | 1536x2752 | 3072x5504 |
| **16:9** | 1376x768 | 2752x1536 | 5504x3072 |
| **21:9** | 1584x672 | 3168x1344 | 6336x2688 |

### 调用示例 (Python)

```python
import requests

url = "http://localhost:8045/v1/images/generations"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}
data = {
    "model": "gemini-3-pro-image",
    "prompt": "A futuristic city with flying cars, cinematic lighting, 8k",
    "size": "16:9",
    "quality": "hd",
    "n": 1
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

## 3. 图生图 (Image-to-Image / Edits) 🔥 [新增]

调用 `/v1/images/edits` 接口，支持通过参考图生成。

*   **Content-Type**: `multipart/form-data`
*   **支持多图**: 可同时上传多张参考图。

### 表单字段说明

| 字段名 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `prompt` | String | 是 | 文本提示词 |
| `image1`...`imageN` | File | 是 | **参考图文件**。支持 `image1`, `image2` 等任意名称的文件字段 (非 standard `image` 或 `mask`)。 |
| `image` | File | 否 | (兼容 OpenAI 标准) 主图像 |
| `mask` | File | 否 | (兼容 OpenAI 标准) 遮罩图像 |
| `aspect_ratio` | String | 否 | 显式指定比例，如 `"16:9"` (优先级高于 `size`) |
| `image_size` | String | 否 | 显式指定分辨率，如 `"2K"`, `"4K"` (优先级高于 `quality`) |
| `style` | String | 否 | 风格描述，会自动追加到 Prompt 中 |
| `n` | Integer | 否 | 生成数量 (默认 1) |
| `model` | String | 否 | 模型名称 (默认 `gemini-3-pro-image`) |

### 调用示例 (Python)

```python
import requests

url = "http://localhost:8045/v1/images/edits"
headers = {
    "Authorization": "Bearer <token>"
}
# 支持多张参考图 (image1, image2, ...)
files = {
    "image1": open("/path/to/reference_1.jpg", "rb"),
    "image2": open("/path/to/reference_2.jpg", "rb")
}
data = {
    "prompt": "A cyberpunk city street based on this layout",
    "aspect_ratio": "16:9",
    "image_size": "4K",
    "style": "watercolor"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```

---

## 4. 后缀魔法 (Magic Suffix)

除了标准的 JSON 参数外，本项目还支持在 **模型名称** 中直接指定参数（方便在不支持自定义参数的客户端中使用）。

**格式**: `gemini-3-pro-image-{比例}-{画质}`

*   **比例后缀**: `-16x9`, `-9x16`, `-4x3`, `-3x4`, `-3x2`, `-2x3` 等。
*   **画质后缀**: `-4k` (对应 hd), `-2k` (对应 medium)。

**示例**:
使用模型名 `gemini-3-pro-image-16x9-4k` 等同于：
*   `size`: "1920x1080" (16:9)
*   `quality`: "hd"

> **注意**: 如果 JSON Body 中显式传递了 `size` 或 `quality`，Body 中的参数优先级 **高于** 模型名后缀。

---

## 5. 常见问题

1.  **Q: 为什么我设置了 `size: "1234x5678"` 但生成的图片比例不对？**
    *   **A**: 系统会将您输入的尺寸归一化为 Gemini 支持的 10 种标准比例（见 2.1 节）。如果您的比例非常特殊且不匹配任何标准比例（容差 > 0.05），系统将回退到默认的 **1:1**。建议直接使用示例中的分辨率。

2.  **Q: 支持一次生成多张图片吗？**
    *   **A**: 支持。虽然 Gemini 上游单次请求限制生成 1 张，但 Antigravity 代理层会自动并发处理 `n` 参数。例如设置 `n: 4`，系统会并行发起 4 个请求并合并结果返回。

3.  **Q: `person_generation` 参数报错？**
    *   **A**: 请确保该参数位于 JSON 的**根层级**（与 `prompt`, `model` 同级），而不是嵌套在其他字段中。支持 `snake_case` (`person_generation`) 和 `camelCase` (`personGeneration`)。