URL context

Alat konteks URL memungkinkan Anda memberikan konteks tambahan ke model dalam bentuk URL. Dengan menyertakan URL dalam permintaan Anda, model akan mengakses konten dari halaman tersebut (selama bukan jenis URL yang tercantum di bagian batasan) untuk menginformasikan dan meningkatkan kualitas responsnya.

Alat konteks URL berguna untuk tugas seperti berikut:

  • Ekstrak Data: Tarik info spesifik seperti harga, nama, atau temuan utama dari beberapa URL.
  • Bandingkan Dokumen: Menganalisis beberapa laporan, artikel, atau PDF untuk mengidentifikasi perbedaan dan melacak tren.
  • Mensintesis & Membuat Konten: Gabungkan informasi dari beberapa URL sumber untuk membuat ringkasan, postingan blog, atau laporan yang akurat.
  • Analisis Kode & Dokumen: Arahkan ke repositori GitHub atau dokumentasi teknis untuk menjelaskan kode, membuat petunjuk penyiapan, atau menjawab pertanyaan.

Contoh berikut menunjukkan cara membandingkan dua resep dari situs yang berbeda.

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

Cara kerjanya

Alat Konteks URL menggunakan proses pengambilan dua langkah untuk menyeimbangkan kecepatan, biaya, dan akses ke data baru. Saat Anda memberikan URL, alat ini pertama-tama akan mencoba mengambil konten dari cache indeks internal. Cache ini berfungsi sebagai cache yang sangat dioptimalkan. Jika URL tidak tersedia di indeks (misalnya, jika URL tersebut adalah halaman yang sangat baru), alat akan otomatis kembali melakukan pengambilan langsung. Alat ini mengakses URL secara langsung untuk mengambil kontennya secara real time.

Anda dapat menggabungkan alat konteks URL dengan alat lain untuk membuat alur kerja yang lebih efektif.

Jika konteks URL dan Perujukan dengan Google Penelusuran diaktifkan, model dapat menggunakan kemampuan penelusurannya untuk menemukan informasi yang relevan secara online, lalu menggunakan alat konteks URL untuk mendapatkan pemahaman yang lebih mendalam tentang halaman yang ditemukannya. Pendekatan ini efektif untuk perintah yang memerlukan penelusuran luas dan analisis mendalam halaman tertentu.

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

Memahami respons

Saat model menggunakan alat konteks URL, respons akan menyertakan objek url_context_metadata. Objek ini mencantumkan URL tempat model mengambil konten dan status setiap upaya pengambilan, yang berguna untuk verifikasi dan proses debug.

Berikut adalah contoh bagian respons tersebut (bagian respons telah dihilangkan agar lebih ringkas):

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

Untuk mengetahui detail lengkap tentang objek ini , lihat referensi API UrlContextMetadata.

Pemeriksaan keamanan

Sistem melakukan pemeriksaan moderasi konten pada URL untuk mengonfirmasi bahwa URL tersebut memenuhi standar keamanan. Jika URL yang Anda berikan gagal dalam pemeriksaan ini, Anda akan mendapatkan url_retrieval_status URL_RETRIEVAL_STATUS_UNSAFE.

Jumlah token

Konten yang diambil dari URL yang Anda tentukan dalam perintah dihitung sebagai bagian dari token input. Anda dapat melihat jumlah token untuk perintah dan penggunaan alat di objek usage_metadata output model. Berikut adalah contoh output:

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

Harga per token bergantung pada model yang digunakan. Lihat halaman harga untuk mengetahui detailnya.

Model yang didukung

Praktik Terbaik

  • Berikan URL spesifik: Untuk mendapatkan hasil terbaik, berikan URL langsung ke konten yang ingin Anda analisis oleh model. Model hanya akan mengambil konten dari URL yang Anda berikan, bukan konten dari link bertingkat.
  • Periksa aksesibilitas: Pastikan URL yang Anda berikan tidak mengarah ke halaman yang memerlukan login atau berada di balik penghalang konten berbayar.
  • Gunakan URL lengkap: Berikan URL lengkap, termasuk protokolnya (misalnya, https://www.google.com, bukan hanya google.com).

Batasan

  • Harga: Konten yang diambil dari URL dihitung sebagai token input. Batas frekuensi permintaan dan harga didasarkan pada model yang digunakan. Lihat halaman batas kecepatan dan harga untuk mengetahui detailnya.
  • Batas permintaan: Alat ini dapat memproses hingga 20 URL per permintaan.
  • Ukuran konten URL: Ukuran maksimum untuk konten yang diambil dari satu URL adalah 34 MB.

Jenis konten yang didukung dan tidak didukung

Alat ini dapat mengekstrak konten dari URL dengan jenis konten berikut:

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

Jenis konten berikut tidak didukung:

  • Konten paywall
  • Video YouTube (Lihat pemahaman video untuk mempelajari cara memproses URL YouTube)
  • File Google Workspace seperti Google Dokumen atau Spreadsheet
  • File video dan audio

Langkah berikutnya