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 上下文工具。
Use URL context 使用 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 .
Code examples with URL context only
仅包含 URL 上下文的代码示例
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
Code examples with Grounding with Google Search
包含 Google 搜索接地功能的代码示例
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 搜索进行接地的更多详细信息,请参阅
概览页面。
Contextual response 上下文响应
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">
}
]
}
}
}
Supported models 支持的模型
- gemini-2.5-pro-preview-06-05
- gemini-2.5-flash-preview-05-20
- gemini-2.0-flash
- gemini-2.0-flash-live-001
Limitations 局限性
- 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 次查询
- 1500 queries per day per project for requests made through the Gemini API