GeminiのAPIグラウンディング｜引用の注意点

こんにちは。Osukeラーニング、運営者の「osuke」です。

GeminiのAPIで最新情報を調べたいのに、検索を付けても参照リンクが画面に出ない。古いサンプルと新しい公式コードで書き方が違い、どちらを使えばよいか迷う。グラウンディングを調べ始めると、こうした疑問がつながって出てきますね。

この記事ではGoogle検索を使うグラウンディングについて、API方式、引用表示、料金、公開前の注意点を整理します。結論は、回答文が出ることと、出典を確認できるアプリが完成することを分けて考えることです。

確認日は2026年10月4日です。Google公式資料とXの公開投稿を調査してまとめており、私自身の本番運用体験や、この記事のコードで実際にAPIを呼び出した結果ではありません。料金・対応モデル・利用条件は、導入時にも公式資料で確認してください。

記事のポイント

• Google検索・URL指定・RAGを目的で使い分ける
• 古いAPIのメタデータと新しい応答形式を混ぜない
• 引用表示と検索回数を回答本文とは別に確認する
• 保存条件と公開画面の要件を確認してから提供する

GeminiのAPIグラウンディング基礎

最初に、何を検索し、何を根拠として返し、どこに費用が発生するのかを整理します。コードを貼り付ける前に用途を決めると、後から作り直す部分を減らせます。

Google検索と回答をつなぐ仕組み

グラウンディングは、回答を外部の情報に結び付けるための仕組みです。Google検索を使う場合は、APIに検索ツールを渡し、必要に応じて検索された情報と回答を関連付けます。ただし、検索の設定を入れたことだけで、すべての質問について検索が実行されるわけではありません。質問に対して検索が役立つかをモデルが判断するため、文章が返ってきたかどうかと、検索が使われたかどうかは別々に確認する必要があります。

たとえば、試作するのが公共施設の案内アプリなら、「図書館とは何ですか」と「対象の図書館の今月の臨時休館日はいつですか」では必要な情報が違います。前者は一般的な説明、後者は対象施設と時期を特定した情報です。この2問を同じ扱いにせず、後者では施設名、地域、対象月を明示する。これは検索を必ず起動する保証ではなく、確認したい情報を曖昧にしないための入力設計です。

引用が付いても、最終的な回答が常に正しいとは限りません。去年の告知を今年のものと読み違えていないか、通常の休館日と臨時休館日を混ぜていないか、別の自治体の同名施設を見ていないかを確認します。私なら、まず答えを短くし、「対象」「日付」「出典の該当箇所」の3点を照合する設計から考えます。長い回答を一度に評価するより、何が誤っているかを見つけやすくなるからです。

• 回答が出たかと検索が実行されたかを分ける
• 日付・地域・対象を質問に含める
• 引用先が、その文章の主張を実際に支えているか確認する

公式の仕組みと応答例は、Google公式「Grounding with Google Search」で確認できます。本記事では、そこから先の実装判断として、回答本文、引用、検索候補、費用の4つを別の確認項目にしています。グラウンディングは確認を助ける機能であって、人の確認を不要にする認証マークではない、と考えると使い方がぶれにくいですね。

URL指定やRAGとの違い

検索を使うべきか迷ったら、「根拠にしたい情報は、もう決まっているか」と考えてみてください。Webから新しい情報を探したい場合と、指定した1ページを読ませたい場合では、出発点が異なります。Google検索によるグラウンディングは前者、URL contextは指定した公開ページを扱うときの候補です。社内の権限付き資料を対象にするなら、さらに別の設計として、自分たちで取得範囲とアクセス権を管理するRAGなどを検討します。

たとえば「この製品の最新の変更点を探す」と「このリリースノートだけを説明する」は似ていても違います。前者は発見、後者は範囲を限定した読解です。後者なのに検索範囲を広げると、別のバージョンの記事まで混ざるかもしれません。逆に、指定したページだけで完結する設定では、その後に出た重要な訂正に気付かない可能性があります。どちらが高機能かではなく、何を答えの範囲とするかで選びます。

Google公式のURL context資料は、公開URLの取得を説明しています。ログインが必要な社内ページを、URLを渡すだけで安全に読める仕組みだと考えないことが大切です。また、RAGという名称を使えば安全になるわけでもありません。資料の取得権限、更新日、回答への引用、削除時の反映まで設計して初めて、対象を絞った情報利用になります。ここを飛ばして検索ツールだけで代替しないようにしましょう。

• 未発見の情報を探すのか、既知の資料を読むのかを決める
• 公開Webと非公開資料を同じ入力に混ぜない
• 方式名ではなく、情報の範囲と権限で判断する

Geminiアプリで人が調査することが目的なら、APIを組み込む必要がない場合もあります。アプリ内の調査機能を探している方は、GeminiのDeep Researchの使い方と注意点から確認すると整理しやすいです。この記事は、自分のアプリに検索と引用を組み込みたい方向けの内容です。

対応モデルとAPI方式を確認

ネット上のコードを見比べるときは、モデル名だけでなく、どのAPI方式で呼び出しているかを先に確認します。2026年10月4日に確認した公式のグラウンディング例は、Interactions APIとgemini-3.8-flashの組み合わせでした。一方、従来のgenerateContentも引き続きサポートされています。古い形式が載っていること自体を誤りと決め付けず、自分のアプリがどちらを使っているかを明確にするのが出発点です。

特につまずきやすいのは、リクエストだけ新しくして、応答の読み取りを以前のままにすることです。従来のgenerateContentで見かけるgroundingMetadata、Pythonのgrounding_metadataと、Interactionsのstepsやannotationsは、同じ場所にある同じ項目ではありません。検索結果を返しているのに、古い階層を探したため引用がないように見えることも考えられます。これは本記事で確認した特定の不具合ではなく、形式を混在させたときに点検すべき実装上の問題です。

新規の小さな試作なら、現行公式例に合わせて1方式で統一すると読み解きやすくなります。既存アプリが動いているなら、検索を追加するためだけに全体を一度に移行する必要があるとは限りません。移行する場合は、入力パラメータ、返り値、エラー処理、保存設定の4項目を分けて確認します。モデル名の置換だけで移行完了とせず、既存のテストで期待していた引用表示まで確かめることが重要です。

• API方式とSDKのバージョンを記録する
• 旧形式のgroundingMetadataと新形式のannotationsを混ぜない
• モデルへのアクセス可否は自分のプロジェクトで確認する

作業メモには「採用した方式」「参照した公式ページ」「確認日」を残しておくと、後で別の人が調べ直しやすくなります。たとえば、引用を描画する担当者にモデル名だけ伝えても、どのデータを渡すべきかは分かりません。文章と引用の対応を含めた応答形式まで共有することで、画面側とAPI側の認識のずれを減らせます。Google公式のInteractions概要と移行ガイドは、この違いを確認する資料として使えます。

料金は検索回数で見積もる

費用を考えるときは、APIを呼んだ回数だけではなく、実際に行われる検索の数に注目します。Googleの料金資料では、Gemini 3系のGoogle検索は個々の検索クエリを課金単位としています。1回の質問から複数の検索が行われれば、「質問が1回だから検索料金も1回分」という見積もりにはなりません。反対に、検索が実行されない回答まで、毎回同じ検索回数として扱うのも正確ではありません。

確認日時点のGemini 3.8 Flashの料金表では、Google検索は無料ティアで提供されず、有料ティアにはGemini 3.xで共有する月5,000検索の無料枠、その後は1,000検索当たり14米ドルという条件が示されています。これはモデルの入出力料金とは別です。月額のGeminiアプリを契約しているからAPI検索も使い放題、という意味ではありません。契約の入口の違いは、Geminiの無料・有料料金の考え方も参考にしてください。

単純な試算として、共有無料枠5,000回をその月に使え、対象となる検索が合計6,000回だったとします。この仮定なら超過は1,000回で、検索部分は14米ドルです。ただし、入力・出力の料金、税、為替などを含む総額ではありません。他の対象利用が先に共有枠を消費していれば、この前提も変わります。「月6,000回のAPIリクエストなら14ドル」と読み替えないことが、ここで最も大切な注意点です。

• モデルの入出力料金と検索料金を分ける
• 共有無料枠を、自分の機能だけの専用枠と思わない
• 通知設定と実行停止の仕組みを別々に確認する

小規模な試作でも、どのプロジェクトで費用を見るか、誰が確認するか、想定を超えたらどの機能を止めるかを決めておきたいですね。予算通知が来ることと、自動的にすべての呼び出しが停止することは同じではありません。アプリ側の回数制限や再試行上限も含めて考えましょう。料金表は更新されるため、公開後もモデル変更時に同じ単位で比較し直すことをおすすめします。

Xの活用例と不安を読み解く

Xでは、グラウンディングの説明だけでなく、開発者が何を便利と感じ、どこに手間を感じているかを確認しました。今回読めたのは複数の公開投稿ですが、利用者全体の傾向を測った調査ではありません。また、2025年の投稿と2026年の公式例ではAPI方式が異なる場合があります。古い投稿を参考にするときは、実現したい用途と、そのままコピーできるコードを切り離して読む必要があります。

2025年1月23日の@kwindlaの投稿では、音声AIでGeminiの検索メタデータを扱い、参照URLを示すPipecatの実装が紹介されていました。音声で答えを聞くだけでは確認しにくい根拠を、別の画面で確かめられるようにする用途として参考になります。一方、その投稿で触れられているデータ利用方法を、現在の規約で許可された運用とみなすことはできません。本記事では、参照先を利用者に示すという用途の部分に限定して捉えています。

2025年4月15日の@jarekceborskiの投稿でも、APIから得られるgroundingMetadataへの評価が見られました。本文は日本語翻訳表示で確認していますが、速度についての感想は本記事の性能評価には採用していません。また、2026年10月3日の@koinunopochiの投稿は、GeminiのAPIラッパーで費用の閾値を設定したという内容でした。後者は費用管理の隣接事例であり、グラウンディング固有の障害や、特定の課金制御機能の有無を証明するものではありません。

• 用途の発見には個人の投稿を参考にする
• 仕様・利用条件・対応形式は現行の公式資料で確認する
• 個人の速度評価や費用実績を自分の環境へ一般化しない

今回の取得範囲では、現行グラウンディングに固有の、再現条件まで確認できる失敗事例は得られませんでした。そこで「多くの人が失敗している」といった説明はしません。得られた示唆は、回答文だけでは足りず、出典を見せる設計と費用を管理する設計が必要ということです。以下の確認順は、これらの観察と公式仕様を基にした提案であり、SNSで検証済みの万能な解決策ではありません。

GeminiのAPIグラウンディング実装

ここからは、公開情報を使った小さな試作から始める手順です。最小コードで回答が出ても、そのまま利用者向けに公開するのではなく、引用表示と利用条件まで順に確認します。

Pythonで検索を有効にする

まずは、現行のGoogle Gen AI SDKでInteractionsを利用できる環境を用意します。APIキーはサーバー側の環境変数などで管理し、コードに直書きしたり、ブラウザーへ配信するJavaScriptへ埋め込んだりしないようにしてください。下の例は検索ツールを指定する部分に絞っています。この記事では実際のAPI実行はしておらず、利用プロジェクトのモデルへのアクセス、課金設定、SDKの対応状況は実行前に確認が必要です。

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Pythonの直近の安定版について、公式発表の日付と変更点を調べてください。",
    tools=[{"type": "google_search"}],
    store=False,
)
print(interaction.output_text)

この例は、Google公式のグラウンディング例を基に、質問内容と会話状態の保存設定を調整した参考コードです。store=FalseはInteractionsの会話状態を保存しない設定ですが、検索機能に適用される別の保存条件まで無効にするものではありません。キーの値や機密情報を出力する処理は入れていません。それでも、回答に何を含めるかは入力次第なので、最初は公開されているソフトウェアの発表など、秘密を含まない題材を選びます。

実行後に見るべきなのは、文章の見栄えだけではありません。対象のバージョンが明確か、発表日と別の更新日を混同していないか、検索の処理が返っているかを確認します。質問文で公式発表を求めても、特定ドメインだけを技術的に許可する設定と同じではないため、実際の引用先の確認も必要です。公式サイトを見ていない回答を、文章の丁寧さだけで合格にしないようにしましょう。

• 最小コードは引用画面を備えた完成アプリではない
• APIキーは利用者の画面や公開リポジトリに出さない
• store=Falseを「すべてのデータが保存されない」と説明しない

最初から大量の質問を流す必要はありません。公開情報の1問で応答形式を確認し、その後に一般質問、対象が曖昧な質問、答えが見つからない質問へ広げると、確認事項が見えやすくなります。ここで紹介したコードは回答本文を表示するところまでです。利用者向けに出す前には、次の引用と検索候補の表示を実装・確認してください。

引用と検索候補を表示する

回答文だけを取り出す便利なプロパティを使うと、画面に文章は出ても、根拠との対応は別途扱う必要があります。Interactionsの現行例では、model_outputのテキストに付くannotationsに引用情報があり、url_citationには参照先とテキストの範囲が含まれます。また、google_search_resultには検索候補表示用のsearch_suggestionsがあります。この2つを「参考リンクの一覧」とひとまとめにせず、役割を分けて確認します。

たとえば「新機能が追加された」と「公開日は何月何日」という2文があるなら、それぞれがどの根拠を参照しているか分かる表示を目指します。ページ末尾にリンクを1つ置いただけでは、どの主張を支えているのか曖昧です。本文を加工してから元の位置情報をそのまま当てると、引用位置がずれる可能性もあります。まず元のテキストと引用の対応を保ち、画面用の整形後にも対応が崩れていないかを点検しましょう。

引用の配列が空のケースも考えておきます。すべての回答に同じ引用構造が存在する前提で処理すると、一般質問や検索されなかった回答で画面が壊れかねません。「検索付き回答として表示してよい条件」と「通常回答として扱う条件」をアプリ側で分けるのが実務的です。根拠がないときに、存在しないURLを補ったり、成功を表すバッジだけ付けたりしないことが大切ですね。

• 引用の有無と本文との対応を確かめる
• 検索候補の表示を引用リンクで代用しない
• 引用なし・空の応答でも画面が壊れないようにする

search_suggestionsの扱いは、公式資料と利用条件に沿って確認してください。独自の要約に置き換えてよいと決め付けるのは避けます。実装テストでは、スマートフォンで引用を開けるか、長いタイトルが本文を押し広げないか、キーボード操作でも参照先へ移れるかを確かめるとよいでしょう。「引用の情報がAPIから返る」と「利用者が引用を確認できる」は別の到達点です。後者まで確認して、初めて出典付きの画面になります。

検索されないときの確認順

検索結果らしい文章が出ないと、すぐモデルを変更したくなるかもしれません。しかし、最初に確認したいのは、リクエストに検索ツールが渡っているか、採用モデルとAPI方式が対応しているか、返ってきた情報を正しい場所から読んでいるかです。この順に見れば、設定、モデル判断、表示処理のどこを調べるべきか整理できます。ネットワークや認証のエラーがある場合は、検索の品質を評価する前に、そのエラーを解消する必要があります。

切り分けのために、3種類の質問を用意する方法を提案します。1つ目は一般的な説明、2つ目は対象と時期を明示した公開情報、3つ目は対象が曖昧な質問です。2つ目でも検索がないなら、ツール設定と応答の確認を優先します。3つ目で別の対象を調べたなら、質問の曖昧さを減らします。これは必ず検索させるテストではなく、何を期待して何が返ったかを比較できるようにする確認用の組み合わせです。

エラーが出ていない場合も、回答の文章だけを見て「検索したはず」と判断しないでください。検索ステップがあるか、引用があるか、引用が画面まで届いているかを順に追います。API側には情報があるのに画面で消えているなら、質問の書き換えを繰り返しても解決しません。逆に、検索が不要と判断された一般質問に対して、引用が空であることだけを障害扱いするのも適切ではありません。

• 設定：ツール・モデル・API方式を確認する
• 応答：検索ステップと引用を分けて確認する
• 画面：受け取った根拠が表示まで残っているか確認する

再試行は上限を設けましょう。応答が気に入らないたびに自動で何度も呼び直すと、料金と待ち時間を増やす可能性があります。失敗時には利用者へ確認できなかったことを伝え、質問の対象や期間を明確にする、公式ページを直接確認する、といった次の行動を示す方が誠実です。なお、調査用の記録を残す場合も、検索結果本文や入力を無制限に保存するのではなく、規約と機密性を確認して必要な範囲に絞ってください。

保存・公開前に規約を確認

検索できることと、その結果を自由に保存・再利用できることは別です。Gemini APIの利用条件には、Grounding with Google Searchの結果やSearch Suggestionsの利用方法について個別の条件があります。検索結果からリンクを収集して独自の索引を作る、取得した内容を別の用途で再配布する、といった使い方まで一律に許されているとは考えないでください。アプリの利用者に回答を提示する用途と、データを蓄積して別サービスの材料にする用途は分けて確認します。

保存期間にも注意が必要です。確認日時点の利用条件では、グラウンディングで使われる入力・文脈・出力について30日間の保存が記載されています。Interactionsのstore=Falseだけを見て、検索も含めたすべての保存がなくなると説明するのは適切ではありません。機密情報を含む業務で使うなら、入力対象、適用される契約、社内の承認条件を確認することが先です。具体的な適法性や契約への適合は、担当部署などに相談してください。

公開前の確認では、開発者の画面だけでなく、実際の利用者が目にする画面を見ます。検索候補や引用の表示、確認できなかった場合の案内、対象外の入力を避ける説明が揃っているかを点検します。たとえば問い合わせフォームの自由入力をそのまま検索へ送る設計なら、利用者が個人情報を書き込む可能性も考慮します。「公開Webを検索する機能だから入力も公開情報だろう」という前提にはしない方が安全です。

• 保存・再利用には個別の条件や限定的な例外がある
• 検索結果を自動収集して別用途へ転用しない
• 公開前に利用条件と組織のデータ取扱方針を確認する

利用条件は、本文で最初に示した公式グラウンディング資料からTerms of Serviceへ進んで確認できます。Google公式の「Gemini API Additional Terms of Service」の該当項目を、料金表とは別に読むのがポイントです。料金を支払っていれば何でもできるわけではありません。履歴表示のための保存などに例外があっても、別の目的への無制限な保存へ広げて解釈しないようにしましょう。

GeminiのAPIグラウンディング要点

GeminiのAPIグラウンディングを試すなら、最初の目標は「回答が出る」ではなく、「公開情報の1問について、検索と根拠を確認できる」に置くと進めやすいです。API方式を統一し、対象を絞った質問で検索ステップを確認する。次に引用と検索候補を表示し、料金と保存条件を確認する。この順番なら、まだできていないことを曖昧にしたまま公開するのを避けられます。

すべてを初日に完成させる必要はありません。最初は開発用の小さな画面でよく、扱う質問も1つの分野に限定できます。ただし、利用者へ出すなら表示条件や安全性を後回しにしないことが重要です。試作段階で足りない部分を一覧にし、「文章出力は確認済み、引用表示は未確認」のように状態を分けておけば、誰かが完成版だと思って使い始める混乱を減らせます。

Xで見られたのは、検索メタデータを活用したいという関心と、API費用を自分で管理したいという課題でした。それは便利さの証明や、すべての環境での成功を保証する話ではありません。公式資料で仕様を確認し、個人の投稿から使い道を知り、自分の用途で小さく確かめる。この3段階を混ぜないことが、更新の速いAPIと付き合ううえで長く使える考え方だと思います。

• 今日の一歩は、公開情報1問で検索と引用を確認すること
• 未確認の表示や条件が残る間は、完成アプリとして公開しない
• モデルやSDKを変更したら、同じ確認項目で見直す

Gemini全体の機能から用途を選び直したい場合は、Geminiでできることと使い分けも確認してください。APIの導入そのものが目的ではなく、必要な根拠を利用者が確かめられることが目的です。検索を付けるだけで終わらせず、確かめられる画面と無理なく続けられる運用まで、一つずつ整えていきましょう。