メディアの解像度

media_resolution パラメータは、メディア入力に割り当てられるトークンの最大数を決定することで、Gemini API が画像、動画、音声、PDF ドキュメントなどのメディア入力を処理する方法を制御します。これにより、レスポンスの品質とレイテンシ、費用を調整できます。画像入力とドキュメント入力では、解像度の設定に基づいてトークンの割り当てがスケーリングされますが、音声入力はすべての解像度レベルで 1 秒あたりの固定レートでトークン化されます。さまざまな設定、デフォルト値、トークンとの対応については、トークン数セクションをご覧ください。

メディアの解像度を構成する方法は 2 つあります。

パートごとのメディア解像度(Gemini 3 のみ)

Gemini 3 では、リクエスト内の個々のメディア オブジェクトのメディア解像度を設定できるため、トークン使用量のきめ細かい最適化が可能です。1 つのリクエストで解像度レベルを混在させることができます。たとえば、複雑な図には高解像度を使用し、コンテキスト画像には低解像度を使用します。この設定は、特定の部分のグローバル構成をオーバーライドします。デフォルト設定については、トークン数セクションをご覧ください。

Python

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-3.1-pro-preview'

response = client.models.generate_content(
    model=model_name,
    contents=["Describe these images:", image_part_high]
)
print(response.text)

JavaScript

// Example: Setting per-part media resolution in JavaScript
import { GoogleGenAI, MediaResolution, Part } from '@google/genai';
import * as fs from 'fs';
import { Buffer } from 'buffer'; // Node.js

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-3.1-pro-preview';
    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);
}
run();

REST

# 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-3.1-pro-preview"

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 を使用すると、リクエスト内のすべてのメディア要素のデフォルトの解像度を設定できます。これは、すべてのマルチモーダル モデルでサポートされています。リクエストにグローバル設定とパーツごとの設定の両方が含まれている場合、その特定のアイテムではパーツごとの設定が優先されます。

Python

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-3.8-flash',
    contents=["Describe this image:", image_part],
    config=config
)
print(response.text)

JavaScript

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-3.8-flash',
      contents: ["Describe this image:", imagePart],
      config: {
         mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
      }
   });
   console.log(response.text);
}
run();

REST

# ... (Base64 encoding logic) ...

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash: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: デフォルト設定。このレベルのトークン数は、Gemini 3 と以前の Gemini モデルで大きく異なります。
  • MEDIA_RESOLUTION_LOW: トークン数が少なくなり、処理が高速化され、コストが削減されますが、詳細情報は少なくなります。
  • MEDIA_RESOLUTION_MEDIUM: 詳細、費用、レイテンシのバランス。
  • MEDIA_RESOLUTION_HIGH: トークン数が多いほど、モデルが処理する詳細が増えますが、レイテンシと費用が増加します。
  • MEDIA_RESOLUTION_ULTRA_HIGH(パートごと): トークン数が最も多く、パソコンの使用などの特定のユースケースで必要です。

MEDIA_RESOLUTION_HIGH はほとんどのユースケースで最適なパフォーマンスを提供します。

これらの各レベルで生成されるトークンの正確な数は、メディアタイプ(画像、動画、音声、PDF)とモデル バージョンの両方によって異なります。

トークン数

次の表は、モデル ファミリーごとに、各 media_resolution 値とメディアタイプのおおよそのトークン数をまとめたものです。

Gemini 3 モデル

MediaResolution 画像 動画 音声 PDF
MEDIA_RESOLUTION_UNSPECIFIED(デフォルト) 1120 70 25(1 秒あたり) 560
MEDIA_RESOLUTION_LOW 280 70 25(1 秒あたり) 280 + ネイティブ テキスト
MEDIA_RESOLUTION_MEDIUM 560 70 25(1 秒あたり) 560 + ネイティブ テキスト
MEDIA_RESOLUTION_HIGH 1120 280 25(1 秒あたり) 1120 + ネイティブ テキスト
MEDIA_RESOLUTION_ULTRA_HIGH 2,240 なし なし なし

Gemini 2.5 モデル

MediaResolution 画像 動画 音声 PDF(スキャン) PDF(ネイティブ)
MEDIA_RESOLUTION_UNSPECIFIED(デフォルト) 256 + パン&スキャン(~2048) 256 32(1 秒あたり) 256 + OCR 256 + ネイティブ テキスト
MEDIA_RESOLUTION_LOW 64 64 32(1 秒あたり) 64 + OCR 64 + ネイティブ テキスト
MEDIA_RESOLUTION_MEDIUM 256 256 32(1 秒あたり) 256 + OCR 256 + ネイティブ テキスト
MEDIA_RESOLUTION_HIGH 256 + パン&スキャン 256 32(1 秒あたり) 256 + OCR 256 + ネイティブ テキスト

適切な解決策の選択

  • デフォルト(UNSPECIFIED): デフォルトから開始します。最も一般的なユースケースで、品質、レイテンシ、費用のバランスが取れるように調整されています。
  • LOW: 費用とレイテンシが最優先で、詳細な情報はそれほど重要ではないシナリオで使用します。
  • MEDIUM / HIGH: メディア内の複雑な詳細を理解する必要があるタスクでは、解像度を上げます。これは、複雑な視覚分析、チャートの読み取り、密度の高いドキュメントの理解に必要になることがよくあります。
  • ULTRA HIGH - パーツごとの設定でのみ使用できます。パソコンでの使用など、特定のユースケースや、テストで HIGH よりも明確な改善が見られる場合に推奨されます。
  • パートごとの制御(Gemini 3): トークンの使用量を最適化します。たとえば、複数の画像を含むプロンプトでは、複雑な図には HIGH を使用し、シンプルなコンテキスト画像には LOW または MEDIUM を使用します。

推奨設定

以下に、サポートされている各メディアタイプに推奨されるメディア解像度設定を示します。

メディアタイプ 推奨設定 最大トークン数 使用に関するガイダンス
画像検索 MEDIA_RESOLUTION_HIGH 1120 品質を最大限に高めるため、ほとんどの画像分析タスクに推奨されます。
PDF MEDIA_RESOLUTION_MEDIUM 560 ドキュメントの理解に最適です。通常、品質は medium で飽和します。high に増やしても、標準的なドキュメントの OCR 結果が改善されることはほとんどありません。
動画(全般) MEDIA_RESOLUTION_LOW(または MEDIA_RESOLUTION_MEDIUM 70(フレームあたり) 注: 動画の場合、コンテキストの使用を最適化するために、lowmedium の設定は同じ(70 個のトークン)として扱われます。これは、ほとんどのアクション認識と説明のタスクで十分です。
動画(テキストが多い) MEDIA_RESOLUTION_HIGH 280(フレームあたり) ユースケースで、密度の高いテキスト(OCR)や動画フレーム内の細部を読み取る場合にのみ必要です。
音声 MEDIA_RESOLUTION_UNSPECIFIED(デフォルト) Gemini 3 の場合は 25(秒あたり)、Gemini 2.5 の場合は 32(秒あたり) 音声は、サポートされているすべての解像度設定(unspecifiedlowmediumhigh)で、1 秒あたり一定のレートでトークン化されます。

さまざまな解像度設定が特定のアプリケーションに与える影響を常にテストして評価し、品質、レイテンシ、費用の最適なトレードオフを見つけてください。

動画処理モードとの関係

media_resolution パラメータと処理パラメータは、動画入力のさまざまな側面を制御します。

  • media_resolution は各フレームの解像度(フレームあたりのトークン数)を制御します。
  • processing / media_processing は、動画のどのコンテンツがコンテキストに読み込まれるかを制御します。

同じ動画入力に両方を設定できます。たとえば、メディアの解像度を低くしてエージェント処理を使用すると、長い動画の合計トークン使用量を最小限に抑えることができます。

動画処理モードの詳細については、エージェント動画理解ガイドをご覧ください。

バージョンの互換性の概要

  • MediaResolution 列挙型は、メディア入力をサポートするすべてのモデルで使用できます。
  • 各列挙型レベルに関連付けられているトークン数は、Gemini 3 モデルと以前の Gemini バージョンで異なります
  • 個々の Part オブジェクトに media_resolution を設定できるのは、Gemini 3 モデルのみです。

次のステップ