Gemini Python SDK gebruiken (google-genai)

Welke SDK gebruik je in 2026?

Google heeft de losse Python-SDK's samengevoegd tot een enkele, uniforme SDK: google-genai. Deze ondersteunt zowel de Gemini Developer API (via Google AI Studio) als Vertex AI.

De oudere SDK google-generativeai is sinds 30 november 2025 deprecated en krijgt geen nieuwe functies meer. Bestaande code blijft voorlopig werken, maar nieuwe projecten gebruiken altijd google-genai. Dit artikel gaat volledig uit van de nieuwe SDK.

Installatie en vereisten

De officiele Python SDK voor de Gemini API heet google-genai:

pip install google-genai

Vereisten:

• Python 3.10 of hoger
• Een Gemini API-sleutel (verkrijgbaar via Google AI Studio)

Voor een geisoleerde omgeving gebruik je een virtual environment:

python -m venv gemini-env
source gemini-env/bin/activate
pip install google-genai

Configuratie

De nieuwe SDK werkt met een Client-object dat je eenmaal aanmaakt en daarna hergebruikt:

from google import genai
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

Geef je geen api_key mee, dan leest de client automatisch de omgevingsvariabele GEMINI_API_KEY uit. Dat is meteen de aanbevolen aanpak: zet de sleutel nooit hardcoded in je code.

Voor lokale ontwikkeling werk je vaak met een .env-bestand:

from dotenv import load_dotenv
from google import genai

load_dotenv()
client = genai.Client()

Installeer python-dotenv voor .env-ondersteuning: pip install python-dotenv.

Je eerste call

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Geef 3 tips voor betere Python-code."
)

print(response.text)

Je roept generatie aan via client.models.generate_content() en geeft de modelnaam als string mee. Het antwoord lees je uit response.text.

Het juiste model kiezen

In juni 2026 is gemini-3.5-flash het aanbevolen stabiele model voor algemene tekstgeneratie. Wil je lagere kosten of latentie, dan is gemini-3.1-flash-lite een sterke, goedkopere variant.

Let op: de oudere gemini-2.5-modellen staan op de planning om medio juni 2026 uitgefaseerd te worden. Vermijd ze voor nieuwe productiecode.

Modelnamen veranderen regelmatig. Vraag de actueel beschikbare modellen op met de SDK zelf, zodat je niet op een verouderde naam blijft hangen:

for model in client.models.list():
    print(model.name, "-", model.display_name)

Configuratie per call

In de nieuwe SDK geef je systeminstructies, generatie-instellingen en veiligheidsfilters mee via een config-object van het type GenerateContentConfig:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Schrijf een korte productbeschrijving.",
    config=types.GenerateContentConfig(
        system_instruction="Je bent een behulpzame assistent.",
        temperature=0.7,
        max_output_tokens=1024,
        top_p=0.9,
        safety_settings=[
            types.SafetySetting(
                category="HARM_CATEGORY_HARASSMENT",
                threshold="BLOCK_MEDIUM_AND_ABOVE",
            ),
            types.SafetySetting(
                category="HARM_CATEGORY_HATE_SPEECH",
                threshold="BLOCK_MEDIUM_AND_ABOVE",
            ),
        ],
    ),
)

print(response.text)

Wil je dezelfde config voor meerdere calls hergebruiken, maak het GenerateContentConfig-object dan eenmaal aan en geef het bij elke call mee. Zo blijft je gedrag consistent en voorkom je herhaling.

Chatsessies

Voor gesprekken met geheugen gebruik je client.chats.create(). De sessie houdt de geschiedenis automatisch bij:

from google import genai

client = genai.Client()

chat = client.chats.create(model="gemini-3.5-flash")

response = chat.send_message("Wat is een lijst-comprehensie in Python?")
print(response.text)

response = chat.send_message("Geef daar een voorbeeld van.")
print(response.text)

Streaming

Wil je tokens tonen zodra ze binnenkomen (bijvoorbeeld in een chatinterface), gebruik dan de stream-variant:

from google import genai

client = genai.Client()

for chunk in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Leg in stappen uit hoe een virtual environment werkt."
):
    print(chunk.text, end="")

Asynchroon gebruik

De SDK biedt een async-interface via client.aio. Handig om meerdere requests parallel uit te voeren:

import asyncio
from google import genai

client = genai.Client()

async def generate_async(prompt: str) -> str:
    response = await client.aio.models.generate_content(
        model="gemini-3.5-flash",
        contents=prompt,
    )
    return response.text

async def main():
    prompts = [
        "Wat is Python?",
        "Wat is JavaScript?",
        "Wat is Rust?",
    ]
    tasks = [generate_async(p) for p in prompts]
    results = await asyncio.gather(*tasks)
    for prompt, result in zip(prompts, results):
        print(f"Vraag: {prompt}")
        print(f"Antwoord: {result[:100]}")
        print()

asyncio.run(main())

Retry-logica bij rate limits

De SDK doet zelf geen herhaalpogingen bij een overschreden rate limit. Voeg dit toe met tenacity (installeer met pip install tenacity):

from tenacity import (
    retry,
    stop_after_attempt,
    wait_exponential,
    retry_if_exception_type,
)
from google.genai import errors

@retry(
    stop=stop_after_attempt(5),
    wait=wait_exponential(multiplier=1, min=4, max=60),
    retry=retry_if_exception_type(errors.APIError),
)
def generate_with_retry(client, prompt: str) -> str:
    response = client.models.generate_content(
        model="gemini-3.5-flash",
        contents=prompt,
    )
    return response.text

Met een exponentiele backoff geef je de API steeds meer tijd tussen pogingen, wat de kans op succes vergroot zonder de service te overbelasten.

Respons-objecten begrijpen

Een respons bevat meer dan alleen tekst. Voor monitoring en kostencontrole zijn vooral de tokentellingen en de reden van afronding nuttig:

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Geef 3 tips voor betere Python-code.",
)

print(response.text)

print(response.candidates[0].finish_reason)

print(response.usage_metadata.prompt_token_count)
print(response.usage_metadata.candidates_token_count)
print(response.usage_metadata.total_token_count)

Een finish_reason van STOP betekent een normale afronding. Andere waarden (zoals MAX_TOKENS of een veiligheidsblokkade) geven aan dat het antwoord vroegtijdig stopte; daar wil je in productie op kunnen reageren.

SDK-versie en updates

Controleer welke versie je draait:

import importlib.metadata
print(importlib.metadata.version("google-genai"))

Houd de SDK actueel, zeker omdat modellen en functies snel veranderen:

pip install --upgrade google-genai

Veelvoorkomende valkuilen

• Code die genai.GenerativeModel(...) of genai.configure(...) gebruikt, hoort bij de oude SDK. Migreer naar genai.Client() en client.models.generate_content().
• Een verouderde modelnaam (zoals een uitgefaseerd gemini-2.5-model) levert fouten op. Vraag de beschikbare modellen op met client.models.list().
• Vergeet config=... niet: systeminstructies en veiligheidsinstellingen geef je in de nieuwe SDK per call mee, niet bij het aanmaken van een modelobject.