URL bağlamı

URL Bağlamı aracı, modellere URL biçiminde ek bağlam sağlamanıza olanak tanır. İsteğinize URL'leri dahil ettiğinizde model, yanıtını bilgilendirmek ve geliştirmek için bu sayfalardaki içeriğe erişir (sınırlamalar bölümünde listelenen bir URL türü olmadığı sürece).

URL Bağlamı aracı aşağıdaki gibi görevler için kullanışlıdır:

  • Verileri ayıklama: Birden fazla URL'den fiyat, ad veya önemli bulgular gibi belirli bilgileri alın.
  • Belgeleri Karşılaştırma: Farklılıkları belirlemek ve trendleri takip etmek için birden fazla raporu, makaleyi veya PDF'yi analiz edin.
  • İçerik sentezleme ve oluşturma: Doğru özetler, blog yayınları veya raporlar oluşturmak için birden fazla kaynak URL'deki bilgileri birleştirin.
  • Kod ve Doküman Analizi: Kodları açıklamak, kurulum talimatları oluşturmak veya soruları yanıtlamak için bir GitHub deposunu ya da teknik dokümanları referans gösterin.

Aşağıdaki örnekte, farklı web sitelerinden iki yemek tarifinin nasıl karşılaştırılacağı gösterilmektedir.

Python

# 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.8-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}")

JavaScript

// 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.8-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();

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

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

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(
                fmt.Sprintf("Compare the ingredients and cooking times from the recipes at %s and %s", url1, url2),
            ),
            Tools: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Print the model's text response and its source annotations
    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                    if len(contentBlock.TextContent.Annotations) > 0 {
                        fmt.Println("\nSources:")
                        for _, annotation := range contentBlock.TextContent.Annotations {
                            if annotation.URLCitation != nil {
                                fmt.Printf("  - %s: %s\n", annotation.URLCitation.GetTitle(), annotation.URLCitation.GetURL())
                            }
                        }
                    }
                }
            }
        }
    }
}

REST

# 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" \
  -d '{
      "model": "gemini-3.8-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"}]
  }'

İşleyiş şekli

URL Bağlamı aracı; hız, maliyet ve güncel verilere erişim arasında denge kurmak için iki adımlı bir alma işlemi kullanır. Bir URL sağladığınızda araç, öncelikle içeriği dahili bir dizin önbelleğinden getirmeye çalışır. Bu, yüksek düzeyde optimize edilmiş bir önbellek görevi görür. Bir URL dizinde mevcut değilse (örneğin, çok yeni bir sayfaysa) araç otomatik olarak canlı getirme işlemine geri döner. Bu araç, içeriğini gerçek zamanlı olarak almak için doğrudan URL'ye erişir.

Daha güçlü iş akışları oluşturmak için URL Bağlamı aracını diğer araçlarla birleştirebilirsiniz.

Gemini 3 modelleri, yerleşik araçların (ör. URL Bağlamı) özel araçlarla (işlev çağrısı) birleştirilmesini destekler. Araç kombinasyonları sayfasından daha fazla bilgi edinin.

Hem URL Bağlamı hem de Google Arama ile Temellendirme etkinleştirildiğinde model, arama özelliklerini kullanarak internette alakalı bilgileri bulabilir ve ardından URL Bağlamı aracını kullanarak bulduğu sayfaları daha ayrıntılı bir şekilde anlayabilir. Bu yaklaşım, hem geniş kapsamlı arama hem de belirli sayfaların ayrıntılı analizini gerektiren istemler için çok etkilidir.

Python

# 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.8-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)

JavaScript

// 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.8-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();

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("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: []interactions.Tool{
                interactions.NewTool(interactions.URLContext{}),
                interactions.NewTool(interactions.GoogleSearch{}),
            },
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, step := range res.Interaction.Steps {
        if step.ModelOutputStep != nil {
            for _, contentBlock := range step.ModelOutputStep.Content {
                if contentBlock.TextContent != nil {
                    fmt.Println(contentBlock.TextContent.Text)
                }
            }
        }
    }
}

REST

# 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" \
  -d '{
      "model": "gemini-3.8-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"}
      ]
  }'

Yanıtı anlama

Model, URL Bağlamı aracını kullandığında metin yanıtı, metin içerik bloğunda satır içi url_citation ek açıklamalar içerir. Her ek açıklama, yanıt metninin bir bölümünü (start_index ve end_index aracılığıyla) türetildiği kaynak URL'ye bağlar. Bu, uygulamanızda alıntıları göstermenin birincil yoludur. Bunları nasıl çıkaracağınızı öğrenmek için yukarıdaki ana örneğe bakın.

Yanıtta ayrıca her URL alma denemesiyle ilgili meta verilerin (durum, alınan URL) olduğu bir url_context_result adımı yer alır. Bu, özellikle hata ayıklama için kullanışlıdır.

Güvenlik kontrolleri

Sistem, URL'lerin güvenlik standartlarını karşıladığını doğrulamak için içerik denetimi yapar. Bir URL bu kontrolde başarısız olursa ilgili url_context_result adımında "unsafe" üzerinden status gösterilir.

Jeton sayısı

İsteminizde belirttiğiniz URL'lerden alınan içerikler, giriş jetonları kapsamında sayılır. Jeton sayısını etkileşimin usage nesnesinde görebilirsiniz. Örnek:

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

Parça başına fiyat, kullanılan modele bağlıdır. Ayrıntılar için fiyatlandırma sayfasına bakın.

Desteklenen modeller

Model URL Bağlamı
Gemini 4 Argon ✔️
Gemini 3.8 Flash ✔️
Gemini 3.6 Flash ✔️
Gemini 3.5 Flash-Lite ✔️
Gemini 3.1 Pro Preview ✔️
Gemini 3.1 Flash-Lite ✔️
Gemini 3 Flash Preview ✔️
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.5 Flash-Lite ✔️

En İyi Uygulamalar

  • Belirli URL'ler sağlama: En iyi sonuçları elde etmek için modelin analiz etmesini istediğiniz içeriğe doğrudan giden URL'ler sağlayın. Model yalnızca sağladığınız URL'lerdeki içerikleri alır, iç içe yerleştirilmiş bağlantılardaki içerikleri almaz.
  • Erişilebilirliği kontrol edin: Sağladığınız URL'lerin, giriş yapmayı gerektiren veya ödeme duvarının arkasında bulunan sayfalara yönlendirmediğinden emin olun.
  • Tam URL'yi kullanın: Protokolü de içeren tam URL'yi girin (ör. yalnızca google.com yerine https://www.google.com).

Sınırlamalar

  • İstek sınırı: Araç, istek başına en fazla 20 URL işleyebilir.
  • URL içerik boyutu: Tek bir URL'den alınan içerik için maksimum boyut 34 MB'tır.
  • Herkese açık erişim: URL'ler web'de herkesin erişimine açık olmalıdır. Localhost adresleri (ör. localhost, 127.0.0.1), özel ağlar ve tünel oluşturma hizmetleri (ör. ngrok, pinggy) desteklenmez.

Desteklenen ve desteklenmeyen içerik türleri

Araç, aşağıdaki içerik türlerine sahip URL'lerden içerik ayıklayabilir:

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

Aşağıdaki içerik türleri desteklenmez:

  • Ödeme duvarlı içerik
  • YouTube videoları (YouTube URL'lerinin nasıl işleneceğini öğrenmek için videoları anlama bölümüne bakın)
  • Google Dokümanlar veya e-tablolar gibi Google Workspace dosyaları
  • Video ve ses dosyaları