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)

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)

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)。