メディアの解像度

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

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

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

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

from google import genai

client = genai.Client()

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

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

  const interaction = await ai.interactions.create({
    model: "gemini-3.5-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();

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

適切な解決策の選択

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

推奨設定

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

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

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

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

次のステップ

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