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 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: Sie können mehrere Berichte, Artikel oder PDFs analysieren, um Unterschiede zu erkennen und Trends zu verfolgen.
• Inhalte zusammenfassen und erstellen: Informationen aus mehreren Quell-URLs kombinieren, um genaue Zusammenfassungen, Blogbeiträge 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 können.

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-flash-preview",
    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}")

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    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();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "gemini-3-flash-preview",
      "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, den Inhalt aus einem internen Indexcache abzurufen. Dies dient als hochgradig optimierter Cache. Wenn eine URL nicht im Index verfügbar ist (z. B. bei einer sehr neuen Seite), führt das Tool automatisch einen Live-Abruf durch. Dadurch wird direkt auf die URL zugegriffen, um die Inhalte in Echtzeit abzurufen.

Mit anderen Tools kombinieren

Sie können das Tool für den 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 zu Tool-Kombinationen

Fundierung mit der Suche

Wenn sowohl der URL-Kontext als auch Fundierung mit der Google Suche 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.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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)

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

const client = new GoogleGenAI({});

async function main() {
  const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    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();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "gemini-3-flash-preview",
      "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 für den URL-Kontext verwendet, enthält die Textantwort Inline-url_citation-Anmerkungen im Textinhaltsblock. Jede Anmerkung verknüpft einen Abschnitt des Antworttexts (über start_index und end_index) mit der Quell-URL, aus der er abgeleitet wurde. Dies ist die primäre Methode, um Zitationen in Ihrer Anwendung anzuzeigen. Im Hauptbeispiel oben erfahren Sie, wie Sie sie extrahieren.

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

Sicherheitschecks

Das System führt eine Inhaltsmoderationsprüfung für URLs durch, um zu bestätigen, dass sie den Sicherheitsstandards entsprechen. Wenn eine URL diese Prüfung nicht besteht, wird im entsprechenden url_context_result-Schritt ein status von "unsafe" angezeigt.

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 finden Sie im usage-Objekt 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

• 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

• Funktionsaufrufe: Die Verwendung von Tools (URL-Kontext, Fundierung mit der Google Suche usw.) mit Funktionsaufrufen wird derzeit nicht unterstützt.
• 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.
• Ö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: Der 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-Dokumente oder ‑Tabellen
• Video- und Audiodateien