URL context

網址脈絡工具可讓您以網址形式為模型提供額外脈絡。在要求中加入網址後，模型會存取這些網頁的內容 (只要網址類型未列於限制一節)，藉此提供更完善的回覆。

網址背景資訊工具適用於下列工作：

擷取資料：從多個網址擷取特定資訊，例如價格、名稱或重要發現。
比較文件：分析多份報表、文章或 PDF，找出差異並追蹤趨勢。
彙整及建立內容：整合多個來源網址的資訊，生成準確的摘要、網誌文章或報告。
分析程式碼和文件：指向 GitHub 存放區或技術文件，說明程式碼、產生設定操作說明，或回答問題。

以下範例說明如何比較不同網站的兩道食譜。

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

運作方式

網址內容工具採用兩步驟的擷取程序，兼顧速度、成本和最新資料存取權。提供網址後，這項工具會先嘗試從內部索引快取擷取內容。這項功能可做為經過高度最佳化的快取。如果網址不在索引中 (例如網頁剛發布)，工具會自動改為即時擷取。這項工具會直接存取網址，即時擷取內容。

與其他工具搭配使用

您可以將網址內容工具與其他工具結合，建立更強大的工作流程。

以搜尋結果為參考依據

同時啟用網址脈絡和 Google 搜尋建立基準後，模型就能使用搜尋功能在網路上尋找相關資訊，然後使用網址脈絡工具深入瞭解找到的網頁。對於需要廣泛搜尋和深入分析特定網頁的提示，這種做法非常有效。

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_context_metadata 物件。這個物件會列出模型擷取內容的網址，以及每次擷取嘗試的狀態，有助於驗證和偵錯。

以下是回應中該部分的範例 (為簡潔起見，部分回應已省略)：

{
  "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_retrieval_status 的 URL_RETRIEVAL_STATUS_UNSAFE。

權杖數量

系統會將從提示中指定網址擷取的內容，計為輸入權杖。您可以在模型輸出內容的 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
  }

每個權杖的價格取決於使用的模型，詳情請參閱定價頁面。

支援的模型

最佳做法

提供特定網址：為獲得最佳結果，請提供要模型分析的內容的直接網址。模型只會從您提供的網址擷取內容，不會從巢狀連結擷取任何內容。
檢查存取方式：確認提供的網址不會導向需要登入或位於付費牆後的網頁。
使用完整網址：請提供完整網址，包括通訊協定 (例如 https://www.google.com，而不是只有 google.com)。

限制

價格：從網址擷取的內容會計為輸入權杖。使用頻率限制和價格取決於所用模型。詳情請參閱速率限制和定價頁面。
要求限制：這項工具每次要求最多可處理 20 個網址。
網址內容大小：從單一網址擷取的內容大小上限為 34 MB。

支援及不支援的內容類型

這項工具可從下列內容類型的網址中擷取內容：

文字 (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 網址)
Google Workspace 檔案，例如 Google 文件或試算表
影片和音訊檔案

後續步驟

如需更多範例，請參閱 URL 內容食譜。