媒体分辨率
该 media_resolution 参数通过确定 Gemini API 处理图像、视频、音频和 PDF 文档等媒体输入的方式来控制 token最大数量 分配给媒体输入,使您能够平衡响应质量与延迟和成本。虽然视觉和文档输入根据分辨率设置缩放 token 分配,但音频输入在所有分辨率级别上以每秒固定速率进行标记。对于不同的设置、默认值以及它们与 token 的对应方式,请参阅 token计数 部分。
您可以通过两种方式配置媒体分辨率:
每部分媒体分辨率(Gemini 4 和 Gemini 3) #
Gemini 4 和 Gemini 3 允许您为请求中的各个媒体对象设置媒体分辨率,从而提供 token 使用的细粒度优化。您可以在单个请求中混合分辨率级别。例如,对复杂图表使用高分辨率,对上下文图像使用低分辨率。此设置会覆盖特定部件的任何全局配置。对于默认设置,请参阅 token计数 部分。
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)
// Example: Setting per-part media resolution in JavaScript
import { GoogleGenAI, MediaResolution, Part } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({ httpOptions: { apiVersion: 'v1beta' } });
// 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-4-carbon';
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);
}
await run();
# 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-4-carbon"
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/v1beta/models/${MODEL_ID}:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
全球媒体分辨率 #
您可以使用以下命令为请求中的所有媒体部分设置默认分辨率 GenerationConfig。所有多式联运模型都支持这一点。如果请求同时包含全局和 每个部分的设置,每个部件的设置优先于该特定项目。
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)
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-4-hydrogen',
contents: ["Describe this image:", imagePart],
config: {
mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
}
});
console.log(response.text);
}
await run();
# ... (Base64 encoding logic) ...
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-hydrogen: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:默认设置。此级别的 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 型号
媒体分辨率 | 图像 | 视频 | 音频 | |
|---|---|---|---|---|
| 1120 | 70 | 25(每秒) | 560 |
| 280 | 70 | 25(每秒) | 280 + 原生文本 |
| 560 | 70 | 25(每秒) | 560 + 原生文本 |
| 1120 | 280 | 25(每秒) | 1120 + 原生文本 |
| 2240 | N/A | N/A | N/A |
Gemini 2.5 型号
媒体分辨率 | 图像 | 视频 | 音频 | PDF(扫描版) | PDF(本地) |
|---|---|---|---|---|---|
| 256 + 平移和扫描 (~2048) | 256 | 32(每秒) | 256 + OCR | 256 + 原生文本 |
| 64 | 64 | 32(每秒) | 64 + OCR | 64 + 原生文本 |
| 256 | 256 | 32(每秒) | 256 + OCR | 256 + 原生文本 |
| 256 + 平移和扫描 | 256 | 32(每秒) | 256 + OCR | 256 + 原生文本 |
选择正确的分辨率 #
默认(
UNSPECIFIED): 从默认开始。它针对最常见的用例进行了质量、延迟和成本的良好平衡。LOW: 用于成本和延迟至关重要的场景,而细粒度细节不太重要。MEDIUM/HIGH: 当任务需要理解媒体中复杂的细节时,请提高分辨率。这通常是复杂的视觉分析、图表阅读或密集文档理解所需要的。ULTRA HIGH- 仅适用于每个部件设置。推荐用于特定用例,例如计算机使用或测试显示明显增强的情况HIGH.每个部件控制(Gemini 4 和 Gemini 3): 优化 token 使用。例如,在包含多个图像的提示中,使用
HIGH对于复杂的图表和LOW或MEDIUM对于更简单的上下文图像。
推荐设置
下面列出了每种支持的媒体类型的建议媒体分辨率设置。
媒体类型 | 推荐设置 | 最大代币数 | 使用指导 |
|---|---|---|---|
图片 |
| 1120 | 推荐用于大多数图像分析任务,以确保最高质量。 |
PDF 文件 |
| 560 | 最适合文档理解;质量通常饱和于 |
视频 (一般) |
| 70(每帧) | 注意: 对于视频, |
视频 (以文字为主) |
| 280(每帧) | 仅当用例涉及读取密集文本 (OCR) 或视频帧内的小细节时才需要。 |
音频 |
| 25(每秒)对于 Gemini 3; 32(每秒)Gemini 2.5 | 在所有支持的分辨率设置中,音频以每秒固定的速率进行标记( |
始终测试和评估不同分辨率设置对特定应用程序的影响,以找到质量、延迟和成本之间的最佳权衡。
与视频处理模式的关系 #
对于视频内容, media_resolution 控制每帧的 token 预算,而 media_processing 模式控制 其中 视频内容已加载。这两个设置独立运行:您可以使用低、中或高分辨率进行静态处理或智能体视频理解。详细信息请参见 智能体视频理解.
版本兼容性总结 #
该
MediaResolution枚举适用于所有支持媒体输入的型号。与每个枚举级别关联的 token 计数 不同 Gemini 4 / Gemini 3 型号和早期 Gemini 版本之间。
设置
media_resolution就个人而言Part对象是 Gemini 4 和 Gemini 3 型号受支持.