URL context

URL コンテキスト ツールを使用すると、URL の形式でモデルに追加のコンテキストを提供できます。リクエストに URL を含めると、モデルはそれらのページのコンテンツにアクセスし（制限事項のセクションに記載されている URL タイプでない限り）、回答の情報を取得して強化します。

URL コンテキスト ツールは、次のようなタスクに役立ちます。

  • データの抽出: 複数の URL から価格、名前、重要な調査結果などの特定の情報を取得します。
  • ドキュメントの比較: 複数のレポート、記事、PDF を分析して、違いを特定し、傾向を追跡します。
  • コンテンツの統合と作成: 複数のソース URL からの情報を組み合わせて、正確な要約、ブログ投稿、レポートを生成します。
  • コードとドキュメントを分析: GitHub リポジトリまたは技術ドキュメントを指定して、コードの説明、設定手順の生成、質問への回答を行います。

次の例は、異なるウェブサイトの 2 つのレシピを比較する方法を示しています。

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig

client = genai.Client()
model_id = "gemini-2.5-flash"

tools = [
  {"url_context": {}},
]

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

response = client.models.generate_content(
    model=model_id,
    contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)

# For verification, you can inspect the metadata to see which URLs the model retrieved
print(response.candidates[0].url_context_metadata)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);

  // For verification, you can inspect the metadata to see which URLs the model retrieved
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

仕組み

URL コンテキスト ツールは、2 段階の取得プロセスを使用して、速度、費用、最新データへのアクセスをバランスよく調整します。URL を指定すると、ツールはまず内部インデックス キャッシュからコンテンツを取得しようとします。これは、高度に最適化されたキャッシュとして機能します。URL がインデックスに登録されていない場合（たとえば、非常に新しいページの場合）、ツールは自動的にライブ取得にフォールバックします。これにより、URL に直接アクセスして、コンテンツをリアルタイムで取得します。

URL コンテキスト ツールを他のツールと組み合わせて、より強力なワークフローを作成できます。

URL コンテキストと Google 検索によるグラウンディングの両方が有効になっている場合、モデルは検索機能を使用してオンラインで関連情報を検索し、URL コンテキスト ツールを使用して検索結果のページをより深く理解できます。このアプローチは、広範な検索と特定のページの詳細な分析の両方を必要とするプロンプトに有効です。

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext

client = genai.Client()
model_id = "gemini-2.5-flash"

tools = [
      {"url_context": {}},
      {"google_search": {}}
  ]

response = client.models.generate_content(
    model=model_id,
    contents="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    config=GenerateContentConfig(
        tools=tools,
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: [
        "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
    ],
    config: {
      tools: [
        {urlContext: {}},
        {googleSearch: {}}
        ],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          },
          {
              "google_search": {}
          }
      ]
  }' > result.json

cat result.json

レスポンスについて

モデルが URL コンテキスト ツールを使用すると、レスポンスに url_context_metadata オブジェクトが含まれます。このオブジェクトには、モデルがコンテンツを取得した URL と、各取得試行のステータスが一覧表示されます。これは、検証とデバッグに役立ちます。

レスポンスの例を次に示します（簡潔にするため、レスポンスの一部は省略されています）。

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata": {
        "url_metadata": [
          {
            "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          },
          {
            "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"
          }
        ]
      }
    }
}

このオブジェクトの詳細については、UrlContextMetadata API リファレンスをご覧ください。

安全性チェック

システムは URL に対してコンテンツ モデレーション チェックを実行し、安全基準を満たしていることを確認します。指定した URL がこのチェックに失敗すると、url_retrieval_status の値は URL_RETRIEVAL_STATUS_UNSAFE になります。

トークン数

プロンプトで指定した URL から取得されたコンテンツは、入力トークンの一部としてカウントされます。プロンプトとツールの使用量のトークン数は、モデル出力の usage_metadata オブジェクトで確認できます。出力例を次に示します。

'usage_metadata': {
  'candidates_token_count': 45,
  'prompt_token_count': 27,
  'prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 27}],
  'thoughts_token_count': 31,
  'tool_use_prompt_token_count': 10309,
  'tool_use_prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,
    'token_count': 10309}],
  'total_token_count': 10412
  }

トークンあたりの料金は使用するモデルによって異なります。詳細については、料金のページをご覧ください。

サポートされているモデル

ベスト プラクティス

  • 特定の URL を指定する: 最良の結果を得るには、モデルで分析するコンテンツへの直接 URL を指定します。モデルは、指定した URL のコンテンツのみを取得し、ネストされたリンクのコンテンツは取得しません。
  • アクセシビリティを確認する: 提供した URL が、ログインが必要なページやペイウォールの背後にあるページにリンクしていないことを確認します。
  • 完全な URL を使用する: プロトコルを含む完全な URL を指定します（例: google.com ではなく https://www.google.com）。

制限事項

  • 料金: URL から取得したコンテンツは入力トークンとしてカウントされます。レート制限と料金は、使用するモデルに基づきます。詳細については、レートの上限と料金のページをご覧ください。
  • リクエストの上限: このツールでは、1 回のリクエストで最大 20 個の URL を処理できます。
  • URL コンテンツのサイズ: 単一の URL から取得されるコンテンツの最大サイズは 34 MB です。

サポートされているコンテンツ タイプとサポートされていないコンテンツ タイプ

このツールは、次のコンテンツ タイプの URL からコンテンツを抽出できます。

  • テキスト（text/html、application/json、text/plain、text/xml、text/css、text/javascript、text/csv、text/rtf）
  • 画像（image/png、image/jpeg、image/bmp、image/webp）
  • PDF（application/pdf）

次のコンテンツ タイプはサポートされていません。

  • ペイウォール コンテンツ
  • YouTube 動画（YouTube URL の処理方法については、動画の理解をご覧ください）
  • Google ドキュメントやスプレッドシートなどの Google Workspace ファイル
  • 動画ファイルと音声ファイル

次のステップ