Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

URL コンテキスト

URL コンテキストツールを使用すると、プロンプトの追加コンテキストとして URL を Gemini に提供できます。モデルは、URL からコンテンツを取得し、そのコンテンツを使用してレスポンスを形成します。

このツールは、次のようなタスクに役立ちます。

記事からの重要なデータポイントや話のポイントの抽出
マルチリンク間での情報の比較
複数のソースからのデータの統合
特定のページの内容に基づいて質問に回答する
特定の目的（求人情報の作成やテスト問題の作成など）のためのコンテンツの分析

データを取得するために使用されるインデックスが必ずしも最新ではないため、一部の情報が古い可能性があります。

このガイドでは、Gemini API で URL コンテキストツールを使用する方法について説明します。

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

次のモデルは URL コンテキストをサポートしています。

クリックしてサポートされているモデルを開く

URL コンテキストを使用する

URL コンテキストツールは、単独で使用する方法と、Google 検索でのグラウンディングと組み合わせて使用する方法の 2 つの主な方法で使用できます。

URL コンテキストのみ

モデルで分析する特定の URL をプロンプトで直接指定できます。

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

Python

GenerateContent API

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

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-3.5-flash"

url_context_tool = Tool(
    url_context = UrlContext
)

response = client.models.generate_content(
    model=model_id,
    contents="Compare recipes from YOUR_URL1 and YOUR_URL2",
    config=GenerateContentConfig(
        tools=[url_context_tool],
        response_modalities=["TEXT"],
    )
)

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

Interactions API

from google import genai

client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Compare recipes from YOUR_URL1 and YOUR_URL2",
    tools=[{"type": "url_context"}],
)

print(interaction.output_text)

# Get URLs retrieved for context
for step in interaction.steps:
    if step.type == "url_context_result":
        for res in step.result:
            print(f"URL: {res.url} (Status: {res.status})")

JavaScript

GenerateContent API

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: [
        "Compare recipes from YOUR_URL1 and YOUR_URL2",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

Interactions API

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Compare recipes from YOUR_URL1 and YOUR_URL2",
    tools: [{ type: "url_context" }],
  });

  console.log(interaction.output_text);

  for (const step of interaction.steps) {
    if (step.type === "url_context_result") {
      console.log(step.result);
    }
  }
}

await main();

REST

GenerateContent API

リクエストのデータを使用する前に、次のように置き換えます。

GOOGLE_CLOUD_PROJECT: 実際のプロジェクト ID。
YOUR_URL1: コンテキストを取得する最初の URL。
YOUR_URL2: コンテキストを取得する 2 番目の URL。

HTTP メソッドと URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent

リクエストの本文（JSON）:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
        }
      ]
    }
  ],
  "tools": [
    {
      "url_context": {}
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

Interactions API

リクエストのデータを使用する前に、次のように置き換えます。

GOOGLE_CLOUD_PROJECT: 実際のプロジェクト ID。
YOUR_URL1: コンテキストを取得する最初の URL。
YOUR_URL2: コンテキストを取得する 2 番目の URL。

HTTP メソッドと URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions

リクエストの本文（JSON）:

{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Compare recipes from YOUR_URL1 and YOUR_URL2"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "url_context"
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content

URL コンテキストを使用した Google 検索によるグラウンディング

URL コンテキストと Google 検索によるグラウンディングの両方を有効にして、URL を含むプロンプトまたは URL を含まないプロンプトを使用することもできます。モデルは、まず関連情報を検索し、URL コンテキストツールを使用して検索結果の内容を読み取り、より詳細な情報を取得できます。

この機能は試験運用版であり、API バージョン v1beta1 で使用できます。

プロンプトの例

Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.

Recommend 3 books for beginners to read to learn more about the latest YOUR_SUBJECT.

Python

GenerateContent API

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

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-3.5-flash"

tools = []
tools.append(Tool(url_context=UrlContext))
tools.append(Tool(google_search=GoogleSearch))

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,
        response_modalities=["TEXT"],
    )
)

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

Interactions API

from google import genai

client = genai.Client(
    enterprise=True,
    project="GOOGLE_CLOUD_PROJECT",
    location="global",
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.",
    tools=[
        {"type": "url_context"},
        {"type": "google_search"},
    ],
)

print(interaction.output_text)

# Get URLs retrieved for context
for step in interaction.steps:
    if step.type == "url_context_result":
        for res in step.result:
            print(f"URL: {res.url} (Status: {res.status})")

JavaScript

GenerateContent API

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1beta1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: [
        "Give me a three day event 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();

Interactions API

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  enterprise: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
});

async function main() {
  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to be taken care of considering weather and commute.",
    tools: [
      { type: "url_context" },
      { type: "google_search" },
    ],
  });

  console.log(interaction.output_text);

  for (const step of interaction.steps) {
    if (step.type === "url_context_result") {
      console.log(step.result);
    }
  }
}

await main();

REST

GenerateContent API

リクエストのデータを使用する前に、次のように置き換えます。

GOOGLE_CLOUD_PROJECT: 実際のプロジェクト ID。
YOUR_URL: コンテキストを取得する URL。

HTTP メソッドと URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent

リクエストの本文（JSON）:

{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."
        }
      ]
    }
  ],
  "tools": [
    {
      "url_context": {}
    },
    {
      "google_search": {}
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content

Interactions API

リクエストのデータを使用する前に、次のように置き換えます。

GOOGLE_CLOUD_PROJECT: 実際のプロジェクト ID。
YOUR_URL: コンテキストを取得する URL。

HTTP メソッドと URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions

リクエストの本文（JSON）:

{
  "model": "gemini-3.8-flash",
  "input": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "url_context"
    },
    {
      "type": "google_search"
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions"

PowerShell

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/interactions" | Select-Object -Expand Content

Google 検索によるグラウンディングの詳細については、概要ページをご覧ください。

URL コンテキストを使用したエンタープライズ向けウェブグラウンディング

特定のコンプライアンスのニーズがある場合や、医療、金融、公共部門などの規制対象の業界に属している場合は、URL コンテキストとエンタープライズ向けウェブグラウンディングの両方を有効にできます。エンタープライズ向けウェブグラウンディングで使用されるウェブインデックスは、Google 検索で利用可能なサブセットを使用するため、Google 検索による標準のグラウンディングインデックスよりも制限が厳しくなっています。

エンタープライズ向けウェブグラウンディングの詳細については、エンタープライズ向けウェブグラウンディングページをご覧ください。

コンテキストに応じたレスポンス

モデルのレスポンスは、URL から取得したコンテンツに基づきます。モデルが URL からコンテンツを取得した場合、レスポンスには url_context_metadata が含まれます。このようなレスポンスは次のようになります（簡潔にするため、レスポンスの一部は省略しています）。

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

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

ライブ取得

URL コンテキストツールは情報を最新の状態に保つため、ウェブページの公開版を取得します。

ウェブページのコンテンツを効率的に取得するため、URL コンテキストツールは、速度、コスト、そして最新情報へのアクセスのバランスを取るように設計された 2 段階プロセスを使用します。

インデックス登録済みコンテンツの取得: 最初のステージです。URL を指定すると、ツールはまず Googleの広範で高度に最適化されたウェブインデックスからコンテンツを取得しようとします。この方法では、膨大な量のクロールされたウェブページにすばやくアクセスできます。
ライブ取得のフォールバック: これは 2 番目のステージです。特定の URL のコンテンツがインデックス登録されていない場合（たとえばページが新しく、まだインデックス登録されていない場合）、このツールは自動的にライブ取得を実行します。このフォールバックメカニズムは URL に直接アクセスし、コンテンツの最新バージョンをリアルタイムで取得できます。

安全チェック

システムは URL が安全基準を満たしていることを確認するため、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
  }

トークンあたりの料金は、使用するモデルによって異なります。詳細については、Gemini Enterprise Agent Platform での AI モデルの構築とデプロイの費用をご覧ください。

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

URL コンテキストツールは、次のコンテンツタイプの 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`

URL コンテキストツールでは、次のコンテンツタイプはサポートされていません。

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

制限事項

URL コンテキストツールでは、リクエストごとに最大 20 個の URL を分析のために消費します。
試験運用期間中は、YouTube 動画などのマルチメディアコンテンツではなく、標準的なウェブページでこのツールを使用することをおすすめします。

URL コンテキスト コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

クリックしてサポートされているモデルを開く

URL コンテキストを使用する

URL コンテキストのみ

Python

GenerateContent API

Interactions API

JavaScript

GenerateContent API

Interactions API

REST

GenerateContent API

curl

PowerShell

Interactions API

curl

PowerShell

URL コンテキストを使用した Google 検索によるグラウンディング

Python

GenerateContent API

Interactions API

JavaScript

GenerateContent API

Interactions API

REST

GenerateContent API

curl

PowerShell

Interactions API

curl

PowerShell

URL コンテキストを使用したエンタープライズ向けウェブ グラウンディング

コンテキストに応じたレスポンス

ライブ取得

安全チェック

トークン数

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

制限事項

URL コンテキスト

URL コンテキストを使用したエンタープライズ向けウェブグラウンディング

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