メディアの解像度

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

リクエスト内の個々のメディア オブジェクト（コンテンツ アイテム）のメディア解像度を構成できます（Gemini 3 のみ）。

コンテンツ アイテムごとのメディア解像度（Gemini 3 のみ）

Gemini 3 では、リクエスト内の個々のメディア オブジェクトのメディア解像度を設定できるため、トークンの使用をきめ細かく最適化できます。1 つのリクエストで解像度レベルを混在させることができます。たとえば、複雑な図には高解像度を使用し、シンプルなコンテキスト画像には低解像度を使用します。

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)

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();

# 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 モデル

適切な解像度の選択

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

おすすめの設定

以下に、サポートされているメディアタイプごとにおすすめのメディア解像度設定を示します。

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

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

• 個々のコンテンツ アイテムに resolution を設定できるのは、Gemini 3 モデルのみ です。

次のステップ

• Gemini API のマルチモーダル機能について詳しくは、画像理解、動画理解、ドキュメント理解のガイドをご覧ください。