Gemini API媒体分辨率配置指南：高分辨率图片与视觉识别优化
使用Gemini API处理产品白底图、财报截图或UI界面分析时，图像上传后常出现文字识别错漏、图表细节丢失、关键像素被模糊化。根因并非模型能力不足，而是媒体分辨率配置未对齐模型上限。简言之，将超高分辨率显示器截图丢给基础版模型，预处理阶段强制压缩，导致细节像素不可逆损失。
确认所用模型的原生分辨率上限
基础判断点：gemini-pro-vision默认处理3072×3072像素内容；gemini-ultra-vision开放至4096×4096。用5120×2880截图调用前者，模型会强制缩放裁切，原始像素信息永久丢失。操作上，打开Google AI Studio，进入「Model Explorer」，选中模型后查看「Input capabilities」栏的「Max image resolution」——以官方实时标注为准，忽略过时文档。API调用时模型名需明确，例如model = genai.GenerativeModel("gemini-ultra-vision")；若写成gemini-pro-vision则锁定在低分辨率通道。
上传前精准预处理图像
关键上传前步骤：按模型上限等比缩放。用PIL加载图像后执行img.thumbnail((4096, 4096), Image.Resampling.LANCZOS)，自动保持宽高比，Lanczos重采样最大限度保留边缘锐度。另一种策略针对OCR场景：例如A4扫描件仅需识别右下角印章，用OpenCV定位坐标后crop加resize，将该区域放大至4096×4096满帧。模型注意力集中在高像素密度区域，识别精度显著提升。此外，WebP格式在同等视觉质量下体积比PNG小40%，上传失败率低，建议优先转为WebP再做base64编码。
构造请求Payload时控制图像数据精度
请求构造细节不可马虎。第一步取二进制文件必须用with open("input.webp", "rb") as f: raw_bytes = f.read()，用text模式会导致二进制头信息错乱，解析直接失败。第二步base64编码时去掉换行符：base64.b64encode(raw_bytes).decode('utf-8').replace("\n", "").replace("\r", "")。Gemini API对带\r\n的字符串会静默截断，图像残损。第三步，mime_type必须与实际格式严格对应；即使文件后缀.jpg，若实际编码为JPEG2000，需写成image/jp2。填错后服务端静默降级，输出质量下降且无报错提示。
验证分辨率是否真正生效
验证方法：在prompt中加入强约束指令：“请逐字转录图中所有文字，不得省略任何标点、数字或小字号注释。”观察响应：若出现“图中文字模糊无法识别”“部分区域未覆盖”等兜底回复，说明实际输入分辨率未达标——不必调整prompt，返回检查缩放逻辑与文件格式。高分辨率通路激活后，成功响应会包含精确到小数点后两位的坐标值、完整十六进制色值（如#3a86ff），或连续12位以上的数字串。这才是分辨率配置对齐后的表现。
