Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Konteks URL

Anda dapat menggunakan alat konteks URL untuk memberikan URL kepada Gemini sebagai konteks tambahan untuk perintah Anda. Kemudian, model dapat mengambil konten dari URL dan menggunakan konten tersebut untuk menginformasikan dan membentuk responsnya.

Alat ini berguna untuk tugas-tugas seperti berikut:

Mengekstrak poin data atau poin pembicaraan penting dari artikel
Membandingkan informasi di beberapa link
Menyintesis data dari beberapa sumber
Menjawab pertanyaan berdasarkan konten halaman tertentu
Menganalisis konten untuk tujuan tertentu (seperti menulis deskripsi pekerjaan atau membuat pertanyaan ujian)

Perhatikan bahwa indeks yang digunakan untuk mengambil data mungkin tidak selalu yang terbaru, sehingga beberapa informasi mungkin sudah usang.

Panduan ini menjelaskan cara menggunakan alat konteks URL di Gemini API.

Model yang didukung

Model berikut memberikan dukungan untuk Konteks URL:

Klik untuk meluaskan model yang didukung

Menggunakan konteks URL

Anda dapat menggunakan alat konteks URL dengan dua cara utama, yaitu secara mandiri atau bersama dengan Grounding dengan Google Penelusuran.

Hanya konteks URL

Anda dapat memberikan URL spesifik yang Anda ingin untuk dianalisis oleh model secara langsung dalam perintah Anda:

Summarize this document: YOUR_URLs

Extract the key features from the product description on this page: YOUR_URLs

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext

client = genai.Client(http_options=HttpOptions(api_version="v1"))
model_id = "gemini-3.5-flash"

url_context_tool = Tool(
    url_context = UrlContext
)

response = client.models.generate_content(
    model=model_id,
    contents="Compare recipes from YOUR_URL1 and YOUR_URL2",
    config=GenerateContentConfig(
        tools=[url_context_tool],
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: [
        "Compare recipes from YOUR_URL1 and YOUR_URL2",
    ],
    config: {
      tools: [{urlContext: {}}],
    },
  });
  console.log(response.text);
  // To get URLs retrieved for context
  console.log(response.candidates[0].urlContextMetadata)
}

await main();

REST

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
              ]
          }
      ],
      "tools": [
          {
              "url_context": {}
          }
      ]
  }' > result.json

cat result.json

Grounding dengan Google Penelusuran dengan konteks URL

Anda juga dapat mengaktifkan Konteks URL dan Grounding with Google Search, menggunakan perintah dengan atau tanpa URL. Model ini mungkin akan menelusuri informasi yang relevan terlebih dahulu, lalu menggunakan alat Konteks URL untuk membaca konten hasil penelusuran guna mendapatkan pemahaman yang lebih mendalam.

Fitur ini bersifat eksperimental dan tersedia di API versi v1beta1.

Contoh perintah:

Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.

Recommend 3 books for beginners to read to learn more about the latest YOUR_SUBJECT.

Python

from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext, GoogleSearch

client = genai.Client(http_options=HttpOptions(api_version="v1beta1"))
model_id = "gemini-3.5-flash"

tools = []
tools.append(Tool(url_context=UrlContext))
tools.append(Tool(google_search=GoogleSearch))

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,
        response_modalities=["TEXT"],
    )
)

for each in response.candidates[0].content.parts:
    print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)

JavaScript

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

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

const ai = new GoogleGenAI({
  vertexai: true,
  project: process.env.GOOGLE_CLOUD_PROJECT,
  location: process.env.GOOGLE_CLOUD_LOCATION,
  apiVersion: 'v1beta1',
});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3.5-flash",
    contents: [
        "Give me a three day event 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 -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
  -d '{
      "contents": [
          {
              "role": "user",
              "parts": [
                  {"text": "Give me a three day event 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

Untuk mengetahui detail selengkapnya tentang Grounding dengan Google Penelusuran, lihat halaman ringkasan.

Grounding Web untuk Enterprise dengan Konteks URL

Anda dapat mengaktifkan konteks URL dan Web Grounding for Enterprise jika memiliki kebutuhan kepatuhan tertentu atau berada di industri yang diatur seperti kesehatan, keuangan, atau sektor publik. Indeks web yang digunakan dalam Web Grounding for Enterprise lebih terbatas daripada indeks Grounding dengan Google Penelusuran standar, karena menggunakan subset dari apa yang tersedia di Google Penelusuran.

Untuk mengetahui detail selengkapnya tentang Grounding Web untuk Enterprise, lihat halaman Grounding Web untuk Enterprise.

Respons kontekstual

Respons model didasarkan pada konten yang diambilnya dari URL. Jika model mengambil konten dari URL, responsnya akan menyertakan url_context_metadata. Respons tersebut mungkin terlihat seperti berikut (bagian dari respons telah dihilangkan agar lebih singkat):

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "... \n"
          }
        ],
        "role": "model"
      },
      ...
      "url_context_metadata":
      {
          "url_metadata":
          [
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/code-execution",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
            {
              "retrieved_url": "https://cloud.google.com/gemini-enterprise-agent-platform/models/grounding/grounding-with-google-search",
              "url_retrieval_status": <UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS: "URL_RETRIEVAL_STATUS_SUCCESS">
            },
          ]
        }
    }
  ]
}

Untuk mengetahui informasi selengkapnya tentang objek ini, lihat referensi API UrlContextMetadata.

Pengambilan langsung

Alat konteks URL mengambil versi aktif halaman web untuk menjaga informasi Anda tetap aktual.

Untuk mengambil konten halaman web secara efisien, alat konteks URL menggunakan proses dua tahap yang dirancang untuk menyeimbangkan kecepatan, biaya, dan akses ke informasi terbaru:

Pengambilan konten yang diindeks: Ini adalah tahap pertama. Saat Anda memberikan URL, alat ini pertama-tama akan mencoba mengambil konten dari indeks web Googleyang ekstensif dan sangat dioptimalkan. Metode ini memberikan akses cepat ke banyak koleksi halaman web yang di-crawl.
Penggantian pengambilan langsung: Ini adalah tahap kedua. Jika konten untuk URL tertentu tidak tersedia di indeks (misalnya, jika halaman tersebut sangat baru dan belum diindeks), alat akan otomatis melakukan pengambilan langsung. Mekanisme penggantian ini dapat langsung mengakses URL, dan mengambil versi terbaru konten secara real-time.

Pemeriksaan keamanan

Sistem akan 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 dari URL_RETRIEVAL_STATUS_UNSAFE.

Jumlah token

Jumlah token input mencakup konten yang diambil dari URL yang Anda tentukan dalam perintah. Dari output model, Anda dapat melihat jumlah token untuk penggunaan perintah dan alat dalam objek usage_metadata. 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 Anda gunakan. Untuk mengetahui informasi selengkapnya, lihat Biaya membangun dan men-deploy model AI di Gemini Enterprise Agent Platform.

Jenis konten yang didukung dan tidak didukung

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

Konten	Jenis
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`

Alat konteks URL tidak mendukung jenis konten berikut:

Konten berbayar berpenghalang
Video YouTube (Untuk mengetahui informasi selengkapnya, lihat Pemahaman video.)
File Google Workspace seperti Google Dokumen atau Google Spreadsheet
File video dan audio

Batasan

Alat konteks URL menggunakan hingga 20 URL per permintaan untuk analisis.
Untuk mendapatkan hasil terbaik selama fase eksperimental, gunakan alat ini di halaman web standar, bukan di konten multimedia seperti video YouTube.

Konteks URL Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Model yang didukung

Klik untuk meluaskan model yang didukung

Menggunakan konteks URL

Hanya konteks URL

Python

JavaScript

REST

Grounding dengan Google Penelusuran dengan konteks URL

Python

JavaScript

REST

Grounding Web untuk Enterprise dengan Konteks URL

Respons kontekstual

Pengambilan langsung

Pemeriksaan keamanan

Jumlah token

Jenis konten yang didukung dan tidak didukung

Batasan

Konteks URL