媒體解析度

media_resolution 參數可控制 Gemini API 處理媒體輸入內容 (例如圖片、影片、音訊和 PDF 文件) 的方式，方法是決定分配給媒體輸入內容的權杖數量上限，讓您在回覆品質、延遲時間和成本之間取得平衡。雖然視覺和文件輸入內容會根據解析度設定調整權杖分配量，但音訊輸入內容在所有解析度層級中，每秒的權杖化率都是固定的。如要瞭解不同設定、預設值，以及這些設定如何對應至符記，請參閱「符記數量」一節。

你可以在要求中設定個別媒體物件 (內容項目) 的媒體解析度 (僅限 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：預設設定。Gemini 3 和舊版 Gemini 模型在這個層級的詞元數差異很大。
  • low：減少詞元數量，加快處理速度並降低成本，但詳細程度較低。
  • medium：在詳細程度、費用和延遲時間之間取得平衡。
  • high：詞元數較多，可為模型提供更多詳細資料，但延遲時間和費用會增加。
  • ultra_high (僅限每個內容項目)：最高詞元數，適用於特定用途，例如電腦使用。

請注意，high 可為大多數用途提供最佳效能。

各層級產生的確切權杖數量取決於媒體類型 (圖片、影片、音訊、PDF) 和模型版本。

符記數量

下表彙整了各模型系列的每個 media_resolution 值和媒體類型，對應的概略權杖數量。

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 產生較簡單的脈絡圖片。

建議設定

下表列出各支援媒體類型的建議媒體解析度設定。

媒體類型 建議設定 詞元數上限 使用指南
圖片 high 1120 建議用於大多數圖像分析工作，確保最高品質。
PDF medium 560 最適合用於文件解讀；品質通常會在 medium 達到飽和。增加至 high 很少能改善標準文件的 OCR 結果。
影片 (一般) low (或 medium) 70 (每格) 注意：對於影片，系統會將 low 和 medium 設定視為相同 (70 個權杖)，以最佳化情境使用情形。這足以應付大多數的動作辨識和描述工作。
影片 (文字內容較多) high 280 (每格) 只有在用途涉及讀取密集文字 (OCR) 或影片影格中的細節時，才需要此功能。
音訊 unspecified (預設) 25 (每秒) 在所有支援的解析度設定 (unspecified、low、medium 和 high) 中，音訊的代碼化固定為每秒 25 個權杖。

請務必測試及評估不同解析度設定對應用程式的影響，找出品質、延遲和成本之間的最佳取捨。

與影片處理模式的關係

media_resolution 和處理參數可控制影片輸入的不同層面：

  • media_resolution 可控制每個影格的解析度 (每個影格的權杖數量)。
  • processing / media_processing 控制項會將影片中的哪些內容載入至情境。

您可以在同一個影片輸入中設定這兩項功能。舉例來說，您可能會使用低媒體解析度的代理處理，盡量減少長影片的權杖總用量。

如要瞭解影片處理模式的詳細資料，請參閱「Agentic 影片理解」指南。

版本相容性摘要

  • resolution 只能透過 Gemini 3 模型為個別內容項目設定。

後續步驟