# Get structured JSON output from the Gemini API

> Make the Gemini API return JSON that matches a Pydantic schema with the google-genai SDK, then parse it into a typed object.

- Canonical: https://guides-ai.com/guides/gemini-api-structured-output/
- Plate 15.22 · Topic: Building with the API (https://guides-ai.com/topics/api/)
- Published: 21 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

The Gemini API can return JSON constrained to a schema, so you skip brittle string parsing. With the `google-genai` SDK you pass a `response_format` on the Interactions API and hand it your schema. The OpenAI equivalent is [structured outputs](/guides/openai-api-structured-outputs/); if you have not called Gemini yet, start with [your first Gemini API request](/guides/gemini-api-first-request/).

## 1. Install google-genai and pydantic

```bash
pip install -U google-genai pydantic
```

Pydantic gives you a schema and client-side validation in one model.

## 2. Define the schema as a Pydantic model

```python
from pydantic import BaseModel

class Recipe(BaseModel):
    name: str
    minutes: int
    ingredients: list[str]
```

A plain Pydantic model whose JSON Schema you send as the response contract.

## 3. Request JSON with response_format

```python
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me a recipe for pancakes.",
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": Recipe.model_json_schema(),
    },
)
```

`response_format` sets the MIME type to JSON and pins the output to your schema.

## 4. Parse the response into the typed object

```python
recipe = Recipe.model_validate_json(interaction.output_text)
print(recipe.name, recipe.minutes)
```

`model_validate_json` turns the JSON text into a typed `Recipe` you can use directly.

## 5. Constrain fields with enums

```python
from typing import Literal
from pydantic import BaseModel

class Ticket(BaseModel):
    priority: Literal["low", "medium", "high"]
    hours: int
```

A `Literal` becomes a JSON Schema enum, so the model must pick one of the allowed values.

Gemini enforces `enum`, `minimum`, and `maximum` on numbers, and `minItems` and `maxItems` on arrays; constraints like `minLength` it does not enforce, so keep validating with Pydantic after parsing. Structured output combined with tools is preview and limited to the Gemini 3 series. Model ids change: take the current one from the [structured output docs](https://ai.google.dev/gemini-api/docs/structured-output) or the models page.

## Verify it worked

`interaction.output_text` should be valid JSON, and `model_validate_json` should return a `Recipe` without raising.

**If it fails:**

- **ValidationError from Pydantic** — the model returned a field your schema forbids; loosen the model or add the field, then re-parse.
- **Plain prose instead of JSON** — you omitted `mime_type: "application/json"`; both the MIME type and the schema are required to force JSON.
- **Unknown model error** — the model id is stale; copy the current id from the Gemini models page.

---

Next: [OpenAI structured outputs](/guides/openai-api-structured-outputs/) · [glossary: structured output](/glossary/#structured-output).