URL context

Mit dem Tool „URL-Kontext“ können Sie den Modellen zusätzlichen Kontext in Form von URLs zur Verfügung stellen. Wenn Sie URLs in Ihre Anfrage einfügen, greift das Modell auf die Inhalte dieser Seiten zu (sofern es sich nicht um einen im Abschnitt zu Einschränkungen aufgeführten URL-Typ handelt), um seine Antwort zu ergänzen und zu verbessern.

Das Tool „URL-Kontext“ ist für Aufgaben wie die folgenden nützlich:

  • Daten extrahieren: Bestimmte Informationen wie Preise, Namen oder wichtige Erkenntnisse aus mehreren URLs abrufen.
  • Dokumente vergleichen: Analysieren Sie mehrere Berichte, Artikel oder PDFs, um Unterschiede zu erkennen und Trends zu verfolgen.
  • Inhalte zusammenfassen und erstellen: Informationen aus mehreren Quell-URLs kombinieren, um genaue Zusammenfassungen, Blogposts oder Berichte zu erstellen.
  • Code und Dokumente analysieren: Verweisen Sie auf ein GitHub-Repository oder eine technische Dokumentation, um Code zu erläutern, Einrichtungsanleitungen zu generieren oder Fragen zu beantworten.

Im folgenden Beispiel wird gezeigt, wie Sie zwei Rezepte von verschiedenen Websites vergleichen.

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

Funktionsweise

Das Tool „URL-Kontext“ verwendet einen zweistufigen Abrufprozess, um Geschwindigkeit, Kosten und Zugriff auf aktuelle Daten in Einklang zu bringen. Wenn Sie eine URL angeben, versucht das Tool zuerst, den Inhalt aus einem internen Indexcache abzurufen. Dies dient als hochgradig optimierter Cache. Wenn eine URL nicht im Index verfügbar ist (z. B. weil es sich um eine sehr neue Seite handelt), führt das Tool automatisch einen Live-Abruf durch. Dadurch wird direkt auf die URL zugegriffen, um die Inhalte in Echtzeit abzurufen.

Sie können das Tool „URL-Kontext“ mit anderen Tools kombinieren, um leistungsstärkere Workflows zu erstellen.

Wenn sowohl der URL-Kontext als auch Mit der Google Suche fundieren aktiviert sind, kann das Modell seine Suchfunktionen nutzen, um relevante Informationen online zu finden, und dann das Tool „URL-Kontext“ verwenden, um die gefundenen Seiten besser zu verstehen. Dieser Ansatz ist besonders nützlich für Prompts, die sowohl eine breite Suche als auch eine detaillierte Analyse bestimmter Seiten erfordern.

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

Antwort verstehen

Wenn das Modell das Tool für den URL-Kontext verwendet, enthält die Antwort ein url_context_metadata-Objekt. Dieses Objekt enthält die URLs, aus denen das Modell Inhalte abgerufen hat, sowie den Status jedes Abrufvorgangs. Das ist nützlich für die Überprüfung und das Debugging.

Im Folgenden sehen Sie ein Beispiel für diesen Teil der Antwort (Teile der Antwort wurden aus Gründen der Übersichtlichkeit weggelassen):

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

Weitere Informationen zu diesem Objekt finden Sie in der UrlContextMetadata API-Referenz.

Sicherheitschecks

Das System führt eine Inhaltsmoderationsprüfung der URL durch, um zu bestätigen, dass sie den Sicherheitsstandards entspricht. Wenn die von Ihnen angegebene URL diese Prüfung nicht besteht, erhalten Sie eine url_retrieval_status von URL_RETRIEVAL_STATUS_UNSAFE.

Tokenanzahl

Die Inhalte, die von den URLs abgerufen werden, die Sie in Ihrem Prompt angeben, werden als Teil der Eingabetokens gezählt. Die Anzahl der Tokens für Ihren Prompt und die Nutzung von Tools finden Sie im usage_metadata-Objekt der Modellausgabe. Hier ein Beispiel für die Ausgabe:

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

Der Preis pro Token hängt vom verwendeten Modell ab. Weitere Informationen finden Sie auf der Preisseite.

Unterstützte Modelle

Best Practices

  • Geben Sie bestimmte URLs an: Die besten Ergebnisse erzielen Sie, wenn Sie direkte URLs zu den Inhalten angeben, die das Modell analysieren soll. Das Modell ruft nur Inhalte von den von Ihnen angegebenen URLs ab, nicht von verschachtelten Links.
  • Zugänglichkeit prüfen: Prüfen Sie, ob die von Ihnen angegebenen URLs zu Seiten führen, für die eine Anmeldung erforderlich ist oder die sich hinter einer Paywall befinden.
  • Vollständige URL verwenden: Geben Sie die vollständige URL einschließlich des Protokolls an (z.B. https://www.google.com statt nur google.com).

Beschränkungen

  • Preise: Inhalte, die über URLs abgerufen werden, zählen als Eingabetokens. Ratenbegrenzung und Preise richten sich nach dem verwendeten Modell. Weitere Informationen finden Sie auf den Seiten Ratenbeschränkungen und Preise.
  • Anfragelimit: Das Tool kann bis zu 20 URLs pro Anfrage verarbeiten.
  • Größe von URL-Inhalten: Die maximale Größe für Inhalte, die von einer einzelnen URL abgerufen werden, beträgt 34 MB.

Unterstützte und nicht unterstützte Inhaltstypen

Das Tool kann Inhalte aus URLs mit den folgenden Inhaltstypen extrahieren:

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

Die folgenden Inhaltstypen werden nicht unterstützt:

  • Paywall-Inhalte
  • YouTube-Videos (Informationen zum Verarbeiten von YouTube-URLs finden Sie unter Video-Understanding.)
  • Google Workspace-Dateien wie Google-Dokumente oder ‑Tabellen
  • Video- und Audiodateien

Nächste Schritte