Gemini 中文指南
获取 API 密钥 ↗

媒体分辨率

↓ 下载 Markdown

该 media_resolution 参数通过确定 Gemini API 处理图像、视频、音频和 PDF 文档等媒体输入的方式来控制 token最大数量 分配给媒体输入,使您能够平衡响应质量与延迟和成本。虽然视觉和文档输入根据分辨率设置缩放 token 分配,但音频输入在所有分辨率级别上以每秒固定速率进行标记。对于不同的设置、默认值以及它们与 token 的对应方式,请参阅 token计数 部分。

您可以为请求(Gemini 4 和 Gemini 3 型号)中的各个媒体对象(内容项)配置媒体分辨率。

每个内容项的媒体分辨率(Gemini 4 和 Gemini 3 型号) #

Gemini 4 和 Gemini 3 型号允许您为请求中的各个媒体对象设置媒体分辨率,从而提供 token 使用的细粒度优化。您可以在单个请求中混合分辨率级别。例如,对复杂图表使用高分辨率,对简单上下文图像使用低分辨率。

python
from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_text)

可用分辨率值 #

Gemini API 定义了以下媒体分辨率级别:

  • unspecified:默认设置。此级别的 token 计数在 Gemini 4/3 和早期的 Gemini 型号之间存在显着差异。
  • low:token 数量较少,处理速度更快,成本更低,但细节较少。
  • medium:细节、成本和延迟之间的平衡。
  • high:更高的 token 数量,为模型提供更多细节,但代价是增加延迟和成本。
  • ultra_high (仅限每个内容项):最高 token 计数,特定用例所需,例如 电脑使用.

请注意 high 为大多数用例提供最佳性能。

为每个级别生成的 token 的确切数量取决于 媒体类型 (图像、视频、音频、PDF)和 型号版本.

token计数 #

下表总结了每个 token 的近似计数 media_resolution 每个型号系列的值和媒体类型。

Gemini 4 和 Gemini 3 型号

媒体分辨率图像视频音频PDF
unspecified (默认)11207025(每秒)560
low2807025(每秒)280 + 原生文本
medium5607025(每秒)560 + 原生文本
high112028025(每秒)1120 + 原生文本
ultra_high2240N/AN/AN/A

选择正确的分辨率 #

  • 默认(unspecified): 从默认开始。它针对最常见的用例进行了质量、延迟和成本的良好平衡。
  • low: 用于成本和延迟至关重要的场景,而细粒度细节不太重要。
  • medium / high: 当任务需要理解媒体中复杂的细节时,请提高分辨率。这通常是复杂的视觉分析、图表阅读或密集文档理解所需要的。
  • ultra_high - 仅适用于每个内容项设置。推荐用于特定用例,例如计算机使用或测试显示明显增强的情况 high.
  • 按内容项控制(Gemini 4 和 Gemini 3): 优化 token 使用。例如,在包含多个图像的提示中,使用 high 对于复杂的图表和 low 或 medium 对于更简单的上下文图像。

推荐设置

下面列出了每种支持的媒体类型的建议媒体分辨率设置。

媒体类型推荐设置最大代币数使用指导
图片high1120推荐用于大多数图像分析任务,以确保最高质量。
PDF 文件medium560最适合文档理解;质量通常饱和于 medium。增加到 high 很少改善标准文档的 OCR 结果。
视频 (一般)low (或 medium)70(每帧)注意: 对于视频, low 和 medium 设置以相同方式处理(70 token)以优化上下文使用。这对于大多数动作识别和描述任务来说已经足够了。
视频 (以文字为主)high280(每帧)仅当用例涉及读取密集文本 (OCR) 或视频帧内的小细节时才需要。
音频unspecified (默认)25(每秒)在所有支持的分辨率设置中,音频以每秒 25 token 的固定速率进行标记(unspecified, low, medium, 和 high).

始终测试和评估不同分辨率设置对应用程序的影响,以找到质量、延迟和成本之间的最佳权衡。

与视频处理模式的关系 #

对于视频内容, media_resolution 控制每帧的 token 预算,而 processing 模式控制 其中 视频内容已加载。这两个设置独立运行:您可以使用低、中或高分辨率进行静态处理或智能体视频理解。详细信息请参见 智能体视频理解.

版本兼容性总结 #

  • 设置 resolution 各个内容项上的内容是 Gemini 4 和 Gemini 3 型号受支持.

后续步骤 #

搜索标题、API 名称或正文内容