URL-Kontext

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 URL-Typ handelt, der im Abschnitt zu denBeschränkungenaufgeführt ist), um seine Antwort zu informieren 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 Ergebnisse aus mehreren URLs abrufen.
• Dokumente vergleichen: Mehrere Berichte, Artikel oder PDFs analysieren, um Unterschiede zu ermitteln und Trends zu verfolgen.
• Inhalte zusammenführen und erstellen: Informationen aus mehreren Quell-URLs kombinieren, um genaue Zusammenfassungen, Blogposts oder Berichte zu erstellen.
• Code und Dokumente analysieren: Auf ein GitHub-Repository oder eine technische Dokumentation verweisen, um Code zu erklären, Einrichtungsanleitungen zu erstellen oder Fragen zu beantworten.

Im folgenden Beispiel werden zwei Rezepte von verschiedenen Websites verglichen.

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    tools=[{"type": "url_context"}]
)

# Print the model's text response and its source annotations
for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nSources:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            print(f"  - {annotation.title}: {annotation.url}")

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "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: [{ type: "url_context" }]
  });

  // Print the model's text response and its source annotations
  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') {
          console.log(contentBlock.text);
          if (contentBlock.annotations) {
            console.log("\nSources:");
            for (const annotation of contentBlock.annotations) {
              if (annotation.type === 'url_citation') {
                console.log(`  - ${annotation.title}: ${annotation.url}`);
              }
            }
          }
        }
      }
    }
  }
}

await main();

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "input": "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": [{"type": "url_context"}]
  }'

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, die Inhalte aus einem internen Index-Cache abzurufen. Dieser dient als hochoptimierter Cache. Wenn eine URL nicht im Index verfügbar ist (z. B. wenn es sich um eine sehr neue Seite handelt), greift das Tool automatisch auf einen Live-Abruf zurück. Dabei wird direkt auf die URL zugegriffen, um die Inhalte in Echtzeit abzurufen.

Kombination mit anderen Tools

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

Gemini 3-Modelle unterstützen die Kombination von integrierten Tools (z. B. „URL-Kontext“) mit benutzerdefinierten Tools (Funktionsaufruf). Weitere Informationen finden Sie auf der Seite zu Toolkombinationen.

Fundierung mit der Suche

Wenn sowohl „URL-Kontext“ als auch „Fundierung mit der Google Suche“ aktiviert sind, kann das Modell seine Suchfunktionen verwenden, um relevante Informationen online zu finden. Anschließend kann es mit dem Tool „URL-Kontext“ ein tieferes Verständnis der gefundenen Seiten erlangen. Dieser Ansatz ist leistungsstark für Prompts, die sowohl eine breite Suche als auch eine detaillierte Analyse bestimmter Seiten erfordern.

# This will only work for SDK newer than 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="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=[
        {"type": "url_context"},
        {"type": "google_search"}
    ]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "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: [
      { type: "url_context" },
      { type: "google_search" }
    ]
  });

  for (const step of interaction.steps) {
    if (step.type === 'model_output') {
      for (const contentBlock of step.content) {
        if (contentBlock.type === 'text') console.log(contentBlock.text);
      }
    }
  }
}

await main();

# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
      "model": "gemini-3.5-flash",
      "input": "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": [
          {"type": "url_context"},
          {"type": "google_search"}
      ]
  }'

Antwort verstehen

Wenn das Modell das Tool „URL-Kontext“ verwendet, enthält die Textantwort Inline-Annotationen vom Typ url_citation im Textinhaltsblock. Jede Annotation verknüpft ein Segment des Antworttexts (über start_index und end_index) mit der Quell-URL, aus der es abgeleitet wurde. Dies ist die primäre Methode, um Zitate in Ihrer Anwendung zu präsentieren. Wie Sie sie extrahieren, erfahren Sie im Hauptbeispiel oben.

Die Antwort enthält auch einen Schritt vom Typ url_context_result mit Metadaten zu jedem URL-Abrufversuch (Status, abgerufene URL). Dies ist hauptsächlich für das Debugging nützlich.

Sicherheitschecks

Das System führt eine Überprüfung der Inhaltsmoderation für URLs durch, um zu bestätigen, dass sie den Sicherheitsstandards entsprechen. Wenn eine URL diese Überprüfung nicht besteht, wird im entsprechenden url_context_result Schritt der status auf "unsafe" gesetzt.

Tokenanzahl

Die Inhalte, die von den in Ihrem Prompt angegebenen URLs abgerufen werden, werden als Teil der Eingabetokens gezählt. Die Tokenanzahl finden Sie im Objekt usage der Interaktion. Hier ein Beispiel:

'usage': {
  'output_tokens': 45,
  'input_tokens': 27,
  'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],
  'thoughts_tokens': 31,
  'tool_use_input_tokens': 10309,
  'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],
  'total_tokens': 10412
}

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

Unterstützte Modelle

Best Practices

• Bestimmte URLs angeben: 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 nicht 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 an, einschließlich des Protokolls (z.B. https://www.google.com anstelle von google.com).

Beschränkungen

• Anfragelimit: Das Tool kann bis zu 20 URLs pro Anfrage verarbeiten.
• Größe der URL-Inhalte: Die maximale Größe für Inhalte, die von einer einzelnen URL abgerufen werden, beträgt 34 MB.
• Öffentliche Zugänglichkeit: Die URLs müssen öffentlich im Web zugänglich sein. Localhost-Adressen (z.B. localhost, 127.0.0.1), private Netzwerke und Tunneling-Dienste (z.B. ngrok, pinggy) werden nicht unterstützt.
• Nur Gemini API: „URL-Kontext“ ist nur in der Gemini API verfügbar, nicht über die Gemini Enterprise Agent Platform.

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 Docs oder Google Sheets
• Video- und Audiodateien