Générer du JSON structuré avec l'API Gemini : guide développeur

L'article précédentPourquoi les agents d'IA ne peuvent pas vivre sans JSONtracé Tool Calling et MCP saut par saut. Celui-ci regarde leréponse finalele modèle donne à un utilisateur ou à un programme en aval : comment faire en sorte que Gemini émette JSON que vous pouvez analyser, valider et stocker - pas de prose qui ressemble simplement à JSON.

Il s'agit des sorties structurées (génération contrôlée) dans la documentation Gemini. Il partage des idées de schéma avec Function Calling mais une cible différente : la première contraint lecharge utile finale; ce dernier contraintoutil arguments. Gardez-les séparés afin qu'un Agent ne traite pas « extraire une facture » et « appeler le paiement API » comme le même type d'appel.

Trois approches, chacune plus stricte

Les équipes essaient généralement trois façons de « faire en sorte que Gemini produise JSON ». La fiabilité diffère d'un ordre de grandeur :

Everyone has seen the first failure mode: a ```json fence, an extra paragraph, single quotes, a trailing comma. The second layer parses, but price may be a string and items may be missing. The third layer is this tutorial: hand JSON Schema to the API so the decoder avoids illegal paths at each token.

Décodage contraint : pourquoi Schema bat une invite

A prompt only raises the odds that the model wants to comply. Structured Output compiles the Schema into generation: if the next token would break JSON syntax or leave the Schema (for example starting an undeclared field), its probability is suppressed. So response.text is usually a parseable object — no regex to strip fences.

Since 2025 the Gemini API complements the OpenAPI 3.0-style responseSchema with standard JSON Schema (often responseJsonSchema on the wire). Pydantic model_json_schema() and Zod exports can be sent almost as-is. Gemini 2.5 and later also tend to preserve property order from the Schema, which helps CSV columns and tables downstream.

Classification has a side path: responseMimeType: text/x.enum emits only the enum string (for example Keyboard), with no braces. Use application/json when you need an object; use the enum MIME when you need a single label.

Python : un exemple complet de google-genai

Prefer the current SDK google-genai (from google import genai). Do not mix it with the legacy google-generativeai package. With GEMINI_API_KEY set:

from google import genai
from pydantic import BaseModel, Field


class LineItem(BaseModel):
    name: str = Field(description="Product name")
    qty: int = Field(description="Quantity, positive integer")
    unit_price_cents: int = Field(description="Unit price in cents")


class Invoice(BaseModel):
    vendor: str
    currency: str = Field(description="ISO 4217, e.g. CNY")
    items: list[LineItem]
    total_cents: int


client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Extract an invoice from: Acme sold 2 keyboards at 199 CNY each.",
    config={
        "response_mime_type": "application/json",
        "response_schema": Invoice,
    },
)

print(response.text)      # JSON string
invoice = response.parsed  # Invoice instance (Pydantic path)
print(invoice.total_cents)

response.parsed is meaningful when response_schema is a Pydantic or SDK type. If you pass a raw JSON Schema dict (next section), json.loads(response.text) and validate yourself.

For many records use list[Invoice] or wrap invoices: list[Invoice] in an object. An array at the root is less stable on some models than always returning an object; production code usually does the latter.

response_schema vs JSON Schéma

Ne devinez pas quelle clé de configuration utiliser :

• response_schema: un modèle Pydantic, un objet Python Enum ou un objet SDK Schema. Le SDK le mappe au sous-ensemble OpenAPI on-wire.
• response_json_schema: a JSON Schema object (dict). Use it for Invoice.model_json_schema(), Zod toJSONSchema(), and richer keywords such as additionalProperties, minimum / maximum, and prefixItems.

schema = {
  "type": "object",
  "properties": {
    "vendor": { "type": "string" },
    "currency": { "type": "string", "enum": ["CNY", "USD", "EUR"] },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "qty": { "type": "integer", "minimum": 1 },
          "unit_price_cents": { "type": "integer", "minimum": 0 }
        },
        "required": ["name", "qty", "unit_price_cents"],
        "additionalProperties": False
      }
    },
    "total_cents": { "type": "integer" }
  },
  "required": ["vendor", "currency", "items", "total_cents"],
  "additionalProperties": False
}

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Extract the invoice: …",
    config={
        "response_mime_type": "application/json",
        "response_json_schema": schema,
    },
)

Older REST docs use uppercase types in responseSchema (OBJECT, STRING, ARRAY, INTEGER). The JSON Schema path uses lowercase object / string. Do not mix the two keyword sets. Put field meaning in description: it enters the model context and decides whether qty is pieces or cases. Types alone cannot.

À quoi ressemble la requête REST

On the Gemini Developer API, generateContent puts structured output under generationConfig. The key goes in x-goog-api-key or a query param — never in a frontend repo.

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "Extract an invoice from the text: …" }]
    }
  ],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseJsonSchema": {
      "type": "object",
      "properties": {
        "vendor": { "type": "string" },
        "total_cents": { "type": "integer" }
      },
      "required": ["vendor", "total_cents"]
    }
  }
}

On success the candidate text is candidates[0].content.parts[0].text — a JSON string. Vertex AI uses the same field names; only the endpoint and GCP auth change. Images and PDFs can be inputs: the Schema constrains output, not multimodal input.

Comment diviser le travail avec Function Calling

Les deux utilisent Schema pour gouverner JSON, mais ils reposent sur des sauts différents :

Extraction de factures, étiquettes de modération, transformation de notes en liste de tâches : sortie structurée. Recherche d'inventaire, création d'un ticket, lecture d'un fichier repo : outils — voirl'article sur le flux de donnéesetJSON Schéma et évolution MCP. N'utilisez pas la sortie structurée pour prétendre qu'un paiement API a déjà été exécuté — le modèle ne l'a pas appelé.

Validation de l'exécution et pièges courants

Le décodage contraint n’est pas une solution commerciale correcte. Gardez deux portes :

1. Syntax and Schema: after json.loads, validate again with the same JSON Schema (required, enum, minimum).
2. Business invariants: for example sum(item.qty * item.unit_price_cents) == total_cents. Schema cannot express that; you write it.

Pièges courants :

• Mots clés non pris en charge: le dumping d'un projet complet de schéma 2020-12 peut ignorer silencieusement certains mots-clés. Commencez par type / propriétés / requis / enum / éléments, puis ajoutez additionalProperties et min/max.
• Array at the root: { "items": [ ... ] } as an object root is often more reliable.
• Mélanger les commentaires Markdown avec JSON: une fois JSON MIME activé, ne demandez pas également « expliquez d'abord, puis JSON ».
• Troncature: augmentez maxOutputTokens, ou divisez « la liste d'abord, puis remplissez chaque ligne ».
• Clés dans le frontend: les démos à sortie structurée dans les clés API du navigateur fuient. Le schéma peut être public ; la clé reste sur le serveur.

Pendant le développement, conservez le schéma et deux ou trois échantillons positifs/négatifs dans git. Inspectez la structure et les différences localement dans JSON Toolbox — la même habitude de test de contrat que REST, avec Gemini comme consommateur.

FAQ

Résumé

To get structured JSON from Gemini, the order is: Schema first, JSON MIME second, prompt last. The prompt owns meaning (what to extract); the Schema owns shape (what fields look like). Pydantic / Zod are author-friendly fronts; on the wire you send response_schema or response_json_schema.

Run one real invoice or a support transcript: write the Schema → call generateContent once → paste response.text into a validator. Only then wire a database or the next agent. Tool arguments still go through Function Calling / MCP — do not collapse them into one API.