Konteksti i URL-së

Mjeti i kontekstit të URL-së ju lejon të ofroni kontekst shtesë për modelet në formën e URL-ve. Duke përfshirë URL-të në kërkesën tuaj, modeli do të qaset në përmbajtjen nga ato faqe (për sa kohë që nuk është një lloj URL-je i listuar në seksionin e kufizimeve ) për të informuar dhe përmirësuar përgjigjen e tij.

The URL context tool is useful for tasks like the following:

• Extract Data : Pull specific info like prices, names, or key findings from multiple URLs.
• Compare Documents : Analyze multiple reports, articles, or PDFs to identify differences and track trends.
• Synthesize & Create Content : Combine information from several source URLs to generate accurate summaries, blog posts, or reports.
• Analyze Code & Docs : Point to a GitHub repository or technical documentation to explain code, generate setup instructions, or answer questions.

The following example shows how to compare two recipes from different websites.

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

client = genai.Client()
model_id = "gemini-3.7-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)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.7-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();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-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

Si funksionon

Mjeti i Kontekstit të URL-së përdor një proces rikuperimi me dy hapa për të balancuar shpejtësinë, koston dhe aksesin në të dhëna të reja. Kur jepni një URL, mjeti së pari përpiqet të marrë përmbajtjen nga një memorje e brendshme e indeksit. Kjo vepron si një memorje e optimizuar shumë. Nëse një URL nuk është e disponueshme në indeks (për shembull, nëse është një faqe shumë e re), mjeti automatikisht kthehet për të bërë një rikuperim të drejtpërdrejtë. Kjo i qaset drejtpërdrejt URL-së për të marrë përmbajtjen e saj në kohë reale.

Kombinimi me mjete të tjera

You can combine the URL context tool with other tools to create more powerful workflows.

Gemini 3 models support combining built-in tools (like URL Context) with custom tools (function calling). Learn more on the tool combinations page.

Tokëzim me kërkim

Kur aktivizohen si konteksti i URL-së ashtu edhe Grounding with Google Search , modeli mund të përdorë aftësitë e tij të kërkimit për të gjetur informacione relevante në internet dhe më pas të përdorë mjetin e kontekstit të URL-së për të kuptuar më në thellësi faqet që gjen. Kjo qasje është e fuqishme për kërkesat që kërkojnë si kërkim të gjerë ashtu edhe analizë të thellë të faqeve specifike.

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

client = genai.Client()
model_id = "gemini-3.7-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)

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

const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.7-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();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.7-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

Kuptimi i përgjigjes

Kur modeli përdor mjetin e kontekstit URL, përgjigja përfshin një objekt url_context_metadata . Ky objekt rendit URL-të nga të cilat modeli ka marrë përmbajtjen dhe statusin e çdo përpjekjeje për marrjen e informacionit, gjë që është e dobishme për verifikim dhe debugging.

The following is an example of that part of the response (parts of the response have been omitted for brevity):

{
  "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"
          }
        ]
      }
    }
  ]
}

For complete detail about this object , see the UrlContextMetadata API reference .

Kontrollet e sigurisë

Sistemi kryen një kontroll moderimi të përmbajtjes në URL për të konfirmuar se ato i plotësojnë standardet e sigurisë. Nëse URL-ja që keni dhënë nuk e kalon këtë kontroll, do të merrni një url_retrieval_status URL_RETRIEVAL_STATUS_UNSAFE .

Numri i tokenëve

Përmbajtja e marrë nga URL-të që specifikoni në kërkesën tuaj llogaritet si pjesë e tokenëve të hyrjes. Mund ta shihni numrin e tokenëve për kërkesën tuaj dhe përdorimin e mjeteve në objektin usage_metadata të rezultatit të modelit. Më poshtë është një shembull rezultati:

'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
  }

Price per token depends on the model used, see the pricing page for details.

Modelet e mbështetura

Praktikat më të Mira

• Jepni URL specifike : Për rezultatet më të mira, jepni URL të drejtpërdrejta për përmbajtjen që dëshironi që modeli të analizojë. Modeli do të nxjerrë përmbajtje vetëm nga URL-të që jepni, jo përmbajtje nga lidhjet e ndërthurura.
• Check for accessibility : Verify that the URLs you provide don't lead to pages that require a login or are behind a paywall.
• Use the complete URL : Provide the full URL, including the protocol (eg, https://www.google.com instead of just google.com).

Kufizime

• Function calling: Tool use (URL Context, Grounding with Google Search, etc) with function calling is currently unsupported.
• Request limit: The tool can process up to 20 URLs per request.
• URL content size: The maximum size for content retrieved from a single URL is 34MB.
• Qasje publike: URL-të duhet të jenë të arritshme publikisht në internet. Adresat localhost (p.sh., localhost, 127.0.0.1), rrjetet private dhe shërbimet e tunelimit (p.sh., ngrok, pinggy) nuk mbështeten.

Llojet e përmbajtjes së mbështetur dhe të pambështetur

The tool can extract content from URLs with the following content types:

• Text (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)
• Image (image/png, image/jpeg, image/bmp, image/webp)
• PDF (aplikacion/pdf)

Llojet e mëposhtme të përmbajtjes nuk mbështeten:

• Përmbajtje me pagesë
• YouTube videos (See video understanding to learn how to process YouTube URLs)
• Google workspace files like Google docs or spreadsheets
• Skedarët video dhe audio

Çfarë vjen më pas

• Explore the URL context cookbook for more examples.