Gemini 中文指南
获取 API 密钥 ↗

媒体分辨率

↓ 下载 Markdown

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

您可以通过两种方式配置媒体分辨率:

  • 每部分 (Gemini 4 和 Gemini 3 型号)

  • 全球范围 对于整个 generateContent 请求(所有多式联运型号)

每部分媒体分辨率(Gemini 4 和 Gemini 3) #

Gemini 4 和 Gemini 3 允许您为请求中的各个媒体对象设置媒体分辨率,从而提供 token 使用的细粒度优化。您可以在单个请求中混合分辨率级别。例如,对复杂图表使用高分辨率,对上下文图像使用低分辨率。此设置会覆盖特定部件的任何全局配置。对于默认设置,请参阅 token计数 部分。

python
  from google import genai
  from google.genai import types

  # The media_resolution parameter for parts is available in the v1beta API version.
  client = genai.Client(
    http_options={
        'api_version': 'v1beta',
    }
  )

  # Replace with your image data
  with open('path/to/image1.jpg', 'rb') as f:
      image_bytes_1 = f.read()

  # Create parts with different resolutions
  image_part_high = types.Part.from_bytes(
      data=image_bytes_1,
      mime_type='image/jpeg',
      media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
  )

  model_name = 'gemini-4-carbon'

  response = client.models.generate_content(
      model=model_name,
      contents=["Describe these images:", image_part_high]
  )
  print(response.text)

全球媒体分辨率 #

您可以使用以下命令为请求中的所有媒体部分设置默认分辨率 GenerationConfig。所有多式联运模型都支持这一点。如果请求同时包含全局和 每个部分的设置,每个部件的设置优先于该特定项目。

python
  from google import genai
  from google.genai import types

  client = genai.Client()

  # Prepare standard image part
  with open('image.jpg', 'rb') as f:
      image_bytes = f.read()
  image_part = types.Part.from_bytes(data=image_bytes, mime_type='image/jpeg')

  # Set global configuration
  config = types.GenerateContentConfig(
      media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
  )

  response = client.models.generate_content(
      model='gemini-4-hydrogen',
      contents=["Describe this image:", image_part],
      config=config
  )
  print(response.text)

可用分辨率值 #

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

  • MEDIA_RESOLUTION_UNSPECIFIED:默认设置。此级别的 token 计数在 Gemini 4 / Gemini 3 和早期的 Gemini 型号之间存在显着差异。

  • MEDIA_RESOLUTION_LOW:token 数量较少,处理速度更快,成本更低,但细节较少。

  • MEDIA_RESOLUTION_MEDIUM:细节、成本和延迟之间的平衡。

  • MEDIA_RESOLUTION_HIGH:更高的 token 数量,为模型提供更多细节,但代价是增加延迟和成本。

  • MEDIA_RESOLUTION_ULTRA_HIGH (仅限每个部件):最高 token 数量,特定用例所需,例如 电脑使用.

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

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

token计数 #

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

Gemini 4 和 Gemini 3 型号

媒体分辨率

图像

视频

音频

PDF

MEDIA_RESOLUTION_UNSPECIFIED (默认)

1120

70

25(每秒)

560

MEDIA_RESOLUTION_LOW

280

70

25(每秒)

280 + 原生文本

MEDIA_RESOLUTION_MEDIUM

560

70

25(每秒)

560 + 原生文本

MEDIA_RESOLUTION_HIGH

1120

280

25(每秒)

1120 + 原生文本

MEDIA_RESOLUTION_ULTRA_HIGH

2240

N/A

N/A

N/A

Gemini 2.5 型号

媒体分辨率

图像

视频

音频

PDF(扫描版)

PDF(本地)

MEDIA_RESOLUTION_UNSPECIFIED (默认)

256 + 平移和扫描 (~2048)

256

32(每秒)

256 + OCR

256 + 原生文本

MEDIA_RESOLUTION_LOW

64

64

32(每秒)

64 + OCR

64 + 原生文本

MEDIA_RESOLUTION_MEDIUM

256

256

32(每秒)

256 + OCR

256 + 原生文本

MEDIA_RESOLUTION_HIGH

256 + 平移和扫描

256

32(每秒)

256 + OCR

256 + 原生文本

选择正确的分辨率 #

  • 默认(UNSPECIFIED): 从默认开始。它针对最常见的用例进行了质量、延迟和成本的良好平衡。

  • LOW: 用于成本和延迟至关重要的场景,而细粒度细节不太重要。

  • MEDIUM / HIGH: 当任务需要理解媒体中复杂的细节时,请提高分辨率。这通常是复杂的视觉分析、图表阅读或密集文档理解所需要的。

  • ULTRA HIGH - 仅适用于每个部件设置。推荐用于特定用例,例如计算机使用或测试显示明显增强的情况 HIGH.

  • 每个部件控制(Gemini 4 和 Gemini 3): 优化 token 使用。例如,在包含多个图像的提示中,使用 HIGH 对于复杂的图表和 LOW 或 MEDIUM 对于更简单的上下文图像。

推荐设置

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

媒体类型

推荐设置

最大代币数

使用指导

图片

MEDIA_RESOLUTION_HIGH

1120

推荐用于大多数图像分析任务,以确保最高质量。

PDF 文件

MEDIA_RESOLUTION_MEDIUM

560

最适合文档理解;质量通常饱和于 medium。增加到 high 很少改善标准文档的 OCR 结果。

视频 (一般)

MEDIA_RESOLUTION_LOW (或 MEDIA_RESOLUTION_MEDIUM)

70(每帧)

注意: 对于视频, low 和 medium 设置以相同方式处理(70 token)以优化上下文使用。这对于大多数动作识别和描述任务来说已经足够了。

视频 (以文字为主)

MEDIA_RESOLUTION_HIGH

280(每帧)

仅当用例涉及读取密集文本 (OCR) 或视频帧内的小细节时才需要。

音频

MEDIA_RESOLUTION_UNSPECIFIED (默认)

25(每秒)对于 Gemini 3; 32(每秒)Gemini 2.5

在所有支持的分辨率设置中,音频以每秒固定的速率进行标记(unspecified, low, medium, 和 high).

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

与视频处理模式的关系 #

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

版本兼容性总结 #

  • 该 MediaResolution 枚举适用于所有支持媒体输入的型号。

  • 与每个枚举级别关联的 token 计数 不同 Gemini 4 / Gemini 3 型号和早期 Gemini 版本之间。

  • 设置 media_resolution 就个人而言 Part 对象是 Gemini 4 和 Gemini 3 型号受支持.

后续步骤 #

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