# Safety settings in de Gemini API

[[TOC]]

## Hoe veiligheidsfilters werken

Gemini heeft ingebouwde veiligheidsfilters die zowel de input (jouw prompt) als de output (het model-antwoord) controleren op schadelijke inhoud. Als een van beide de ingestelde drempelwaarde overschrijdt, wordt de generatie geblokkeerd.

Er zijn vier aanpasbare schade-categorieën:

- `HARM_CATEGORY_HARASSMENT`: pesterijen, bedreigingen en beledigingen gericht op personen of beschermde kenmerken.
- `HARM_CATEGORY_HATE_SPEECH`: haatdragende, kwetsende of grove taal.
- `HARM_CATEGORY_SEXUALLY_EXPLICIT`: seksueel expliciete inhoud.
- `HARM_CATEGORY_DANGEROUS_CONTENT`: het promoten of faciliteren van gevaarlijke activiteiten.

Naast deze aanpasbare filters heeft Gemini niet-aanpasbare basisbescherming, bijvoorbeeld tegen content rond kinderveiligheid. Die blokkering kun je nooit uitzetten, ongeacht je instellingen.

:::warn title="Gebruik de Google GenAI SDK"
Het oude `google-generativeai`-pakket is sinds eind 2025 niet meer ondersteund. Gebruik het verenigde `google-genai`-pakket (`from google import genai`). De voorbeelden hieronder gaan uit van die SDK.
:::

## Standaard safety instellingen

Bij Gemini 2.5 en 3 staan de vier aanpasbare filters standaard op `OFF`. Het model blokkeert dan niet automatisch op basis van deze categorieën, maar de niet-aanpasbare basisbescherming blijft altijd actief. Wil je wel filteren, stel dan expliciet een drempel per categorie in. Controleer voor productie altijd de actuele standaardwaarden in de officiële documentatie, want die kunnen per modelfamilie verschillen.

## Safety settings aanpassen

In de Google GenAI SDK geef je de instellingen mee als een lijst met `SafetySetting`-objecten binnen `GenerateContentConfig`.

```python
import os
from google import genai
from google.genai import types

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

safety_config = types.GenerateContentConfig(
    safety_settings=[
        types.SafetySetting(
            category=types.HarmCategory.HARM_CATEGORY_HARASSMENT,
            threshold=types.HarmBlockThreshold.BLOCK_ONLY_HIGH,
        ),
        types.SafetySetting(
            category=types.HarmCategory.HARM_CATEGORY_HATE_SPEECH,
            threshold=types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE,
        ),
        types.SafetySetting(
            category=types.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
            threshold=types.HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
        ),
        types.SafetySetting(
            category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
            threshold=types.HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
        ),
    ]
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Jouw vraag hier",
    config=safety_config,
)
print(response.text)
```

## Drempelwaarden begrijpen

| Drempelwaarde | Beschrijving |
|---|---|
| `OFF` | Filter uit; het model blokkeert niet op deze categorie (standaard bij Gemini 2.5 en 3) |
| `BLOCK_NONE` | Laat content altijd door, maar levert wel safety ratings terug |
| `BLOCK_ONLY_HIGH` | Blokkeer alleen bij hoge kans op schade |
| `BLOCK_MEDIUM_AND_ABOVE` | Blokkeer bij gemiddelde of hoge kans |
| `BLOCK_LOW_AND_ABOVE` | Blokkeer bij lage, gemiddelde of hoge kans (streng) |

Het verschil tussen `OFF` en `BLOCK_NONE` is subtiel: beide laten content door, maar `BLOCK_NONE` retourneert nog steeds safety ratings die je zelf kunt gebruiken voor eigen beslislogica. Met `OFF` schakel je de evaluatie op die categorie verder uit.

## Geblokkeerde content detecteren

Een geblokkeerde generatie geeft geen `response.text`. Vang dit netjes af door eerst de prompt-feedback en daarna de `finish_reason` per kandidaat te controleren.

```python
def safe_generate(client, model: str, prompt: str, config=None):
    response = client.models.generate_content(
        model=model,
        contents=prompt,
        config=config,
    )

    feedback = response.prompt_feedback
    if feedback and feedback.block_reason:
        return None, f"Prompt geblokkeerd: {feedback.block_reason.name}"

    for candidate in response.candidates:
        if candidate.finish_reason and candidate.finish_reason.name == "SAFETY":
            geblokkeerd = [
                rating.category.name
                for rating in (candidate.safety_ratings or [])
                if rating.probability.name in ("HIGH", "MEDIUM")
            ]
            return None, f"Antwoord geblokkeerd ({', '.join(geblokkeerd)})"

    return response.text, None


text, error = safe_generate(
    client, "gemini-3.5-flash", "Hoe maak ik een goede samenvatting?"
)
if error:
    print(f"Fout: {error}")
else:
    print(text)
```

:::warn title="Verlaag filters bewust"
Verlaag safety settings alleen als je use case dit echt vereist en je eigen mechanismen hebt om misbruik te voorkomen. Sommige toepassingen (cybersecurity, medisch, juridisch) kunnen een aparte toegangsaanvraag of goedkeuring bij Google vergen voor de meest permissieve instellingen.
:::

## Safety ratings inzien

Elke respons bevat safety ratings die aangeven hoe het model de content heeft beoordeeld. Handig om eigen drempels te bouwen, ook als je de filters zelf op `OFF` of `BLOCK_NONE` zet.

```python
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Vertel me over historische oorlogen.",
)

for rating in response.candidates[0].safety_ratings or []:
    print(f"{rating.category.name}: {rating.probability.name}")
```

De mogelijke kansen zijn `NEGLIGIBLE`, `LOW`, `MEDIUM` en `HIGH`. De drempelwaarde bepaalt bij welke kans er daadwerkelijk geblokkeerd wordt.

## Contextgevoelige safety-aanpassing

Voor verschillende doelgroepen binnen dezelfde applicatie maak je per doelgroep een eigen config. Hieronder een voorbeeld dat strengere filters toepast voor kinderen.

```python
def config_voor_doelgroep(doelgroep: str) -> types.GenerateContentConfig:
    if doelgroep == "kinderen":
        drempel = types.HarmBlockThreshold.BLOCK_LOW_AND_ABOVE
    elif doelgroep == "volwassenen_algemeen":
        drempel = types.HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE
    else:
        drempel = types.HarmBlockThreshold.BLOCK_ONLY_HIGH

    categorieen = [
        types.HarmCategory.HARM_CATEGORY_HARASSMENT,
        types.HarmCategory.HARM_CATEGORY_HATE_SPEECH,
        types.HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT,
        types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
    ]

    return types.GenerateContentConfig(
        safety_settings=[
            types.SafetySetting(category=cat, threshold=drempel)
            for cat in categorieen
        ]
    )
```

## Safety via de REST API

Werk je zonder SDK, dan stuur je `safetySettings` mee als veld in de JSON-body.

```bash
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Jouw vraag hier"}]}],
    "safetySettings": [
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_ONLY_HIGH"
      }
    ]
  }'
```

## Een werkbare aanpak

:::howto title="Zo kies je je safety settings"
1. Begin met de standaard van je modelfamilie en log de `safety_ratings` van echte verkeer.
2. Bepaal per categorie of je doelgroep strengere of lossere filtering nodig heeft.
3. Stel per categorie een expliciete `threshold` in via een `SafetySetting`; vertrouw niet blind op de standaard.
4. Vang geblokkeerde antwoorden af op `block_reason` en `finish_reason` zodat gebruikers nette feedback krijgen.
5. Houd een audittrail van wijzigingen in je filters, zeker bij gevoelige use cases.
:::

:::tip title="Bewaar je API-sleutel veilig"
Zet je `GEMINI_API_KEY` in een omgevingsvariabele of secret manager, nooit hardcoded in je broncode of frontend. Een gelekte sleutel kan op jouw kosten worden misbruikt.
:::

:::faq
### Kan ik de filters volledig uitschakelen?
Voor de vier aanpasbare categorieën kun je `OFF` of `BLOCK_NONE` kiezen. De niet-aanpasbare basisbescherming, zoals rond kinderveiligheid, blijft altijd actief en kun je niet uitzetten.

### Wat is het verschil tussen OFF en BLOCK_NONE?
Beide laten content door zonder automatische blokkering op die categorie. `BLOCK_NONE` retourneert nog wel safety ratings die je voor eigen beslislogica kunt gebruiken, terwijl `OFF` de filtering op die categorie verder uitschakelt.

### Worden mijn API-calls ook los van de filters beoordeeld?
Ja. Google past naast jouw safety settings ook eigen beleidscontroles toe. Content die in strijd is met het gebruiksbeleid kan worden geweigerd, ook bij de meest permissieve instellingen.

### Wat als een legitieme zakelijke vraag geblokkeerd wordt?
Verhoog de drempel voor de relevante categorie, bijvoorbeeld naar `BLOCK_ONLY_HIGH`. Voor medische, juridische of beveiligingstoepassingen is dat vaak de juiste balans tussen veiligheid en bruikbaarheid.

### Welk model moet ik gebruiken in 2026?
Oudere modellen zoals `gemini-2.0-flash` zijn uitgefaseerd. Gebruik een actueel model zoals `gemini-3.5-flash` of `gemini-2.5-flash`, en controleer de modellenpagina in de documentatie voor de meest recente namen.

### Worden de safety ratings bij Google opgeslagen?
API-gebruik valt onder Google's monitoring- en privacybeleid; herhaald misbruik kan tot accountbeperkingen leiden. De ratings krijg je in de respons terug om client-side beslissingen op te baseren; de exacte logging staat beschreven in Google's privacyvoorwaarden.
:::