媒体分辨率

media_resolution 参数用于控制 Gemini API 处理图片、视频和 PDF 文档等媒体输入的方式，方法是确定为媒体输入分配的 token 数量上限，以便您在回答质量、延迟时间和费用之间取得平衡。如需了解不同设置、默认值及其与 token 的对应关系，请参阅token 数量部分。

您可以为请求（仅限 Gemini 3）中的各个媒体对象（内容项）配置媒体分辨率。

按内容项设置媒体分辨率（仅限 Gemini 3）

Gemini 3 允许您为请求中的各个媒体对象设置媒体分辨率，从而实现对 token 使用情况的精细优化。您可以在单个请求中混合使用不同的分辨率级别。例如，对于复杂的图表，使用高分辨率；对于简单的上下文图片，使用低分辨率。

Python

from google import genai
from google.genai import types

client = genai.Client()

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

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.steps[-1].content[0].text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/image.jpg",
    config: { mimeType: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mimeType: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await main();

REST

# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'

可用的分辨率值

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

  • unspecified：默认设置。对于此级别，Gemini 3 和更早版本的 Gemini 模型之间的 token 数量差异很大。
  • low：token 数量较少，因此处理速度更快，费用更低，但细节较少。
  • medium：在细节、费用和延迟时间之间取得平衡。
  • high：token 数量较多，为模型提供了更多细节，但延迟时间和费用也会增加。
  • ultra_high（仅限按内容项设置）：token 数量最多，某些用例（例如 计算机使用）需要此级别。

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

为每个级别生成的 token 的确切数量取决于媒体类型 （图片、视频、PDF）和模型版本 。

token 数量

下表总结了每个模型系列中每个 media_resolution 值和媒体类型对应的大致 token 数量。

Gemini 3 模型

MediaResolution 图片 视频 PDF
unspecified（默认） 1120 70 560
low 280 70 280 + 原生文本
medium 560 70 560 + 原生文本
high 1120 280 1120 + 原生文本
ultra_high 2240 不适用 不适用

选择合适的分辨率

  • 默认 (unspecified): 从默认设置开始。此设置经过调整，可在大多数常见用例中实现质量、延迟时间和费用的良好平衡。
  • low： 适用于费用和延迟时间至关重要，而精细细节不太重要的场景。
  • medium / high： 如果任务需要理解媒体中的复杂细节，请提高分辨率。这通常适用于复杂的视觉分析、图表阅读或密集文档理解。
  • ultra_high - 仅适用于按内容项设置。建议用于特定用例（例如计算机使用），或者测试表明此设置比 high 有明显提升。
  • 按内容项控制（Gemini 3）： 优化 token 使用情况。例如，在包含多张图片的提示中，对于复杂的图表，使用 high；对于较简单的上下文图片，使用 low 或 medium。

推荐设置

以下列出了每种受支持媒体类型的推荐媒体分辨率设置。

媒体类型 推荐设置 最大 token 数 使用指南
Google 图片 high 1120 建议用于大多数图片分析任务，以确保获得最高质量。
PDF medium 560 最适合文档理解；质量通常在 medium 级别达到饱和。对于标准文档，提高到 high 很少能改善 OCR 结果。
视频 （常规） low（或 medium） 70（每帧） 注意： 对于视频，low 和 medium 设置的处理方式相同（70 个 token），以优化上下文使用。这对于大多数动作识别和描述任务来说已经足够。
视频 （文本密集型） high 280（每帧） 仅当用例涉及读取视频帧中的密集文本 (OCR) 或小细节时才需要。

请务必测试和评估不同分辨率设置对应用的影响，以便在质量、延迟时间和费用之间找到最佳平衡点。

版本兼容性摘要

  • 在各个内容项上设置 resolution 仅适用于 Gemini 3 模型 。

后续步骤