Gemini APIのURLコンテキストとは｜使い方・料金・制限

Gemini APIのURLコンテキストとは、プロンプトにURLを添えるだけで、モデルにそのページの中身を読ませて答えさせるツールです。リクエストの tools に url_context を指定すると使えます。

確認日は2026年11月2日です。公式のURL contextのドキュメントでは、1リクエストで最大20個のURL、1URLあたり最大34MBまで処理でき、ツール自体は無料で、取得した内容が入力トークンとして課金されると説明されています。

• 使い方は、プロンプトにURLを書き、tools に url_context を足すだけ
• 取得できるのは、公開されているHTML・JSON・PDF・画像など
• ログインが必要なページ、有料の記事、YouTube動画、Googleドキュメントは対象外

URLコンテキストとは｜URLを渡してページの中身を読ませるツール

URLコンテキスト（URL context）とは、Gemini APIのモデルにURLを渡し、そのページの内容を読んだうえで回答させる組み込みツールです。

公式ドキュメントは、URLを含めるとモデルがそのページにアクセスして、レスポンスの情報を増やして改善すると説明しています。用途として、次の4つが挙げられています。

• データの抽出（複数のURLから価格・名前・主な調査結果を取り出す）
• ドキュメントの比較（複数のレポート・記事・PDFの違いを調べる）
• コンテンツの統合と作成（複数のページを組み合わせて要約やレポートを作る）
• コードとドキュメントの分析（GitHubのリポジトリや技術文書から手順を作る）

自分でページを取得して本文を貼り付ける処理を書かなくても、URLだけで済むのが特長です。

URLコンテキストの使い方｜url_context を tools に指定する

URLコンテキストを使うには、プロンプトに読ませたいURLを書き、リクエストの tools に {"type": "url_context"} を指定します。

APIキーはGoogle AI Studioの使い方で発行できます。そのうえで、手順は次のとおりです。

1. 読ませたいページのURLを、https から始まる完全な形で用意する
2. プロンプトに「このURLの内容を比較して」のように、URLと頼みたいことを書く
3. tools に {"type": "url_context"} を指定してリクエストを送る
4. レスポンスの出典情報（url_citation）で、どのURLから答えたかを確かめる

公式のPythonの例は、2つのレシピページを比べるものです。次のように、モデルに gemini-3.8-flash を指定し、tools に url_context を渡しています。

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

この例は、公式のコード内の注記で「SDK 2.0.0 より新しいバージョンで動く」とされています。Interactions API（client.interactions.create）を使う形です。

仕組み｜まず内部のキャッシュを見て、なければその場で取得する

URLコンテキストは、まず内部のインデックス（キャッシュ）からページの内容を探し、見つからなければ実際にURLへアクセスして取得する2段階の方式です。

公式ドキュメントは、この方式を「速度・コスト・新しいデータへのアクセスのバランスを取るため」と説明しています。公開直後の新しいページのようにインデックスにない場合は、自動でライブ取得に切り替わります。

取得してくれるのは、プロンプトに書いたURLの中身だけです。公式のベストプラクティスには、ページ内のリンク先（入れ子のリンク）の内容は取得されないと書かれています。

読ませたいページが複数あるときは、それぞれのURLをプロンプトに書いて渡します。

対応モデルと、ほかのツールとの組み合わせ

URLコンテキストは、Gemini 4 ArgonからGemini 2.5 Flash-Liteまで公式の対応モデル表にある10モデルで使え、Google検索のグラウンディングや独自の関数と組み合わせることもできます。

公式の対応モデル表（2026年11月2日確認）にチェックが付いているモデルは次のとおりです。

モデルごとの特徴は、Gemini 3.8 Flashの解説やGemini 4 Argonの解説で確認できます。

組み合わせ方は、公式ドキュメントに2つの例があります。

• Google検索のグラウンディングと同時に有効にすると、モデルが検索でページを見つけ、URLコンテキストで中身を深く読む使い方ができる
• Gemini 3系のモデルでは、URLコンテキストなどの組み込みツールと、独自の関数（Function Calling）を組み合わせられる

組み込みツールと関数の組み合わせは、公式のツール組み合わせのページでプレビュー扱いとされ、Gemini 4とGemini 3系が対象です。関数の書き方はFunction Callingの入門にまとめています。

料金｜ツールは無料で、取得したページの分が入力トークンになる

URLコンテキストの料金は、ツール自体は無料で、取得したページの内容が入力トークンとして、使うモデルの単価で課金される仕組みです。

公式の料金ページ（最終更新2026年10月30日）には、URL contextは「Free of charge」で、入力トークンとしてモデルの料金が課金されると書かれています。

ドキュメントのusage例では、取得したページの分は tool_use_input_tokens として表示されます。公式の例の数値は次のとおりです。

• プロンプトの入力（input_tokens）：27
• 取得したページの入力（tool_use_input_tokens）：10,309
• 出力（output_tokens）：45
• 思考（thoughts_tokens）：31
• 合計（total_tokens）：10,412

この例では、取得したページの分が合計の約99%（10,309÷10,412）を占めています。プロンプトが短くても、読ませるページが長ければ、料金ページの考え方では費用の大半はページ分になります。

次の表は、この公式の例の数値を、Gemini 3.8 Flashの標準・有料の単価に当てはめた仮の例です。単価は料金ページの「入力 100万トークンあたり0.75ドル、出力（思考を含む）3.75ドル（2026年12月31日まで）」を使っています。

同じ規模のリクエストを1,000回送ると、約8ドルの見込みです。2027年1月1日からは入力1.50ドル・出力7.50ドルと書かれているため、同じ条件で約0.016ドルになります。

この表は「公式のusage例」と「3.8 Flashの単価」を組み合わせた仮の例で、実際の請求額ではありません。単価の出典は料金ページです。モデルごとの単価はGemini API料金の読み方で整理しています。

制限｜20URL・34MBまで、取得できない種類もある

URLコンテキストの制限とは、1リクエスト20URL、1URL34MBまでという上限と、公開されていないページや動画などが取得できないという条件です。

公式ドキュメントの「Limitations」に書かれている内容を表にまとめます（2026年11月2日確認）。

YouTubeのURLを扱いたい場合は、公式ドキュメントが動画理解（video understanding）の説明を案内しています。

手元のファイルを読ませたいときは、URLコンテキストではなく、ファイルを預ける方法が向いています。流れはFile APIの使い方で確認できます。

うまく使うコツと、答えが返ってこない時の確認

URLコンテキストをうまく使うコツとは、読ませたい内容に直接つながる具体的なURLを、完全な形で、ログイン不要のページから選ぶことです。

公式のベストプラクティスは次の3点です。

• 具体的なURLを渡す（ページ内のリンク先は取得されない）
• ログインが必要なページや、有料の壁の向こうのページを渡さない
• https から始まる完全なURLを書く（google.com ではなく https://www.google.com）

思った答えが返らないときは、レスポンスの url_context_result を見ます。URLごとの取得結果（ステータスと取得したURL）が入っており、公式は主にデバッグ用と説明しています。

1. url_context_result のステータスで、取得に成功したURLかを確かめる
2. ステータスが「unsafe」なら、安全性の確認に通らなかったURLなので、別のURLに変える
3. ログイン・有料の壁・動画・Googleドキュメントのいずれかでないかを確かめる
4. URLの数が20を超えていないかを確かめる

公式は、URLに対して内容の安全性チェックを行い、通らなかったURLは url_context_result のステータスが「unsafe」になると説明しています。

Google検索のグラウンディングとの使い分け

URLコンテキストは「読むページが決まっているとき」、Google検索のグラウンディングは「どのページを読むかをモデルに探させたいとき」に向いた、役割の違うツールです。

公式ドキュメントの説明と料金ページの記載をもとに、違いを表にします。

両方を同時に有効にすると、検索で見つけたページをURLコンテキストで深く読む使い方もできます。グラウンディングの仕組みと料金はGoogle検索によるグラウンディングの解説にまとめています。

よくある質問（FAQ）

Q1. URLコンテキストに追加料金はかかりますか？

料金ページでは、URL contextは「Free of charge」で、取得した内容が入力トークンとして課金されると書かれています。実際の金額は使うモデルの単価で決まります。

Q2. 1回に何個のURLを渡せますか？

公式ドキュメントでは、1リクエストで最大20個のURLを処理できると書かれています。1つのURLから取得できる内容は最大34MBです。

Q3. ログインが必要なページは読めますか？

読めません。公式は、URLがウェブ上で一般に公開されている必要があり、有料の記事は対応しないと説明しています。

Q4. YouTubeの動画は読ませられますか？

URLコンテキストでは対応していません。YouTubeのURLは、公式の動画理解（video understanding）の説明を参照するよう案内されています。

Q5. PDFのURLも読めますか？

読めます。取得できる種類にPDF（application/pdf）が含まれます。ただし、Googleドキュメントなどのファイルは対象外です。

Q6. 取得したページの分のトークン数はどこで見られますか？

レスポンスの usage に tool_use_input_tokens として出ます。公式の例では、プロンプトの入力27に対して、取得したページの分は10,309でした。

まとめ｜URLが決まっているなら、url_context で読ませる

URLコンテキストは、読ませたいページのURLが決まっているときに、tools へ url_context を足すだけで使えます。

押さえておく点は、1リクエスト20URL・1URL34MBまで、公開ページのみ、費用の大半は取得したページの入力トークンになる、の3つです。

最新の仕様は公式ドキュメントで確認し、費用は tool_use_input_tokens を見て見積もってください。