Generate JSON output with the Gemini API


Gemini generates unstructured text by default, but some applications require structured text. For these use cases, you can constrain Gemini to respond with JSON, a structured data format suitable for automated processing.

For example, these use cases require structured output from the model:

  • Build a database of companies by pulling company information out of newspaper articles.
  • Pull standardized information out of resumes.
  • Extract ingredients from recipes and display a link to a grocery website for each ingredient.

In your prompt, you can ask Gemini to produce JSON-formatted output, but note that Google can't guarantee that it will produce JSON and nothing but JSON. For a more deterministic response, you can pass a specific JSON schema in a responseSchema field so that Gemini always responds with an expected structure.

This guide shows you how to generate JSON using the generateContent method through the SDK of your choice. It focuses on text-only input, although Gemini can also produce JSON responses to multimodal requests that include images, videos, and audio.

Before you begin: Set up your project and API key

Before calling the Gemini API, you need to set up your project and configure your API key.

Generate JSON

When the model is configured to output JSON, it responds to any prompt with JSON-formatted output.

Control the structure of the JSON response by supplying a schema. There are two ways to supply a schema to the model:

  • As text in the prompt.
  • As a structured schema supplied through model configuration.

Both approaches work in both Gemini 1.5 Flash and Gemini 1.5 Pro.

Supply a schema as text in the prompt

The following example does the following:

  1. Instantiates a model configured to respond with JSON.
  2. Prompts the model to return cookie recipes in a specific JSON format.

Since the model gets the format specification from text in the prompt, you may have some flexibility in how you represent the specification. Any reasonable format for representing a JSON schema may work.

import google.generativeai as genai
import os

genai.configure(api_key=os.environ["API_KEY"])

# Using `response_mime_type` requires either a Gemini 1.5 Pro or 1.5 Flash model
model = genai.GenerativeModel('gemini-1.5-flash',
                              # Set the `response_mime_type` to output JSON
                              generation_config={"response_mime_type": "application/json"})

prompt = """
  List 5 popular cookie recipes.
  Using this JSON schema:
    Recipe = {"recipe_name": str}
  Return a `list[Recipe]`
  """

response = model.generate_content(prompt)
print(response.text)

Output: 

[{"recipe_name": "Chocolate Chip Cookies"}, {"recipe_name": "Oatmeal Raisin Cookies"}, {"recipe_name": "Snickerdoodles"}, {"recipe_name": "Sugar Cookies"}, {"recipe_name": "Peanut Butter Cookies"}]

Supply a schema through model configuration

The following example does the following:

  1. Instantiates a model configured through a schema to respond with JSON.
  2. Prompts the model to return cookie recipes.
import google.generativeai as genai
import typing_extensions as typing

class Recipe(typing.TypedDict):
  recipe_name: str

genai.configure(api_key=os.environ["API_KEY"])

model = genai.GenerativeModel('gemini-1.5-flash',
                              # Set the `response_mime_type` to output JSON
                              # Pass the schema object to the `response_schema` field
                              generation_config={"response_mime_type": "application/json",
                                                 "response_schema": list[Recipe]})

prompt = "List 5 popular cookie recipes"

response = model.generate_content(prompt)
print(response.text)

Output: 

[{"recipe_name": "Chocolate Chip Cookies"}, {"recipe_name": "Peanut Butter Cookies"}, {"recipe_name": "Oatmeal Raisin Cookies"}, {"recipe_name": "Sugar Cookies"}, {"recipe_name": "Snickerdoodles"}]

Schema Definition Syntax

Specify the schema for the JSON response in the response_schema property of your model configuration. The value of response_schema must be a either:

Define a Schema with a Type Hint Annotation

The easiest way to define a schema is with a type hint annotation. This is the approach used in the preceding example:

generation_config={"response_mime_type": "application/json",
                   "response_schema": list[Recipe]}

The Gemini API Python client library supports schemas defined with the following subset of typing annotations (where AllowedType is any allowed type annotation):

  • int
  • float
  • bool
  • str
  • list[AllowedType]
  • For dict types:
    • dict[str, AllowedType]. This annotation declares all dict values to be the same type, but doesn't specify what keys should be included.
    • User-defined subclasses of typing.TypedDict. This approach lets you specify the key names and define different types for the values associated with each of the keys.
    • User-defined Data Classes. Like TypedDict subclasses, this approach lets you specify the key names and define different types for the values associated with each of the keys.
Define a Schema with genai.protos.Schema Protocol Buffer

The Gemini API genai.protos.Schema protocol buffer definition supports a few additional schema features not supported for type hints, including:

  • Enums for strings
  • Specifying the format for numeric types (int32 or int64 for integers, for example)
  • Specifying which fields are required.

If you need these features, instantiate a genai.protos.Schema using one of the methods illustrated in Function Calling: Low Level Access.