媒体分辨率

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

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

每部分（仅限 Gemini 3）
全局，适用于整个 generateContent 请求（所有多模态模型）

各部分的媒体分辨率（仅限 Gemini 3）

Gemini 3 可让您为请求中的各个媒体对象设置媒体分辨率，从而实现精细的令牌用量优化。您可以在单个请求中混合使用不同的分辨率级别。例如，为复杂的图表使用高分辨率，为简单的上下文相关图片使用低分辨率。此设置会覆盖特定部分的任何全局配置。如需了解默认设置，请参阅令牌数量部分。

Python

from google import genai
from google.genai import types

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

# 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-3-pro-preview'

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

JavaScript

// Example: Setting per-part media resolution in JavaScript
import { GoogleGenAI, MediaResolution, Part } from '@google/genai';
import * as fs from 'fs';
import { Buffer } from 'buffer'; // Node.js

const ai = new GoogleGenAI({ httpOptions: { apiVersion: 'v1alpha' } });

// Helper function to convert local file to a Part object
function fileToGenerativePart(path, mimeType, mediaResolution) {
    return {
        inlineData: { data: Buffer.from(fs.readFileSync(path)).toString('base64'), mimeType },
        mediaResolution: { 'level': mediaResolution }
    };
}

async function run() {
    // Create parts with different resolutions
    const imagePartHigh = fileToGenerativePart('img.png', 'image/png', Part.MediaResolutionLevel.MEDIA_RESOLUTION_HIGH);
    const model_name = 'gemini-3-pro-preview';
    const response = await ai.models.generateContent({
        model: model_name,
        contents: ['Describe these images:', imagePartHigh]
        // Global config can still be set, but per-part settings will override
        // config: {
        //   mediaResolution: MediaResolution.MEDIA_RESOLUTION_MEDIUM
        // }
    });
    console.log(response.text);
}
run();

REST

# Replace with paths to your images
IMAGE_PATH="path/to/image.jpg"

# Base64 encode the images
BASE64_IMAGE1=$(base64 -w 0 "$IMAGE_PATH")

MODEL_ID="gemini-3-pro-preview"

echo '{
    "contents": [{
      "parts": [
        {"text": "Describe these images:"},
        {
          "inline_data": {
            "mime_type": "image/jpeg",
            "data": "'"$BASE64_IMAGE1"'",
          },
          "media_resolution": {"level": "MEDIA_RESOLUTION_HIGH"}
        }
      ]
    }]
  }' > request.json

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1alpha/models/${MODEL_ID}:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

全球媒体分辨率

您可以使用 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-2.5-flash',
    contents=["Describe this image:", image_part],
    config=config
)
print(response.text)

JavaScript

import { GoogleGenAI, MediaResolution } from '@google/genai';
import * as fs from 'fs';

const ai = new GoogleGenAI({ });

async function run() {
   // ... (Image loading logic) ...

   const response = await ai.models.generateContent({
      model: 'gemini-2.5-flash',
      contents: ["Describe this image:", imagePart],
      config: {
         mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
      }
   });
   console.log(response.text);
}
run();

REST

# ... (Base64 encoding logic) ...

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [...],
    "generation_config": {
      "media_resolution": "MEDIA_RESOLUTION_HIGH"
    }
  }'

可用的分辨率值

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

MEDIA_RESOLUTION_UNSPECIFIED：默认设置。此级别的令牌数量在 Gemini 3 与之前的 Gemini 模型之间存在显著差异。
MEDIA_RESOLUTION_LOW：词元数量较少，因此处理速度更快，费用更低，但细节较少。
MEDIA_RESOLUTION_MEDIUM：在细节、费用和延迟时间之间取得平衡。
MEDIA_RESOLUTION_HIGH：词元数量较多，可为模型提供更多细节，但延迟时间和费用也会增加。
（即将推出）MEDIA_RESOLUTION_ULTRA_HIGH：特定使用场景（例如使用电脑）所需的最高令牌数量。

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

token 数量

下表总结了每个模型系列中每个 media_resolution 值和媒体类型的近似令牌数。

Gemini 3 模型

MediaResolution	图片	视频	PDF
`MEDIA_RESOLUTION_UNSPECIFIED`（默认）	1120	70	560
`MEDIA_RESOLUTION_LOW`	280	70	280 + 原生文字
`MEDIA_RESOLUTION_MEDIUM`	560	70	560 + 原生文字
`MEDIA_RESOLUTION_HIGH`	1120	280	1120 + 原生文本

Gemini 2.5 模型

MediaResolution	图片	视频	PDF（扫描版）	PDF（原生）
`MEDIA_RESOLUTION_UNSPECIFIED`（默认）	256 + 平移和扫描 (~2048)	256	256 + OCR	256 + 原生文字
`MEDIA_RESOLUTION_LOW`	64	64	64 + OCR	64 + 原生文本
`MEDIA_RESOLUTION_MEDIUM`	256	256	256 + OCR	256 + 原生文字
`MEDIA_RESOLUTION_HIGH`	256 + Pan & Scan	256	256 + OCR	256 + 原生文字

选择合适的分辨率

默认 (UNSPECIFIED)：从默认设置开始。它经过调整，可在大多数常见使用场景中实现质量、延迟时间和成本的良好平衡。
LOW：适用于成本和延迟时间至关重要，而细粒度细节不太重要的场景。
MEDIUM / HIGH：如果任务需要了解媒体中的复杂细节，请提高分辨率。这通常对于复杂的视觉分析、图表解读或密集文档理解是必需的。
按部分控制（Gemini 3）：利用此功能可优化令牌用量。例如，在包含多张图片的提示中，使用 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 个令牌），以优化上下文使用情况。这对于大多数动作识别和描述任务来说已经足够。
视频（文字较多）	`MEDIA_RESOLUTION_HIGH`	280（每帧）	仅当用例涉及读取密集文本 (OCR) 或视频帧中的微小细节时才需要。

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

版本兼容性摘要

MediaResolution 枚举适用于支持媒体输入的所有模型。
与每个枚举级别关联的令牌数量在 Gemini 3 模型与更早的 Gemini 版本之间有所不同。
在各个 Part 对象上设置 media_resolution 仅限 Gemini 3 模型。

后续步骤

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