はじめに
Gemini APIをアプリケーションやデータ処理に組み込むとき、自由文の回答をそのまま扱うよりも、JSONのような決まった形で受け取れると後処理がしやすくなります。
Google AI for Developersの公式ドキュメントでは、Gemini APIの Structured outputs として、モデルの応答をJSON Schemaに沿った形式で生成する方法が案内されています。PythonではPydanticのモデルからJSON Schemaを作り、Gemini APIへ渡す書き方ができます。
この記事では、Google Colab上で google-genai を使い、Gemini APIの出力をJSONとして受け取り、Pydanticで検証するところまでを小さく整理します。
※本記事は2026-08-02時点で確認した公式情報をもとにした個人の整理メモです。Gemini APIのSDK、モデル名、料金、利用条件は変更される可能性があります。
この記事でやること
この記事では、次の流れを扱います。
- ColabでGemini APIを使う準備をする
-
response_formatでJSON出力を指定する - PydanticモデルからJSON Schemaを作る
- 応答JSONをPydanticで検証する
- 使うときの注意点を整理する
なお、ここでは最小構成を確認するため、複雑なRAGや外部ツール連携は扱いません。
前提
- Google Colabを使う
- Gemini APIキーを取得済み
- Python SDKとして
google-genaiを使う - APIキーはコードに直接書かず、Colab Secretsから読み込む
Colab Secretsを使う場合、左側メニューの「鍵」アイコンから、たとえば GEMINI_API_KEY という名前でAPIキーを登録しておきます。
1. SDKをインストールする
Colabのセルで、まずSDKをインストールします。
%pip install -U -q "google-genai>=2.9.0" pydantic
Google Gemini CookbookのJSON Mode Quickstartでは、Interactions API向けの例として google-genai>=2.9.0 が使われています。
2. APIキーを読み込んでクライアントを作る
APIキーは記事やノートブックに直接書かず、Colab Secretsから読み込みます。
from google.colab import userdata
from google import genai
GEMINI_API_KEY = userdata.get("GEMINI_API_KEY")
client = genai.Client(api_key=GEMINI_API_KEY)
公開記事にする場合、APIキー、組織ID、社内データなどが出力やスクリーンショットに含まれていないか確認しておくと安全です。
3. まずはJSONとして返す指定をする
Structured Outputを本格的に使う前に、まずは「JSONだけを返してほしい」と指定する最小例を確認します。
import json
MODEL_ID = "gemini-3.6-flash"
prompt = """
次のJSONスキーマに沿って、架空の社内勉強会テーマを3件作ってください。
StudyTopic = {'title': str, 'target_reader': str}
Return: list[StudyTopic]
"""
interaction = client.interactions.create(
model=MODEL_ID,
input=prompt,
response_format={"type": "text", "mime_type": "application/json"},
)
text = interaction.steps[-1].content[0].text
items = json.loads(text)
print(json.dumps(items, ensure_ascii=False, indent=2))
ポイントは response_format={"type": "text", "mime_type": "application/json"} の部分です。
これにより、Markdownのコードブロックや説明文を混ぜず、JSONとして扱いやすい形で返すことを期待できます。
ただし、この段階では「どのフィールドを必ず含めるか」「値の型をどうするか」といった厳密な指定は弱いです。そこで次に、PydanticモデルからJSON Schemaを作って渡します。
4. Pydanticでスキーマを定義する
ここでは、勉強会テーマを表す小さなモデルを作ります。
from pydantic import BaseModel, Field
from typing import List
class StudyTopic(BaseModel):
title: str = Field(description="勉強会テーマのタイトル")
target_reader: str = Field(description="想定読者")
learning_points: List[str] = Field(description="読者が学べること")
BaseModel を使うと、Python側で扱うデータ構造を先に定義できます。
さらに、Pydanticの model_json_schema() を使うと、このモデルからJSON Schemaを生成できます。
import json
print(json.dumps(StudyTopic.model_json_schema(), ensure_ascii=False, indent=2))
スキーマをコードから生成できるため、手書きのJSON SchemaとPython側の型定義がずれるリスクを減らしやすくなります。
ここで確認している StudyTopic.model_json_schema() は、単一の StudyTopic オブジェクト用のスキーマです。今回のように「3件のテーマをリストで受け取りたい」場合は、次の節でリスト用のスキーマを作って渡します。
5. リスト用のスキーマをGemini APIに渡す
次に、Pydanticモデルから作ったJSON Schemaを response_format に渡します。
ここでは「勉強会テーマを3件」返してほしいため、応答全体は StudyTopic の単一オブジェクトではなく、list[StudyTopic] になる想定です。そのため、StudyTopic.model_json_schema() をそのまま渡すのではなく、Pydanticの TypeAdapter からリスト用のJSON Schemaを作ります。
from typing import List
from pydantic import TypeAdapter
TopicsAdapter = TypeAdapter(List[StudyTopic])
prompt = """
Python初心者向けに、Gemini APIを学ぶための社内勉強会テーマを3件提案してください。
各テーマには、タイトル、想定読者、学べることを含めてください。
"""
result = client.interactions.create(
model=MODEL_ID,
input=prompt,
response_format={
"type": "text",
"mime_type": "application/json",
"schema": TopicsAdapter.json_schema(),
},
)
raw_json = result.steps[-1].content[0].text
print(raw_json)
ポイントは、期待する出力全体の形に合わせてスキーマを作ることです。
- 1件だけ返すなら
StudyTopic.model_json_schema() - 複数件のリストで返すなら
TypeAdapter(List[StudyTopic]).json_schema()
公式サンプルでも、response_format の schema にPydanticから生成したJSON Schemaを渡す例が示されています。また、Interactions APIの応答からテキストを取り出す方法として interaction.steps[-1].content[0].text が使われています。
6. Pydanticで検証してPythonオブジェクトとして扱う
JSON文字列をそのまま使うのではなく、Pydanticで検証してから扱うと、後続処理でのエラーに気づきやすくなります。
topics = TopicsAdapter.validate_json(raw_json)
for topic in topics:
print(f"# {topic.title}")
print(f"想定読者: {topic.target_reader}")
print("学べること:")
for point in topic.learning_points:
print(f"- {point}")
print()
このようにしておくと、以降の処理では topic.title や topic.learning_points のように、Pythonオブジェクトとして扱えます。
7. DataFrameに変換して確認する
Colabで試す場合は、最後に pandas.DataFrame にして眺めると、出力結果を確認しやすいです。
import pandas as pd
df = pd.DataFrame([topic.model_dump() for topic in topics])
df
learning_points のようなリスト項目はセル内に配列として入ります。CSVなどに出す場合は、用途に合わせて文字列へ変換するか、別テーブルとして扱うとよさそうです。
Structured Outputを使うと何がうれしいか
個人的には、Structured Outputは「LLMの回答をアプリケーションで扱いやすい形に寄せるための仕組み」と捉えると理解しやすいです。
たとえば、次のような場面で便利です。
- 問い合わせ文から項目を抽出する
- 文章をカテゴリ分類する
- 回答結果をDataFrameやDBに入れる
- 次のAPI呼び出しに渡す入力を作る
- UI表示用のデータ構造を作る
自由文のままでは、後処理のたびに正規表現や文字列分割に頼りがちです。最初からJSONとして受け取れると、処理の見通しがよくなります。
注意点
1. 生成結果は必ず検証する
Structured Outputを指定していても、実運用ではPython側での検証を入れておくのが安全です。
Pydanticで validate_json() することで、期待した型や必須項目から外れた場合に気づきやすくなります。
特に、単一オブジェクトを期待しているのか、リストを期待しているのかは、スキーマ作成時点で合わせておく必要があります。スキーマと検証側の型がずれていると、生成結果が正しくてもPython側で扱いにくくなります。
2. スキーマは小さく始める
最初から複雑なネスト構造や多数のフィールドを要求すると、プロンプトも後処理も読みにくくなります。
まずは、次のような小さい構造から試すのがよさそうです。
class SimpleItem(BaseModel):
title: str
summary: str
その後、必要に応じてフィールドやネストを増やすと整理しやすいです。
3. モデル名やSDKの書き方は変わる可能性がある
Gemini APIは更新が速いため、記事を公開する前に次の点を再確認しておく必要があります。
- 公式ドキュメント上の推奨API
- SDKのバージョン
- 利用するモデル名
- Structured Outputの対応状況
- 料金、レート制限、利用可能リージョン
特に、古い記事では generate_content 系のサンプルが多く見つかる可能性があります。この記事では、2026-08-02時点の公式ドキュメントで案内されているInteractions API側の書き方に寄せています。
まとめ
この記事では、Google Colab上でGemini APIのStructured Outputを試す流れを整理しました。
-
response_formatでJSON出力を指定できる - Pydanticモデルや
TypeAdapterからJSON Schemaを生成できる - Gemini APIの応答をPydanticで検証してから扱える
- DataFrame化するとColab上で結果を確認しやすい
- 公開前には、SDK、モデル名、提供条件を公式情報で再確認する
LLMの出力を「読むための文章」ではなく「後処理しやすいデータ」として扱いたい場合、Structured Outputは最初に試しておきたい機能だと感じました。














