在使用 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 遇到带 rn 的字符串会静默截断，图像因而残缺。第三步，mime_type 必须与实际格式严格对应；即使文件后缀为 .jpg，若实际编码是 JPEG2000，就应写成 image/jp2。填写错误时，服务端会静默降级，输出质量下降但完全不返回任何报错提示。

验证分辨率是否真正生效

最后说明如何验证。在 prompt 中添加一条强制约束指令：“请逐字转录图中所有文字，不得省略任何标点、数字或小字号注释。”然后观察响应：若出现“图中文字模糊无法识别”“部分区域未覆盖”等兜底回复，说明实际输入分辨率未达标——此时不必调整 prompt，应返回检查缩放逻辑和文件格式。真正的高分辨率通路被激活后，成功响应中会包含精确到小数点后两位的坐标值、完整的十六进制色值（例如 #3a86ff），或连续 12 位以上的数字串。这正是分辨率配置对齐后的理想表现。