# 媒体分辨率

该 `media_resolution` 参数通过确定 Gemini API 处理图像、视频、音频和 PDF 文档等媒体输入的方式来控制 **token最大数量** 分配给媒体输入，使您能够平衡响应质量与延迟和成本。虽然视觉和文档输入根据分辨率设置缩放 token 分配，但音频输入在所有分辨率级别上以每秒固定速率进行标记。对于不同的设置、默认值以及它们与 token 的对应方式，请参阅 [token计数](/docs/media-resolution#token-counts) 部分。

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

## 每个内容项的媒体分辨率（Gemini 4 和 Gemini 3 型号）  {% #per-content-item-media-resolution %}

Gemini 4 和 Gemini 3 型号允许您为请求中的各个媒体对象设置媒体分辨率，从而提供 token 使用的细粒度优化。您可以在单个请求中混合分辨率级别。例如，对复杂图表使用高分辨率，对简单上下文图像使用低分辨率。

{% tabs %}
{% tab label="Python" %}
```python
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)
```
{% /tab %}

{% tab label="JavaScript" %}
```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-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();
```
{% /tab %}

{% tab label="Java" %}
```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-4-hydrogen"))
        .input(InteractionsInput.ofContent(contents))
        .build();

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

System.out.println(interaction.outputText().orElse(""));
```
{% /tab %}

{% tab label="Go" %}
```go
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)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```shell
# 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"
      }
    ]
  }'
```
{% /tab %}
{% /tabs %}

## 可用分辨率值  {% #available-resolution-values %}

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

* `unspecified`：默认设置。此级别的 token 计数在 Gemini 4/3 和早期的 Gemini 型号之间存在显着差异。
* `low`：token 数量较少，处理速度更快，成本更低，但细节较少。
* `medium`：细节、成本和延迟之间的平衡。
* `high`：更高的 token 数量，为模型提供更多细节，但代价是增加延迟和成本。
* `ultra_high` （仅限每个内容项）：最高 token 计数，特定用例所需，例如 [电脑使用](/docs/computer-use).

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

为每个级别生成的 token 的确切数量取决于 **媒体类型** （图像、视频、音频、PDF）和 **型号版本**.

## token计数  {% #token-counts %}

下表总结了每个 token 的近似计数 `media_resolution` 每个型号系列的值和媒体类型。

**Gemini 4 和 Gemini 3 型号**

| 媒体分辨率              | 图像   | 视频  | 音频     | PDF         |
| ------------------ | ---- | --- | ------ | ----------- |
| `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         |

## 选择正确的分辨率  {% #choosing-the-right-resolution %}

* **默认（`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`).   |

始终测试和评估不同分辨率设置对应用程序的影响，以找到质量、延迟和成本之间的最佳权衡。

## 与视频处理模式的关系  {% #relationship-with-video-processing-modes %}

对于视频内容， `media_resolution` 控制每帧的 token 预算，而 `processing` 模式控制 *其中* 视频内容已加载。这两个设置独立运行：您可以使用低、中或高分辨率进行静态处理或智能体视频理解。详细信息请参见 [智能体视频理解](/docs/video-understanding#agentic-video-understanding).

## 版本兼容性总结  {% #version-compatibility-summary %}

* 设置 `resolution` 各个内容项上的内容是 **Gemini 4 和 Gemini 3 型号受支持**.

## 后续步骤  {% #next-steps %}

* 了解有关 Gemini API 多模态功能的更多信息 [图像理解](/docs/image-understanding), [视频理解](/docs/video-understanding), [音频理解](/docs/audio), 和 [文档理解](/docs/document-processing) 指南。
