Gemini API best practices: systeeminstructies, gestructureerde JSON en streaming

Een werkende aanvraag naar de Gemini API is snel gemaakt, maar in een echte applicatie wil je voorspelbaar gedrag, antwoorden die je code betrouwbaar kan verwerken en een responsieve gebruikerservaring. Deze gids behandelt drie technieken die daarbij helpen. De voorbeelden gebruiken de officiele Google Gen AI SDK voor Python (google-genai). In de Node.js-SDK (@google/genai) heten de methoden vergelijkbaar.

De codevoorbeelden gebruiken gemini-3.5-flash, het stabiele flash-model dat Google in 2026 aanraadt voor productie. Het oudere gemini-2.5-flash werkt nog steeds en is een prima keuze voor goedkope, hoge-volume taken. Modelnamen wisselen, dus controleer altijd de officiele modeloverzicht-pagina voordat je een naam vastlegt.

1. Gedrag sturen met systeeminstructies

Een systeeminstructie vertelt het model wie het is en hoe het moet antwoorden, los van de eigenlijke gebruikersvraag. Het is de plek voor rol, toon, taal en regels die voor elke aanvraag gelden.

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Hoe reset ik mijn wachtwoord?",
    config=types.GenerateContentConfig(
        system_instruction="Je bent een behulpzame supportmedewerker. Antwoord beknopt in het Nederlands en in een vriendelijke, professionele toon.",
    ),
)
print(response.text)

2. Voorspelbare antwoorden met gestructureerde JSON

Vrije tekst is lastig te verwerken in code. Wil je het antwoord automatisch inlezen, vraag dan om gestructureerde uitvoer. Je stelt response_mime_type in op application/json en geeft via response_schema een schema mee dat de vorm van het antwoord beschrijft.

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Geef drie kernpunten uit deze tekst: ...",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "object",
            "properties": {
                "kernpunten": {
                    "type": "array",
                    "items": {"type": "string"},
                }
            },
            "required": ["kernpunten"],
        },
    ),
)
print(response.text)

Het model levert nu JSON die aan je schema voldoet, zodat je het antwoord direct kunt parsen zonder fragiele tekstverwerking. In Python kun je het schema ook met een Pydantic-model definieren en dat doorgeven als response_schema; de SDK vertaalt het dan voor je.

3. Snellere weergave met streaming

Bij langere antwoorden hoeft je gebruiker niet te wachten tot alles klaar is. Met streaming ontvang je het antwoord stuksgewijs en toon je tekst zodra die binnenkomt. Gebruik daarvoor generate_content_stream:

from google import genai

client = genai.Client()
for chunk in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Schrijf een korte uitleg over cloudopslag.",
):
    print(chunk.text, end="")

Elke chunk bevat een stukje van het antwoord. In een webapplicatie stuur je die stukjes door naar de browser, bijvoorbeeld via Server-Sent Events, zodat de tekst geleidelijk verschijnt.

Je kunt streaming en gestructureerde JSON combineren. De stukjes zijn dan geldige deel-JSON die je aan elkaar plakt tot het volledige object klaar is. Parse pas wanneer de stream compleet is, anders werk je met half ontvangen JSON.

Praktische aandachtspunten

Naast deze drie technieken houden een paar gewoonten je integratie robuust:

• Sleutel op de server. Roep de Gemini API aan vanaf je backend, nooit rechtstreeks vanuit de browser, zodat je API-sleutel geheim blijft.
• Vang fouten op. Netwerkproblemen, snelheidslimieten en geblokkeerde inhoud horen erbij. Bouw nette foutafhandeling en een bericht voor de gebruiker.
• Wees zuinig met tokens. Stuur alleen de context die nodig is. Korte prompts zijn sneller en goedkoper.
• Houd modelnamen actueel. Modellen worden vernieuwd en uitgefaseerd. Controleer de officiele Gemini API-documentatie voordat je een naam vastlegt in productie.

Met systeeminstructies, gestructureerde uitvoer en streaming til je een eenvoudige proef-aanvraag naar een integratie die voorspelbaar, verwerkbaar en prettig in gebruik is.