Gemini APIの構造化出力とは｜JSONスキーマ指定と使い方

Gemini APIの構造化出力（Structured Outputs）は、モデルの応答をあらかじめ用意したJSON Schemaに沿った形式で返させる機能です。公式ドキュメントは「Gemini modelsを、提供されたJSON Schemaに準拠する応答を生成するよう設定できる」と説明しており、目的は予測可能で型安全な結果を得て、非構造化テキストから構造化データを取り出す作業を簡単にすることにあります。Gemini API公式ドキュメント（Structured outputs）を確認しながら、設定方法・対応範囲・Function Callingとの違い・現時点の制限までを一次情報だけで整理します。

先に結論を書くと、構造化出力は「最終的な回答をJSONなどの決まった形式で受け取りたいとき」に使う機能で、検索などの組み込みツールと組み合わせる場合に限り、2026年9月時点ではPreview（プレビュー）機能としてGemini 3系のモデルでのみ利用できます。エージェント的にツールを呼び出す途中の判断にはFunction Callingを使い、モデルの最終回答そのものを構造化したいときに構造化出力を使う、という役割分担で理解すると迷いません。

これまでGemini APIから自由記述のテキストを受け取り、正規表現やプロンプトの工夫で必要な値を後から取り出していた場合、構造化出力に切り替えることで、その後処理のコードを大きく減らせる可能性があります。この記事では、公式ドキュメントに実際に掲載されているコード例や実装例（レシピ抽出・コンテンツモデレーション・組織図のような再帰構造）をもとに、どこまでが公式に保証された挙動で、どこからが実装時に自分で確認すべき範囲なのかを分けて説明します。

Gemini APIの構造化出力とは

構造化出力とは、Gemini APIのレスポンス形式をあらかじめ定義したJSON Schemaに固定し、モデルにその形式のJSONだけを返させる仕組みのことです。

公式ドキュメントの冒頭では、この機能について次のように説明されています。「Gemini modelsを、提供されたJSON Schemaに準拠する応答を生成するよう設定できる。これにより予測可能で型安全な結果が得られ、非構造化テキストから構造化データを抽出する作業が簡単になる」。構造化出力の公式ページではこの定義に続けて、レシピ抽出・コンテンツモデレーション・再帰的な構造（ツリー構造のデータ）など複数の実装例が示されており、単なるJSON整形にとどまらず、アプリケーションのバックエンドにそのまま渡せる形でモデルの出力を受け取ることを狙った機能だとわかります。

似た名前の機能にFunction Calling（関数呼び出し）がありますが、両者は目的が異なります。違いは後述の比較表で整理しますが、まずは「構造化出力＝モデルの最終回答の形式を固定する機能」という理解を先に持っておくと、以降の設定方法や制限事項が読みやすくなります。

構造化出力が向いている3つの用途

公式ドキュメントは構造化出力が向いている用途として、データ抽出・構造化された分類・エージェント的ワークフローの3つを挙げています。

具体的には次のとおりです。

• データ抽出：文章から名前や日付など特定の情報を取り出す
• 構造化された分類：テキストをあらかじめ定義したカテゴリに分類する
• エージェント的ワークフロー：ツールやAPIに渡すための構造化された入力を生成する

3つ目の「エージェント的ワークフロー」は、Deep Researchのように複数ステップで情報収集や分析を進める処理と相性がよい用途です。各ステップの出力を毎回同じJSON形式で受け取れれば、次のステップの入力としてそのまま使い回せるため、プロンプトだけで自由記述させるより後工程の実装が安定します。Google AIの活用事例で紹介されているような業務利用でも、人が読む文章ではなく別のプログラムに渡すデータを作る場面でこそ構造化出力の効果が出ます。

設定方法：response_formatによるJSON出力の指定

構造化出力は、APIリクエストの設定にresponse_formatとしてJSON Schemaを渡すことで有効になります。

公式ドキュメントのPythonサンプルでは、次のような設定オブジェクトが示されています。これはレシピ情報を抽出する仮の例です。

response_format={
    "type": "text",
    "mime_type": "application/json",
    "schema": Recipe.model_json_schema()
}

typeには出力の種別、mime_typeにはapplication/jsonを指定し、schemaキーに実際のJSON Schemaを渡す構成です。この仮の例ではPythonのPydanticモデルであるRecipeクラスからmodel_json_schema()メソッドでスキーマを生成し、そのままリクエストに渡しています。スキーマをクラス定義から自動生成できるため、フィールドを手作業でJSON化する必要がありません。

PydanticやZodによるスキーマ定義とその他の言語対応

Google GenAI SDKでは、Python向けのPydanticとJavaScript向けのZodを使ってスキーマを定義できます。

公式ドキュメントには「Google GenAI SDKsでは、Pydantic（Python）とZod（JavaScript）を使ったスキーマ定義が可能」と明記されています。同ページにはPython・JavaScript・Java・Go・REST APIそれぞれのコード例が掲載されており、Pydantic/Zodのようなオブジェクト指向のスキーマ定義に対応した言語だけでなく、REST APIで直接JSON Schemaを書いて渡す方法もサポートされています。すでにGemini CLIやSDKでプロトタイプを作っている場合は、既存のデータクラスやインターフェース定義をそのままスキーマ生成に流用できるかを確認すると導入の手間を減らせます。

JSON Schemaの対応範囲とサポートされる型

Gemini APIの構造化出力は、JSON Schema仕様のすべてではなく、その一部（サブセット）だけをサポートしています。

前述のとおりGeminiの構造化出力モードはJSON Schema仕様のサブセット対応で、サポートされるtypeの値として次の7種類が挙げられています。

この一覧はJSON Schemaで一般的に使われる型の名前とほぼ同じですが、サポート範囲として明示されているのはこの7種類までであり、JSON Schema仕様にあるすべてのキーワードや制約が使えるとは限りません。独自のバリデーションルールを細かく組み込みたい場合は、まずシンプルな型構成で試し、Gemini APIがエラーを返す組み合わせがないかを確認しながらスキーマを育てていくのが安全です。

実装例の1つである「Content Moderation（コンテンツモデレーション）」の例は、anyOfを条件付きスキーマに、enumを分類に使うことで、コンテンツの内容に応じて出力構造を変えられることを示す例です。このコンテンツモデレーションの例では、spam_typeという項目にphishing（フィッシング）・scam（詐欺）・unsolicited promotion（迷惑な宣伝）・other（その他）という4種類のenum値が使われ、あわせてis_safeというboolean項目も定義されています。1件の投稿を「安全かどうか」というboolean判定と「迷惑の種類」というenum分類の両方で同時に受け取れる、という具体的な設計例です。

また、もう1つの実装例「Recursive Structures（再帰的な構造）」では、「組織図のような再帰的なスキーマの定義方法を示す」と説明されています。組織図は「ある社員の下に、また別の社員がぶら下がる」という同じ構造が何段も繰り返されるデータなので、object型の中に同じobjectを要素とするarrayを持たせることで、階層の深さを事前に決めずに表現できます。社内の承認フローや部署のツリー構造のように、階層の深さが案件ごとに変わるデータを扱うときに応用できる考え方です。

enumで選択肢を固定して分類精度を高める

enumを使うと、文字列や数値の出力先を事前に決めた選択肢だけに限定できます。

公式ドキュメントでは、文字列型のenumについて「分類タスク向けに、特定の文字列の集合を列挙する」、数値型のenumについて「特定の数値の集合を列挙する」と説明されています。たとえば問い合わせ内容を「請求」「技術的な問題」「その他」のように固定カテゴリへ分類したい場合、string型のフィールドにenumでこの3つの値だけを許可しておけば、モデルが想定外の表記ゆれを返す可能性を減らせます。この考え方はGemの作り方で紹介されているような、特定の役割に絞ったカスタムアシスタントを作る場面とも相性がよく、回答の形式を安定させたい用途全般に応用できます。

構造化出力とFunction Callingの使い分け

構造化出力は最終回答の形式を固定する機能で、Function Callingはモデルが処理の途中で外部の関数やAPIを呼び出すための機能です。

公式ドキュメントは両者の違いを次のように整理しています。

言い換えると、Function Callingは「モデルがこちらに何かを実行してほしいと伝えてくる」ための仕組みで、構造化出力は「モデル自身の回答をそのままJSONとして受け取る」ための仕組みです。天気を調べて回答するチャットボットであれば、天気APIを呼び出す指示にはFunction Callingを、最終的にユーザーへ返す「都市名・気温・天気」をまとめたJSONには構造化出力を使う、という組み合わせ方が公式の役割分担に沿った使い方になります。

Grounding with Google SearchなどほかのツールとStructured Outputsの併用

Gemini 3では、構造化出力を検索によるグラウンディングなどの組み込みツールと組み合わせて使えます。

公式ドキュメントには「Gemini 3では、Grounding with Google Search、URL Context、Code Execution、File Search、Function Callingを含む組み込みツールと構造化出力を組み合わせられる」と記載されています。たとえばGoogle検索によるグラウンディングで最新情報を検索させたうえで、その結果を決まったJSON形式（情報源のURLと要約をセットにした配列など）でまとめさせる、といった組み合わせが可能になります。検索結果を人間向けの文章だけでなく、自社システムに取り込みやすい形でも受け取りたい場合に有効な構成です。

ストリーミングで構造化出力を受け取る

構造化出力はストリーミング配信にも対応しており、生成中のJSONを部分的に受け取って処理を開始できます。

公式ドキュメントは「構造化出力をストリーミングでき、生成されている最中から応答の処理を開始できる。ストリーミングされる各チャンクは有効な部分的JSON文字列であり、それらを連結すると最終的なJSONオブジェクトになる」と説明しています。大量のレコードを一括で処理する場合は、Batch APIのような非同期の一括処理に構造化出力を組み合わせる方法もあります。リアルタイム性を重視するならストリーミング、大量件数をまとめて処理したいならBatch APIというように、処理量と応答速度の要件に合わせて構造化出力の受け取り方を選べます。

組み込みツールとの併用時の対応モデル：現時点ではGemini 3系のPreview機能

構造化出力を組み込みツールと組み合わせる機能は、2026年9月時点でPreview（プレビュー）機能であり、Gemini 3系のモデルでのみ利用できます。

公式ドキュメントの「ツールを使用した構造化出力」の項には「Preview：この機能はGemini 3系のモデルでのみ利用できる」と明記されています。この制限は構造化出力を組み込みツールと併用する場合のものです。Preview機能は正式リリース前の位置づけであるため、仕様や対応モデルの範囲が今後変更される可能性がある点を踏まえて利用する必要があります。「Gemini 3系」に具体的にどのモデルが含まれるかは公式ページのモデル一覧で確認するのが確実で、たとえばGemini 3.8 FlashのようにGemini 3系として案内されているモデルであれば対象に含まれる可能性がありますが、旧世代のモデルを使っている場合は、まず自分が呼び出しているモデルがGemini 3系に含まれるかどうかをドキュメントで確認してから実装を進めるべきです。Preview機能は名称のとおり検証段階の提供であるため、本番環境に組み込む場合は、対応モデルの範囲やスキーマの挙動が変わる可能性を前提に、変更があった際にすぐ気づけるよう定期的に公式ページを見直す運用にしておくと安心です。

実装のベストプラクティス

公式ドキュメントは、説明文の明記・厳密な型指定・プロンプト設計・出力の検証・エラー処理の5点をベストプラクティスとして挙げています。

具体的には次のとおりです。

• 明確な説明：descriptionフィールドを使ってモデルに意図を伝える
• 厳密な型指定：integer・string・enumのように具体的な型を使う
• プロンプト設計：モデルにしてほしいことを明確に記述する
• 検証：出力は構文的には正しいJSONだが、値そのものはアプリケーション側で検証する運用にする
• エラー処理：スキーマには準拠しているが意味的には誤っている出力に対して、堅牢なエラー処理を実装する

特に4つ目と5つ目は見落としやすいポイントです。構造化出力はJSONとしての「型」を保証する機能であり、値の中身が業務要件として正しいかどうかまでは保証しません。金額や日付のような重要な値は、受け取った後にアプリケーション側で範囲チェックや整合性チェックを行う設計にしておくと安全です（出力は構文的には正しいJSONだが、値の中身はアプリケーション側で検証するという公式の考え方に沿った対応です）。1つ目の「明確な説明」も実務では効果が大きく、フィールド名だけでは伝わらない意図（たとえば日付の書式や、金額に税込・税抜のどちらを入れてほしいか）をdescriptionに書き添えておくと、モデルが値を埋める際の判断材料になります。なお、Gemini APIの利用料金は通常のトークン課金にもとづいており、構造化出力を使う場合の追加料金についてこのページ自体には記載がありません。モデルごとの単価は変動するため、費用感を確認したい場合はGemini API料金の読み方を合わせて参照してください。

制限事項：スキーマの複雑さとサポート外の機能

構造化出力には、JSON Schemaの一部機能が非対応であることと、極端に複雑なスキーマは拒否される可能性があることの2つの制限があります。

ドキュメントの「Limitations（制限事項）」セクションには、次の2点が明記されています。

• スキーマのサブセット：JSON Schemaのすべての機能がサポートされているわけではない
• スキーマの複雑さ：非常に大きい、または深くネストしたスキーマは拒否される可能性がある

この2点から実務上言えるのは、既存のシステムで使っているJSON Schemaをそのまま流用しようとすると、Gemini APIではサポートされていないキーワードが含まれていたり、ネストが深すぎて拒否されたりする可能性があるということです。まずは必要なフィールドだけに絞ったシンプルなスキーマから始め、実際にリクエストを送ってエラーが出ないかを確認しながら、必要な範囲だけスキーマを拡張していく進め方が現実的です。前述のRecursive Structuresの例のように階層構造を持たせる場合は特に、想定される最大の階層数を先に決めておき、それを超えるデータが来たときにアプリケーション側でどう扱うかも合わせて設計しておくと、本番投入後にスキーマが拒否されて処理が止まる事態を避けやすくなります。

よくある質問（FAQ）

Q1. 構造化出力とFunction Callingはどちらを使えばいいですか。

モデルの最終回答をJSONなど決まった形式で受け取りたいだけなら構造化出力、回答を返す前にモデルが外部の関数やAPIの実行を依頼してくる必要があるならFunction Callingを使います。公式ドキュメントも「最終的な回答の整形」か「会話中の行動」かで役割を分けています。

Q2. 構造化出力はどのモデルで使えますか。

公式ドキュメントの「ツールを使用した構造化出力」の項には「この機能はGemini 3系のモデルでのみ利用できるPreview機能」と明記されています。これは組み込みツールとの併用時の制限です。自分が呼び出しているモデルがGemini 3系に含まれるかどうかは、公式のモデル一覧ページで確認してください。

Q3. スキーマはPythonのクラス定義からそのまま作れますか。

Google GenAI SDKであれば、PythonはPydantic、JavaScriptはZodを使ってスキーマを定義できると公式ドキュメントに記載されています。既存のデータクラスがあれば、そこからJSON Schemaを生成してリクエストに渡す形で流用できます。

Q4. JSON Schemaのどんな書き方でも使えますか。

使えません。公式ドキュメントは「Geminiの構造化出力モードはJSON Schema仕様のサブセットをサポートする」としており、対応するtypeはstring・number・integer・boolean・object・array・nullの7種類に限られます。非常に大きい、または深くネストしたスキーマは拒否される可能性がある点も明記されています。

Q5. 構造化出力で受け取ったJSONの値はそのまま信頼してよいですか。

公式ドキュメントのベストプラクティスでは「出力は構文的には正しいJSONだが、値はアプリケーション側で検証する」ことと、「スキーマには準拠しているが意味的には誤っている出力」への堅牢なエラー処理の実装が挙げられています。形式が正しいことと内容が正しいことは別問題として扱う必要があります。

Q6. 生成が長くなる場合、最後まで待たないと結果を使えませんか。

待つ必要はありません。公式ドキュメントには、構造化出力をストリーミングでき、生成中のチャンクを連結すれば最終的なJSONオブジェクトになると説明されています。大量件数をまとめて処理したい場合はBatch APIとの組み合わせも検討できます。

Q7. 投稿内容によって受け取りたい項目が変わる場合はどうすればいいですか。

公式ドキュメントのContent Moderationの例が参考になります。この例ではanyOfを条件付きスキーマに使うことで、コンテンツの内容に応じて出力構造を変えられると説明されています。あわせてenumでspam_typeのような分類項目を、booleanでis_safeのような判定項目を定義する組み合わせが示されており、1つのスキーマの中で条件分岐と分類を両立させたいときの実装例になります。

まとめ

Gemini APIの構造化出力は、モデルの最終回答をJSON Schemaに沿った形式で固定できる機能です。response_formatにスキーマを渡すだけで設定でき、Python・JavaScriptならPydantic・Zodからスキーマを生成できる手軽さがある一方、組み込みツールと組み合わせる場合は2026年9月時点でGemini 3系モデル限定のPreview機能であること、JSON Schema仕様の一部しかサポートしていないこと、値の中身の正しさまでは保証しないことという3つの制限を踏まえて設計する必要があります。

実装の際は、まずGoogle AIの基本的な使い方でAPIキーの取得やリクエストの基礎を確認したうえで、シンプルなスキーマから試し、Function Callingとの役割分担（最終回答の整形か、途中の行動依頼か）を意識して設計すると迷いにくくなります。エージェント的なワークフローに組み込む場合は、Deep Researchのような多段階の処理と組み合わせて、各ステップの出力形式を構造化出力で固定する構成も検討する価値があります。

公式ドキュメントに掲載されているレシピ抽出・コンテンツモデレーション・組織図のような再帰構造という3つの実装例は、いずれも「人が読む文章」ではなく「別のプログラムがそのまま処理できるデータ」を作ることを目的にしています。自社のサービスでGemini APIの回答を後続の処理に渡している箇所があれば、まずはその1箇所を構造化出力に置き換えるところから試してみると、効果と制約の両方を具体的に把握しやすくなります。