Gemini API高分辨率图片处理参数配置：精细视觉识别
在OCR识别、医疗影像分析、芯片缺陷检测这类要求像素级精度的视觉任务中，一个常见陷阱是Gemini API默认输出的1024×1024图像导致关键纹理和边缘信息模糊，直接引发文字误识、病灶漏判、微米级划痕不可见。因此，掌握media_resolution参数的配置方法，是提升任务精度的核心。
确认当前模型是否支持media_resolution参数
插一句，并非所有Gemini模型都支持该参数。当前仅有两款原生支持：Gemini 3 Pro Image（模型ID：gemini-3-pro-image-preview）和Gemini 3.1 Flash Image HD（代号Nano Banana HD）。Gemini 3 Flash或基础版gemini-3无法识别此字段，传入后会被静默忽略——数据丢失且无提示。调用前必须显式指定模型ID为gemini-3-pro-image-preview，否则后续所有分辨率设置均无效。
media_resolution参数的合法取值与对应场景
该参数接受区分大小写的字符串，当前支持四种取值：
• "low" → 输出约512×512，适用于草图验证、布局预览，响应最快
• "medium" → 输出约1024×1024，默认值，常规图文理解无问题
• "high" → 输出约2048×1024（16:9）或1200×1600（4:3），适合印刷物料、投研图表、电商主图
• "ultra_high" → 输出7680×4320（8K），专为显微图像分析、卫星遥感、IC掩膜检测设计。但必须配合thinking_level="deep"使用，否则模型直接拒绝生成
Python SDK中正确配置media_resolution的完整代码路径
操作步骤虽不复杂，但细节易错。
第一步：安装最新SDK（v0.8.2+），执行pip install --upgrade google-genai
第二步：构建包含media_resolution的generation_config字典，注意不要将其置于contents子字段中
第三步：将generation_config传入generate_content方法
第四步：上传高保真源图时，务必使用bytes类型而非base64字符串，否则media_resolution会被降级为medium
示例代码片段：
from google import genai
genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
client = genai.Client()
response = client.models.generate_content(
model="gemini-3-pro-image-preview",
contents=[{"text": "分析该电路板焊点是否存在虚焊或桥接"}, {"inline_data": {"mime_type": "image/png", "data": image_bytes}}],
generation_config={"media_resolution": "ultra_high", "thinking_level": "deep"}
)
规避常见失败的三个硬性前提
还需注意几个易忽视点：
方法一：输入图片原始尺寸必须≥输出目标尺寸的80%，否则精度损失明显
方法二：若通过URL context方式传图，需确保直链返回HTTP 200且Content-Type准确（如image/jpeg），CDN缓存头须含no-transform才能启用ultra_high
方法三：当请求同时包含video和image多模态输入时，media_resolution仅对首个image生效，其余媒体自动降级为medium