媒体分辨率

media_resolution 参数用于确定为媒体输入分配的 token 数量上限，从而控制 Gemini API 处理图片、视频、音频和 PDF 文档等媒体输入的方式，让您可以在回答质量与延迟时间和成本之间取得平衡。虽然视觉和文档输入的 token 分配会根据分辨率设置进行调整，但音频输入在所有分辨率级别下均以固定的每秒速率进行 token 化。如需了解不同设置、默认值以及它们与令牌的对应关系，请参阅令牌数量部分。

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

每个内容项的媒体分辨率（仅限 Gemini 3）

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

Python

from google import genai

client = genai.Client()

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

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_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: { mime_type: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mime_type: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
    ImageContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

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.8-flash",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'

可用的分辨率值

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

unspecified：默认设置。此级别的 token 数量在 Gemini 3 和更早的 Gemini 模型之间差异很大。
low：token 数量较少，因此处理速度更快，费用更低，但细节较少。
medium：在细节、费用和延迟之间取得平衡。
high：token 数量较多，可为模型提供更多细节，但延迟时间和费用也会增加。
ultra_high（仅限每个内容项）：最高令牌数，适用于特定使用场景，例如计算机使用。

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

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

token 数量

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

Gemini 3 模型

MediaResolution	映像	视频	音频	PDF
`unspecified`（默认）	1120	70	25（每秒）	560
`low`	280	70	25（每秒）	280 + 原生文本
`medium`	560	70	25（每秒）	560 + 原生文本
`high`	1120	280	25（每秒）	1120 + 原生文本
`ultra_high`	2240	不适用	不适用	不适用

选择合适的分辨率

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

推荐设置

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

媒体类型	推荐设置	最大token数	使用指南
图片	`high`	1120	建议用于大多数图片分析任务，以确保获得最佳质量。
PDF	`medium`	560	非常适合文档理解；质量通常在 `medium` 时达到饱和。将该值增加到 `high` 很少能提高标准文档的 OCR 结果。
视频（常规）	`low`（或 `medium`）	70（每帧）	注意：对于视频，`low` 和 `medium` 设置的处理方式相同（70 个 token），以优化上下文使用。这对于大多数动作识别和描述任务来说已经足够。
视频（文字较多）	`high`	280（每帧）	仅当用例涉及读取视频帧中的密集文本 (OCR) 或细微细节时才需要。
音频	`unspecified`（默认）	25（每秒）	音频的 token 化速率固定为每秒 25 个 token，适用于所有支持的分辨率设置（`unspecified`、`low`、`medium` 和 `high`）。

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

与视频处理模式的关系

media_resolution 和处理参数可控制视频输入的不同方面：

media_resolution 用于控制每个帧的分辨率（每帧的令牌数）。
processing / media_processing 用于控制将视频中的哪些内容加载到上下文中。

您可以为同一视频输入源同时设置这两项。例如，您可以使用低媒体分辨率的智能体处理来最大限度地减少长视频的总 token 使用量。

如需详细了解视频处理模式，请参阅 Agentic 视频理解指南。

版本兼容性摘要

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

后续步骤

如需详细了解 Gemini API 的多模态功能，请参阅图片理解、视频理解、音频理解和文档理解指南。