媒體解析度

media_resolution 參數可決定分配給媒體輸入內容的權杖數量上限，藉此控管 Gemini API 處理圖片、影片和 PDF 文件等媒體輸入內容的方式，讓您在回覆品質、延遲時間和費用之間取得平衡。如要瞭解不同設定、預設值，以及這些設定與權杖的對應關係，請參閱「權杖計數」一節。

您可以在要求中設定個別媒體物件 (內容項目) 的媒體解析度 (僅限 Gemini 3)。

每個內容項目的媒體解析度 (僅限 Gemini 3)

Gemini 3 可讓您在要求中為個別媒體物件設定媒體解析度，進而精細調整權杖用量。您可以在單一要求中混用解析度層級。舉例來說，複雜的圖表使用高解析度，簡單的脈絡圖片則使用低解析度。

Python

from google import genai
from google.genai import types

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.steps[-1].content[0].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: { mimeType: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mimeType: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await main();

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-flash-preview",
    "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 560
low 280 70 280 + 原生文字
medium 560 70 560 + 原生文字
high 1120 280 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) 或影片影格中的細微細節時，才需要此功能。

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

版本相容性摘要

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

後續步驟