URL context   URL 上下文

Using the URL context tool, you can provide Gemini with URLs as additional context for your prompt. The model can then retrieve content from the URLs and use that content to inform and shape its response.
使用 URL 上下文工具，您可以为 Gemini 提供 URL 作为提示的额外上下文。然后模型可以从这些 URL 中检索内容，并利用这些内容来提供信息和塑造其响应。

This tool is useful for tasks like the following:
此工具适用于以下任务：

  • Extracting key data points or talking points from articles
    从文章中提取关键数据点或论点
  • Comparing information across multiple links
    比较多个链接中的信息
  • Synthesizing data from several sources
    整合来自多个来源的数据
  • Answering questions based on the content of a specific page or pages
    根据特定页面或多个页面的内容回答问题
  • Analyzing content for specific purposes (like writing a job description or creating test questions)
    分析内容以用于特定目的（例如撰写职位描述或创建测试题）

This guide explains how to use the URL context tool in the Gemini API.
本指南介绍了如何在 Gemini API 中使用 URL 上下文工具。

You can use the URL context tool in two main ways, by itself or in conjunction with Grounding with Google Search.
你可以通过两种主要方式使用 URL 上下文工具：单独使用，或与通过 Google 搜索进行事实核查结合使用。

URL Context Only  仅限 URL 上下文

You provide specific URLs that you want the model to analyze directly in your prompt.
你在提示中直接提供希望模型分析的特定 URL。

Example prompts:  提示示例：

Summarize this document: YOUR_URLs

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

Grounding with Google Search + URL Context
通过 Google 搜索进行事实核查 + URL 上下文

You can also enable both URL context and Grounding with Google Search together. You can enter a prompt with or without URLs. The model may first search for relevant information and then use the URL context tool to read the content of the search results for a more in-depth understanding.
你还可以同时启用 URL 上下文和通过 Google 搜索进行事实核查。你可以输入包含或不包含 URL 的提示。模型可能会首先搜索相关信息，然后使用 URL 上下文工具读取搜索结果的内容，以获得更深入的理解。

Example prompts:  提示示例：

Give me three day events 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.
PythonJavascriptREST
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch

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

url_context_tool = Tool(
    url_context = types.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)


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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash-preview-05-20",
    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();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "contents": [
          {
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json
PythonJavascriptREST
from google import genai
from google.genai.types import Tool, GenerateContentConfig, GoogleSearch

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

tools = []
tools.append(Tool(url_context=types.UrlContext))
tools.append(Tool(google_search=types.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)


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

const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash-preview-05-20",
    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();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-05-20:generateContent?key=$GOOGLE_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

For more details about Grounding with Google Search, see the overview page.
有关通过 Google 搜索进行接地的更多详细信息，请参阅 概览页面。

The model's response will be based on the content it retrieved from the URLs. If the model retrieved content from URLs, the response will include url_context_metadata. Such a response might look something like the following (parts of the response have been omitted for brevity):
模型会根据它从 URL 中检索到的内容给出响应。如果模型确实从 URL 中获取了内容，那么响应中就会包含 `url_context_metadata`。这样的响应可能长这样（为简洁起见，部分内容已省略）：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/1234567890abcdef",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/abcdef1234567890",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "YOUR_URL",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/fedcba0987654321",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            }
          ]
        }
    }
}
  • The tool will consume up to 20 URLs per request for analysis.
    该工具每次请求最多可分析 20 个 URL。
  • For best results during experimental phase, use the tool on standard web pages rather than multimedia content such as YouTube videos.
    为在实验阶段获得最佳结果，请在标准网页而非 YouTube 视频等多媒体内容上使用该工具。
  • During experimental phase, the tool is free to use. Billing to come later.
    在实验阶段，该工具免费使用。后续将开始计费。

  • The experimental release has the following quotas:
    实验版具有以下配额：

    • 1500 queries per day per project for requests made through the Gemini API
      通过 Gemini API 发出的请求，每个项目每天 1500 次查询
    • 100 queries per day per user in Google AI Studio
      在 Google AI Studio 中，每个用户每天 100 次查询