结构化输出 | Gemini API | Google AI for Developers

生成 JSON

您可以通过以下两种方式使用 Gemini API 生成 JSON：

在模型上配置架构

在文本提示中提供架构

在模型上配置架构是生成 JSON 的推荐方法，因为它会限制模型输出 JSON。

配置架构（推荐）

如需将模型限制为生成 JSON，请配置 responseSchema 。然后，模型将以 JSON 格式的输出回答任何问题。

Python

from google import genai
from pydantic import BaseModel
class Recipe(BaseModel):
    recipe_name: str
    ingredients: list[str]
client = genai.Client(api_key="GOOGLE_API_KEY")
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="List a few popular cookie recipes, and include the amounts of ingredients.",
    config={
        "response_mime_type": "application/json",
        "response_schema": list[Recipe],
# Use the response as a JSON string.
print(response.text)
# Use instantiated objects.
my_recipes: list[Recipe] = response.parsed
目前尚不支持 Pydantic 验证器。如果发生 pydantic.ValidationError，系统会将其抑制，并且 .parsed 可能会为空/null。


   
    
     JavaScript
    
    
     
      import { GoogleGenAI, Type } from "@google/genai";
const ai = new GoogleGenAI({ "GOOGLE_API_KEY" });
async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents:
      "List a few popular cookie recipes, and include the amounts of ingredients.",
    config: {
      responseMimeType: "application/json",
      responseSchema: {
        type: Type.ARRAY,
        items: {
          type: Type.OBJECT,
          properties: {
            recipeName: {
              type: Type.STRING,
            ingredients: {
              type: Type.ARRAY,
              items: {
                type: Type.STRING,
          propertyOrdering: ["recipeName", "ingredients"],
  console.log(response.text);
main();
Go
package main
import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "GOOGLE_API_KEY",
        Backend: genai.BackendGeminiAPI,
    if err != nil {
        log.Fatal(err)
    config := &genai.GenerateContentConfig{
        ResponseMIMEType: "application/json",
        ResponseSchema: &genai.Schema{
            Type: genai.TypeArray,
            Items: &genai.Schema{
                Type: genai.TypeObject,
                Properties: map[string]*genai.Schema{
                    "recipeName"




    
: {Type: genai.TypeString},
                    "ingredients": {
                        Type:  genai.TypeArray,
                        Items: &genai.Schema{Type: genai.TypeString},
                PropertyOrdering: []string{"recipeName", "ingredients"},
    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text("List a few popular cookie recipes, and include the amounts of ingredients."),
        config,
    if err != nil {
        log.Fatal(err)
    fmt.Println(result.Text())
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
      "contents": [{
        "parts":[
          { "text": "List a few popular cookie recipes, and include the amounts of ingredients." }
      "generationConfig": {
        "responseMimeType": "application/json",
        "responseSchema": {
          "type": "ARRAY",
          "items": {
            "type": "OBJECT",
            "properties": {
              "recipeName": { "type": "STRING" },
              "ingredients": {
                "type": "ARRAY",
                "items": { "type": "STRING" }
            "propertyOrdering": ["recipeName", "ingredients"]
}' 2> /dev/null | head
输出可能如下所示：
    "recipeName": "Chocolate Chip Cookies",
    "ingredients": [
      "1 cup (2 sticks) unsalted butter, softened",
      "3/4 cup granulated sugar",
      "3/4 cup packed brown sugar",
      "1 teaspoon vanilla extract",
      "2 large eggs",
      "2 1/4 cups all-purpose flour",
      "1 teaspoon baking soda",
      "1 teaspoon salt",
      "2 cups chocolate chips"
在文本提示中提供架构
您可以通过文本提示以自然语言或伪代码的形式提供架构，而无需配置架构。我们不建议使用此方法，因为它可能会生成质量较低的输出，并且模型不受遵循架构的约束。
警告： 如果您要配置 responseSchema，请勿在文本提示中提供架构。这可能会导致意外结果或低质量结果。
下面是一个文本提示中提供的架构的通用示例：
List a few popular cookie recipes, and include the amounts of ingredients.
Produce JSON matching this specification:
Recipe = { "recipeName": string, "ingredients": array<string> }
Return: array<Recipe>
由于模型会从问题中的文本中获取架构，因此您在表示架构的方式上可能会有一定的灵活性。但是，如果您以这种方式内嵌提供架构，模型实际上并不受限于返回 JSON。如需获得更确定性、更高质量的回答，请在模型上配置架构，并避免在文本提示中重复架构。
生成枚举值
在某些情况下，您可能希望模型从选项列表中选择单个选项。如需实现此行为，您可以在架构中传递枚举。您可以在 responseSchema 中可以使用 string 的任何位置使用枚举选项，因为枚举是字符串数组。与 JSON 架构一样，枚举可让您约束模型输出，以满足应用的要求。
例如，假设您正在开发一款应用，用于将乐器分类到以下五个类别之一："Percussion"、"String"、"Woodwind"、"Brass" 或“"Keyboard"”。您可以创建一个枚举来帮助完成此任务。
在以下示例中，您将枚举作为 responseSchema 传递，从而限制模型选择最合适的选项。
Python
from google import genai
import enum
class Instrument(enum.Enum):
  PERCUSSION = "Percussion"
  STRING = "String"
  WOODWIND = "Woodwind"
  BRASS = "Brass"
  KEYBOARD = "Keyboard"
client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': Instrument,
print(response.text)
# Woodwind
JavaScript
import { GoogleGenAI, Type } from "@google/genai";
const ai = new GoogleGenAI({});
const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "What type of instrument is an oboe?",
    config: {
      responseMimeType: "text/x.enum",
      responseSchema: {
        type: Type.STRING,
        enum: ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
console.log(response.text);
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" 




    
\
    -H 'Content-Type: application/json' \
    -d '{
          "contents": [{
            "parts":[
              { "text": "What type of instrument is an oboe?" }
          "generationConfig": {
            "responseMimeType": "text/x.enum",
            "responseSchema": {
              "type": "STRING",
              "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"]
Python 库将转换 API 的类型声明。不过，该 API 接受 OpenAPI 3.0 架构的子集（架构）。
您还可以通过以下两种方式指定枚举。您可以使用 Literal：
Python
Literal["Percussion", "String", "Woodwind", "Brass", "Keyboard"]
您还可以将架构作为 JSON 传递：
Python
from google import genai
client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='What type of instrument is an oboe?',
    config={
        'response_mime_type': 'text/x.enum',
        'response_schema': {
            "type": "STRING",
            "enum": ["Percussion", "String", "Woodwind", "Brass", "Keyboard"],
print(response.text)
# Woodwind
除了基本多选题之外，您还可以在 JSON 架构中的任何位置使用枚举。例如，您可以请求模型提供食谱标题列表，并使用 Grade 枚举为每个标题指定一个热门程度等级：
Python
from google import genai
import enum
from pydantic import BaseModel
class Grade(enum.Enum):
    A_PLUS = "a+"
    A = "a"
    B = "b"
    C = "c"
    D = "d"
    F = "f"
class Recipe(BaseModel):
  recipe_name: str
  rating: Grade
client = genai.Client(api_key="GEMINI_API_KEY")
response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents='List 10 home-baked cookie recipes and give them grades based on tastiness.',
    config={
        'response_mime_type': 'application/json',
        'response_schema': list[Recipe],
print(response.text)
响应可能如下所示：
    "recipe_name": "Chocolate Chip Cookies",
    "rating": "a+"
    "recipe_name": "Peanut Butter Cookies",
    "rating": "a"
    "recipe_name": "Oatmeal Raisin Cookies",
    "rating": "b"
JSON 架构简介
使用 responseSchema 参数将模型配置为 JSON 输出时，需要依赖 Schema 对象来定义其结构。此对象表示 OpenAPI 3.0 架构对象的选定子集，并且还添加了 propertyOrdering 字段。
提示： 在 Python 中，使用 Pydantic 模型时，您无需直接处理 Schema 对象，因为它会自动转换为相应的 JSON 架构。如需了解详情，请参阅 Python 中的 JSON 架构。
下面是所有 Schema 字段的伪 JSON 表示法：
  "type": enum (Type),
  "format": string,
  "description": string,
  "nullable": boolean,
  "enum": [
    string
  "maxItems": integer,
  "minItems": integer,
  "properties": {
    string: {
      object (Schema)
  "required": [
    string
  "propertyOrdering": [
    string
  "items": {
    object (Schema)
架构的 Type 必须是 OpenAPI 数据类型之一，或这些类型的联合（使用 anyOf）。对于每个 Type，只有部分字段有效。以下列表将每个 Type 映射到适用于该类型的字段子集：
string -> enum、format、nullable
integer -> format、minimum、maximum、enum、nullable
number -> format、minimum、maximum、enum、nullable
boolean -> nullable
array -> minItems、maxItems、items、nullable
object -> properties、required、propertyOrdering、nullable
以下是一些示例架构，展示了有效的类型和字段组合：
{ "type": "string", "enum": ["a", "b", "c"] }
{ "type": "string", "format": "date-time" }
{ "type": "integer", "format": "int64" }
{ "type": "number", "format": "double" }
{ "type": "boolean" }
{ "type": "array", "minItems": 3, "maxItems": 3, "items": { "type": ... } }
{ "type": "object",
  "properties": {
    "a": { "type": ... },
    "b": { "type": ... },
    "c": { "type": ... }
  "nullable": true,
  "required": ["c"],
  "propertyOrdering": ["c", "b", "a"]
如需了解 Gemini API 中架构字段的完整文档，请参阅架构参考文档。
媒体资源排序
警告： 配置 JSON 架构时，请务必设置 propertyOrdering[]；提供示例时，请确保示例中的属性顺序与架构一致。
在 Gemini API 中使用 JSON 架构时，属性的顺序非常重要。默认情况下，API 会按字母顺序对房源进行排序，而不保留房源的定义顺序（不过 Google Gen AI SDK 可能会保留此顺序）。如果您向配置了架构的模型提供示例，并且示例的属性顺序与架构的属性顺序不一致，则输出可能会杂乱无章或出乎意料。
为确保属性的排序一致且可预测，您可以使用可选的 propertyOrdering[] 字段。
"propertyOrdering": ["recipeName", "ingredients"]
propertyOrdering[]（不是 OpenAPI 规范中的标准字段）是一个字符串数组，用于确定响应中的属性顺序。通过指定属性的顺序，然后提供按相同顺序排列属性的示例，您有望提高结果的质量。仅当您手动创建 types.Schema 时，才支持 propertyOrdering。
Python 中的架构
使用 Python 库时，response_schema 的值必须为以下某个值：
类型，如在类型注解中所用（请参阅 Python typing 模块）
genai.types.Schema 的实例
genai.types.Schema 的 dict 等效项
定义架构的最简单方法是使用 Pydantic 类型（如上例所示）：
Python
config={'response_mime_type': 'application/json',
        'response_schema': list[Recipe]}
当您使用 Pydantic 类型时，Python 库会为您构建 JSON 架构并将其发送到 API。如需查看更多示例，请参阅 Python 库文档。
Python 库支持使用以下类型定义的架构（其中 AllowedType 是任何允许的类型）：
float
list[AllowedType]
AllowedType|AllowedType|...
对于结构化类型：
dict[str, AllowedType]。此注解声明所有字典值均为同一类型，但未指定应包含哪些键。
用户定义的 Pydantic 模型。通过这种方法，您可以指定键名称，并为与每个键关联的值定义不同的类型，包括嵌套结构。
JSON 架构支持
JSON 架构比 Schema 对象所依据的 OpenAPI 3.0 规范更为新。我们目前提供 JSON 架构的预览版支持，使用字段 responseJsonSchema 接受任何 JSON 架构，但存在以下限制：
它仅适用于 Gemini 2.5。
虽然可以传递所有 JSON 架构属性，但并非所有属性都受支持。如需了解详情，请参阅该字段的文档。
递归引用只能用作非必需对象属性的值。
递归引用会根据架构的大小展开到有限程度。
包含 $ref 的架构除了以 $ 开头的属性之外，不能包含任何其他属性。
下面的示例展示了如何使用 Pydantic 生成 JSON 架构并将其提交给模型：
curl "https://generativelanguage.googleapis.com/v1alpha/models/\
gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d @- <<EOF
  "contents": [{
    "parts":[{
      "text": "Please give a random example following this schema"
  "generationConfig": {
    "response_mime_type": "application/json",
    "response_json_schema": $(python3 - << PYEOF
from enum import Enum
from typing import List, Optional, Union, Set
from pydantic import BaseModel, Field, ConfigDict
import json
class UserRole(str, Enum):
    ADMIN = "admin"
    VIEWER = "viewer"
class Address(BaseModel):
    street: str
    city: str
class UserProfile(BaseModel):
    username: str = Field(description="User's unique name")
    age: Optional[int] = Field(ge=0, le=120)
    roles: Set[UserRole] = Field(min_items=1)
    contact: Union[Address, str]
    model_config = ConfigDict(title="User Schema")
# Generate and print the JSON Schema
print(json.dumps(UserProfile.model_json_schema(), indent=2))
PYEOF
使用 SDK 时尚不支持直接传递 JSON 架构。
使用响应架构时，请牢记以下注意事项和最佳实践：
回答架构的大小会计入输入 token 限制。
默认情况下，字段是可选的，这意味着模型可以填充字段或跳过字段。您可以将字段设置为必填字段，以强制模型提供值。如果关联的输入提示中上下文不足，模型会主要基于其训练所依据的数据生成回答。
复杂的架构可能会导致 InvalidArgument: 400 错误。复杂性可能来自属性名称过长、数组长度限制过长、枚举值过多、对象具有许多可选属性，或者是这些因素的组合。
如果您在使用有效架构时看到此错误，请进行以下一项或多项更改以解决此错误：
缩短属性名称或枚举名称。
展平嵌套数组。
减少存在限制的属性的数量，例如具有下限和上限的数量。
减少存在复杂限制的属性的数量，例如采用 date-time 等复杂格式的属性。
减少可选属性的数量。
减少枚举的有效值数量。
如果您未看到预期结果，请在输入提示中添加更多上下文或修改响应架构。例如，查看非结构化输出情况下模型的响应，以了解模型的响应方式。然后，您可以更新响应架构，使其更贴合模型的输出。
现在，您已经了解了如何生成结构化输出，不妨试试使用 Gemini API 工具：
使用 Google 搜索建立依据
  如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
  最后更新时间 (UTC)：2025-07-09。
      [[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["没有我需要的信息","missingTheInformationINeed","thumb-down"],["太复杂/步骤太多","tooComplicatedTooManySteps","thumb-down"],["内容需要更新","outOfDate","thumb-down"],["翻译问题","translationIssue","thumb-down"],["示例/代码问题","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-07-09。"],[],[]]