媒体分辨率
该 media_resolution 参数通过确定 Gemini API 处理图像、视频、音频和 PDF 文档等媒体输入的方式来控制 token最大数量 分配给媒体输入,使您能够平衡响应质量与延迟和成本。虽然视觉和文档输入根据分辨率设置缩放 token 分配,但音频输入在所有分辨率级别上以每秒固定速率进行标记。对于不同的设置、默认值以及它们与 token 的对应方式,请参阅 token计数 部分。
您可以为请求(Gemini 4 和 Gemini 3 型号)中的各个媒体对象(内容项)配置媒体分辨率。
每个内容项的媒体分辨率(Gemini 4 和 Gemini 3 型号) #
Gemini 4 和 Gemini 3 型号允许您为请求中的各个媒体对象设置媒体分辨率,从而提供 token 使用的细粒度优化。您可以在单个请求中混合分辨率级别。例如,对复杂图表使用高分辨率,对简单上下文图像使用低分辨率。
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/image.jpg")
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=[
{"type": "text", "text": "Describe this image:"},
{
"type": "image",
"uri": myfile.uri,
"mime_type": myfile.mime_type,
"resolution": "high"
}
]
)
print(interaction.output_text)
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-4-hydrogen",
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();
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-4-hydrogen"))
.input(InteractionsInput.ofContent(contents))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-4-hydrogen"),
Input: interactions.NewInteractionsInput([]interactions.Content{
interactions.NewContent(interactions.TextContent{
Text: "Describe the details in this high-resolution image.",
}),
interactions.NewContent(interactions.ImageContent{
URI: genai.Ptr(uploadedFile.URI),
MimeType: interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
Resolution: interactions.MediaResolutionHigh.ToPointer(),
}),
}),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
# 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' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-4-hydrogen",
"input": [
{"type": "text", "text": "Describe this image:"},
{
"type": "image",
"uri": "YOUR_FILE_URI",
"mime_type": "image/jpeg",
"resolution": "high"
}
]
}'
可用分辨率值 #
Gemini API 定义了以下媒体分辨率级别:
unspecified:默认设置。此级别的 token 计数在 Gemini 4/3 和早期的 Gemini 型号之间存在显着差异。low:token 数量较少,处理速度更快,成本更低,但细节较少。medium:细节、成本和延迟之间的平衡。high:更高的 token 数量,为模型提供更多细节,但代价是增加延迟和成本。ultra_high(仅限每个内容项):最高 token 计数,特定用例所需,例如 电脑使用.
请注意 high 为大多数用例提供最佳性能。
为每个级别生成的 token 的确切数量取决于 媒体类型 (图像、视频、音频、PDF)和 型号版本.
token计数 #
下表总结了每个 token 的近似计数 media_resolution 每个型号系列的值和媒体类型。
Gemini 4 和 Gemini 3 型号
| 媒体分辨率 | 图像 | 视频 | 音频 | |
|---|---|---|---|---|
unspecified (默认) | 1120 | 70 | 25(每秒) | 560 |
low | 280 | 70 | 25(每秒) | 280 + 原生文本 |
medium | 560 | 70 | 25(每秒) | 560 + 原生文本 |
high | 1120 | 280 | 25(每秒) | 1120 + 原生文本 |
ultra_high | 2240 | N/A | N/A | N/A |
选择正确的分辨率 #
- 默认(
unspecified): 从默认开始。它针对最常见的用例进行了质量、延迟和成本的良好平衡。 low: 用于成本和延迟至关重要的场景,而细粒度细节不太重要。medium/high: 当任务需要理解媒体中复杂的细节时,请提高分辨率。这通常是复杂的视觉分析、图表阅读或密集文档理解所需要的。ultra_high- 仅适用于每个内容项设置。推荐用于特定用例,例如计算机使用或测试显示明显增强的情况high.- 按内容项控制(Gemini 4 和 Gemini 3): 优化 token 使用。例如,在包含多个图像的提示中,使用
high对于复杂的图表和low或medium对于更简单的上下文图像。
推荐设置
下面列出了每种支持的媒体类型的建议媒体分辨率设置。
| 媒体类型 | 推荐设置 | 最大代币数 | 使用指导 |
|---|---|---|---|
| 图片 | high | 1120 | 推荐用于大多数图像分析任务,以确保最高质量。 |
| PDF 文件 | medium | 560 | 最适合文档理解;质量通常饱和于 medium。增加到 high 很少改善标准文档的 OCR 结果。 |
| 视频 (一般) | low (或 medium) | 70(每帧) | 注意: 对于视频, low 和 medium 设置以相同方式处理(70 token)以优化上下文使用。这对于大多数动作识别和描述任务来说已经足够了。 |
| 视频 (以文字为主) | high | 280(每帧) | 仅当用例涉及读取密集文本 (OCR) 或视频帧内的小细节时才需要。 |
| 音频 | unspecified (默认) | 25(每秒) | 在所有支持的分辨率设置中,音频以每秒 25 token 的固定速率进行标记(unspecified, low, medium, 和 high). |
始终测试和评估不同分辨率设置对应用程序的影响,以找到质量、延迟和成本之间的最佳权衡。
与视频处理模式的关系 #
对于视频内容, media_resolution 控制每帧的 token 预算,而 processing 模式控制 其中 视频内容已加载。这两个设置独立运行:您可以使用低、中或高分辨率进行静态处理或智能体视频理解。详细信息请参见 智能体视频理解.
版本兼容性总结 #
- 设置
resolution各个内容项上的内容是 Gemini 4 和 Gemini 3 型号受支持.