構造化出力
指定された JSON スキーマに準拠したレスポンスを生成するように Gemini モデルを構成できます。これにより、予測可能でタイプセーフな結果が得られ、構造化されていないテキストから構造化データを簡単に抽出できます。
構造化出力の使用は、次のような場合に最適です。
- データ抽出: テキストから名前や日付などの特定の情報を抽出します。
- 構造化分類: テキストを事前定義されたカテゴリに分類します。
- エージェント ワークフロー: ツールまたは API の構造化された入力を生成します。
Google GenAI SDK では、REST API での JSON スキーマのサポートに加えて、 Pydantic（Python）と Zod（JavaScript）を使用してスキーマを定義できます。
この例では、object、array、string、integer などの基本的な JSON スキーマタイプを使用して、テキストから構造化データを抽出する方法を示します。
Python
# This will only work for SDK newer than 2.0.0
from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional
class Ingredient(BaseModel):
name: str = Field(description="Name of the ingredient.")
quantity: str = Field(description="Quantity of the ingredient, including units.")
class Recipe(BaseModel):
recipe_name: str = Field(description="The name of the recipe.")
prep_time_minutes: Optional[int] = Field(description="Optional time in minutes to prepare the recipe.")
ingredients: List[Ingredient]
instructions: List[str]
client = genai.Client()
prompt = """
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
"""
interaction = client.interactions.create(
model="gemini-3-flash-preview",
input=prompt,
response_format={
"type": "text",
"mime_type": "application/json",
"schema": Recipe.model_json_schema()
},
)
recipe = Recipe.model_validate_json(interaction.steps[-1].content[0].text)
print(recipe)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";
const recipeJsonSchema = {
type: "object",
properties: {
recipe_name: {
type: "string",
description: "The name of the recipe."
},
prep_time_minutes: {
type: "integer",
description: "Optional time in minutes to prepare the recipe."
},
ingredients: {
type: "array",
items: {
type: "object",
properties: {
name: { type: "string", description: "Name of the ingredient."},
quantity: { type: "string", description: "Quantity of the ingredient, including units."}
},
required: ["name", "quantity"]
}
},
instructions: {
type: "array",
items: { type: "string" }
}
},
required: ["recipe_name", "ingredients", "instructions"]
};
const recipeSchema = z.fromJSONSchema(recipeJsonSchema);
const client = new GoogleGenAI({});
const prompt = `
Please extract the recipe from the following text.
The user wants to make delicious chocolate chip cookies.
They need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,
1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,
3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.
For the best part, they'll need 2 cups of semisweet chocolate chips.
First, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,
baking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar
until light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry
ingredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons
onto ungreased baking sheets and bake for 9 to 11 minutes.
`;
const interaction = await client.interactions.create({
model: "gemini-3-flash-preview",
input: prompt,
response_format: {
type: 'text',
mime_type: 'application/json',
schema: recipeJsonSchema
},
});
const recipe = recipeSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(recipe);
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3-flash-preview",
"input": "Please extract the recipe from the following text.\nThe user wants to make delicious chocolate chip cookies.\nThey need 2 and 1/4 cups of all-purpose flour, 1 teaspoon of baking soda,\n1 teaspoon of salt, 1 cup of unsalted butter (softened), 3/4 cup of granulated sugar,\n3/4 cup of packed brown sugar, 1 teaspoon of vanilla extract, and 2 large eggs.\nFor the best part, they will need 2 cups of semisweet chocolate chips.\nFirst, preheat the oven to 375°F (190°C). Then, in a small bowl, whisk together the flour,\nbaking soda, and salt. In a large bowl, cream together the butter, granulated sugar, and brown sugar\nuntil light and fluffy. Beat in the vanilla and eggs, one at a time. Gradually beat in the dry\ningredients until just combined. Finally, stir in the chocolate chips. Drop by rounded tablespoons\nonto ungreased baking sheets and bake for 9 to 11 minutes.",
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
"description": "The name of the recipe."
},
"prep_time_minutes": {
"type": "integer",
"description": "Optional time in minutes to prepare the recipe."
},
"ingredients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string", "description": "Name of the ingredient."},
"quantity": { "type": "string", "description": "Quantity of the ingredient, including units."}
},
"required": ["name", "quantity"]
}
},
"instructions": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["recipe_name", "ingredients", "instructions"]
}
}
}
}'
レスポンスの例:
{
"recipe_name": "Delicious Chocolate Chip Cookies",
"ingredients": [
{ "name": "all-purpose flour", "quantity": "2 and 1/4 cups" },
{ "name": "baking soda", "quantity": "1 teaspoon" },
{ "name": "salt", "quantity": "1 teaspoon" },
{ "name": "unsalted butter (softened)", "quantity": "1 cup" },
{ "name": "granulated sugar", "quantity": "3/4 cup" },
{ "name": "packed brown sugar", "quantity": "3/4 cup" },
{ "name": "vanilla extract", "quantity": "1 teaspoon" },
{ "name": "large eggs", "quantity": "2" },
{ "name": "semisweet chocolate chips", "quantity": "2 cups" }
],
"instructions": [
"Preheat the oven to 375°F (190°C).",
"In a small bowl, whisk together the flour, baking soda, and salt.",
"In a large bowl, cream together the butter, granulated sugar, and brown sugar until light and fluffy.",
"Beat in the vanilla and eggs, one at a time.",
"Gradually beat in the dry ingredients until just combined.",
"Stir in the chocolate chips.",
"Drop by rounded tablespoons onto ungreased baking sheets and bake for 9 to 11 minutes."
]
}
結果のストリーミング
構造化出力をストリーミングして、レスポンスの生成中に処理を開始できます。ストリーミングされたチャンクは有効な部分 JSON 文字列であり、連結して最終的な JSON オブジェクトを形成できます。
Python
# This will only work for SDK newer than 2.0.0
from google import genai
from pydantic import BaseModel
from typing import Literal
class Feedback(BaseModel):
sentiment: Literal["positive", "neutral", "negative"]
summary: str
client = genai.Client()
prompt = "The new UI is incredibly intuitive. Add a very long summary to test streaming!"
stream = client.interactions.create(
model="gemini-3-flash-preview",
input=prompt,
response_format={
"type": "text",
"mime_type": "application/json",
"schema": Feedback.model_json_schema()
},
stream=True
)
for event in stream:
if event.event_type == "step.delta" and event.delta.text:
print(event.delta.text, end="")
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";
const feedbackJsonSchema = {
type: "object",
properties: {
sentiment: { type: "string", enum: ["positive", "neutral", "negative"] },
summary: { type: "string" }
},
required: ["sentiment", "summary"]
};
const feedbackSchema = z.fromJSONSchema(feedbackJsonSchema);
const client = new GoogleGenAI({});
const stream = await client.interactions.create({
model: "gemini-3-flash-preview",
input: "The new UI is incredibly intuitive. Add a very long summary!",
response_format: {
type: 'text',
mime_type: 'application/json',
schema: feedbackJsonSchema
},
stream: true,
});
for await (const event of stream) {
if (event.type === "step.delta" && event.delta?.text) {
process.stdout.write(event.delta.text);
}
}
ツールを使用した構造化出力
Gemini 3 では、構造化出力を、Google 検索によるグラウンディング、URL コンテキスト、コード実行、ファイル検索、関数呼び出しなどの組み込みツールと組み合わせることができます。
Python
# This will only work for SDK newer than 2.0.0
from google import genai
from pydantic import BaseModel, Field
from typing import List
class MatchResult(BaseModel):
winner: str = Field(description="The name of the winner.")
final_match_score: str = Field(description="The final match score.")
scorers: List[str] = Field(description="The name of the scorer.")
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.1-pro-preview",
input="Search for all details for the latest Euro.",
tools=[{"type": "google_search"}, {"type": "url_context"}],
response_format={
"type": "text",
"mime_type": "application/json",
"schema": MatchResult.model_json_schema()
},
)
result = MatchResult.model_validate_json(interaction.steps[-1].content[0].text)
print(result)
JavaScript
// This will only work for SDK newer than 2.0.0
import { GoogleGenAI } from "@google/genai";
import * as z from "zod";
const matchJsonSchema = {
type: "object",
properties: {
winner: { type: "string" },
final_match_score: { type: "string" },
scorers: { type: "array", items: { type: "string" } }
},
required: ["winner", "final_match_score", "scorers"]
};
const matchSchema = z.fromJSONSchema(matchJsonSchema);
const client = new GoogleGenAI({});
const interaction = await client.interactions.create({
model: "gemini-3.1-pro-preview",
input: "Search for all details for the latest Euro.",
tools: [{type: "google_search"}, {type: "url_context"}],
response_format: {
type: 'text',
mime_type: 'application/json',
schema: matchJsonSchema
},
});
const match = matchSchema.parse(JSON.parse(interaction.steps.at(-1).content[0].text));
console.log(match);
REST
# Specifies the API revision to avoid breaking changes when they become default
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-3.1-pro-preview",
"input": "Search for all details for the latest Euro.",
"tools": [{"type": "google_search"}, {"type": "url_context"}],
"response_format": {
"type": "text",
"mime_type": "application/json",
"schema": {
"type": "object",
"properties": {
"winner": {"type": "string"},
"final_match_score": {"type": "string"},
"scorers": {"type": "array", "items": {"type": "string"}}
},
"required": ["winner", "final_match_score", "scorers"]
}
}
}'
JSON スキーマのサポート
JSON オブジェクトを生成するには、response_format を text タイプのオブジェクト（またはオブジェクトを含む配列）で構成し、その mime_type を application/json に設定します。スキーマは schema フィールドに指定する必要があります。
Gemini の構造化出力モードでは、 JSON スキーマ仕様のサブセットがサポートされています。
次の type 値がサポートされています。
string: テキストの場合。number: 浮動小数点数の場合。integer: 整数の場合。boolean: true または false の値の場合。object: Key-Value ペアを含む構造化データの場合。array: 項目のリストの場合。null: プロパティを null にする場合は、タイプ配列に"null"を含めます（例:{"type": ["string", "null"]}）。
これらの説明プロパティは、モデルのガイドに役立ちます。
title: プロパティの簡単な説明。description: プロパティの詳細な説明。
タイプ固有のプロパティ
object 値の場合:
properties: 各キーがプロパティ名で、各値がそのプロパティのスキーマであるオブジェクト。required: 必須プロパティを一覧表示する文字列の配列。additionalProperties:propertiesにリストされていないプロパティを許可するかどうかを制御します。ブール値またはスキーマを指定できます。
string 値の場合:
enum: 分類タスクに使用できる特定の文字列のセットを一覧表示します。format: 文字列の構文（date-time、date、timeなど）を指定します。
number 値と integer 値の場合:
enum: 使用できる特定の数値のセットを一覧表示します。minimum: 最小値（包括的）。maximum: 最大値（包括的）。
array 値の場合:
items: 配列内のすべての項目のスキーマを定義します。prefixItems: 最初の N 個の項目のスキーマのリストを定義し、タプルに似た構造を可能にします。minItems: 配列内の項目の最小数。maxItems: 配列内の項目の最大数。
構造化出力と関数呼び出し
| 機能 | 主なユースケース |
|---|---|
| 構造化出力 | 最終的なレスポンスのフォーマット。特定の形式でモデルの回答を取得する場合に使用します。 |
| 関数呼び出し | 会話中のアクション。最終的な回答を提供する前に、モデルにタスクの実行を依頼する必要がある場合に使用します。 |
ベスト プラクティス
- 明確な説明:
descriptionフィールドを使用してモデルをガイドします。 - 厳密な型指定: 特定の型（
integer、string、enum）を使用します。 - プロンプト エンジニアリング: モデルに実行させたいことを明確に記述します。
- 検証: 出力は構文的に正しい JSON ですが、アプリケーションで常に値を検証してください。
- エラー処理: スキーマに準拠しているが意味的に正しくない出力に対して、堅牢なエラー処理を実装します。
制限事項
- スキーマのサブセット: JSON スキーマのすべての機能がサポートされているわけではありません。
- スキーマの複雑さ: 非常に大きいスキーマやネストが深いスキーマは拒否されることがあります。