# Gemini Python SDK gebruiken (google-genai)

[[TOC]]

## 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.

:::warn title="Niet meer beginnen met google-generativeai"
Kom je online voorbeelden tegen met `import google.generativeai as genai` en `genai.GenerativeModel(...)`, dan kijk je naar de oude, deprecated SDK. Het nieuwe patroon werkt met een centrale `client` in plaats van losse modelobjecten.
:::

## Installatie en vereisten

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

```bash
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:

```bash
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:

```python
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:

```python
from dotenv import load_dotenv
from google import genai

load_dotenv()
client = genai.Client()
```

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

:::warn title="Zet je sleutel niet in versiebeheer"
Voeg `.env` toe aan je `.gitignore` en deel API-sleutels nooit via Git, screenshots of logbestanden. Een gelekte sleutel kan direct kosten veroorzaken op je project.
:::

## Je eerste call

```python
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:

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

:::tip title="Gebruik specifieke modelnamen in productie"
Voor reproduceerbaar gedrag verwijs je in productie naar een specifieke stabiele modelnaam (bijvoorbeeld `gemini-3.5-flash`) en niet naar een alias die later naar een nieuwer model kan wijzen. Test elke modelwissel eerst in een staging-omgeving.
:::

## Configuratie per call

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

```python
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:

```python
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:

```python
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:

```python
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`):

```python
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:

```python
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:

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

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

```bash
pip install --upgrade google-genai
```

:::tip title="Pin je versie in productie"
Leg de exacte versie vast in een `requirements.txt` (bijvoorbeeld `google-genai==2.7.0`) en upgrade bewust, na het lezen van de release-notes. Zo voorkom je dat een onverwachte update je productie verrast.
:::

## 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.

:::faq
### Wat is het verschil tussen `google-generativeai` en `google-genai`?
`google-genai` is de huidige, uniforme SDK die zowel de Gemini Developer API als Vertex AI ondersteunt. `google-generativeai` is de oudere SDK en is sinds eind 2025 deprecated. Nieuwe projecten gebruiken altijd `google-genai`.

### Welk Gemini-model gebruik ik voor een nieuw project?
In juni 2026 is `gemini-3.5-flash` het aanbevolen stabiele model voor algemene tekstgeneratie, met `gemini-3.1-flash-lite` als goedkopere variant. Vraag de actuele lijst altijd op met `client.models.list()`, want modelnamen wijzigen geregeld.

### Werkt de Python SDK ook op Apple Silicon (M-serie)?
Ja. De SDK is pure Python en werkt op alle platforms zonder native extensies, dus ook op Apple Silicon.

### Hoe gebruik ik de SDK achter een proxy?
Stel de omgevingsvariabelen `HTTP_PROXY` en `HTTPS_PROXY` in. De SDK respecteert deze standaard proxy-instellingen voor uitgaande HTTPS-verzoeken.

### Kan ik de SDK gebruiken in serverloze omgevingen zoals Lambda of Cloud Functions?
Ja. Houd wel rekening met cold start-tijd en de maximale uitvoeringstijd van de functie. Maak de client buiten de handler aan zodat hij over warme invocaties hergebruikt wordt, en kies streaming alleen als de runtime dat ondersteunt.

### Moet ik mijn API-sleutel meegeven aan `genai.Client()`?
Niet per se. Zet je de sleutel in de omgevingsvariabele `GEMINI_API_KEY`, dan pakt `genai.Client()` die automatisch op. Dat is veiliger dan de sleutel in je code zetten.
:::