# Tekst genereren met de Gemini API

[[TOC]]

## Wat is de Gemini API

De Gemini API is de programmatische toegang tot Google's Gemini-taalmodellen. Via REST of de officiële SDK's (Python, JavaScript/TypeScript, Go, Java) stuur je prompts en ontvang je gegenereerde tekst, code, samenvattingen en meer. De API is bereikbaar via Google AI Studio (om te experimenteren) en via Vertex AI (voor productie).

Voor de meeste ontwikkelaars is Google AI Studio het startpunt: gratis API-sleutels, een directe playground en een overzicht van alle ondersteunde modellen. Daarna stap je over naar Vertex AI zodra je productie-eisen hebt op het gebied van SLA, VPC Service Controls of enterprise-facturering.

:::info title="Eén unified SDK sinds Gemini 2.0"
De oude bibliotheken `google-generativeai` (Python) en `@google/generative-ai` (JavaScript) zijn sinds 30 november 2025 deprecated en worden niet meer onderhouden. Gebruik de nieuwe unified Google GenAI SDK: `google-genai` (Python) en `@google/genai` (JavaScript). De voorbeelden in dit artikel gebruiken de nieuwe SDK.
:::

## Vereisten en API-sleutel aanmaken

Voordat je code schrijft heb je een API-sleutel nodig.

:::howto title="API-sleutel aanmaken in Google AI Studio"
1. Ga naar [Google AI Studio](https://aistudio.google.com).
2. Klik rechtsboven op **Get API key**.
3. Kies **Create API key in new project** of koppel aan een bestaand Google Cloud-project.
4. Kopieer de sleutel en sla hem op in een omgevingsvariabele: `GEMINI_API_KEY`.
:::

:::warn title="Commit je sleutel nooit"
Zet API-sleutels nooit in een Git-repository. Gebruik altijd een `.env`-bestand (en zet dat in `.gitignore`) of een secret manager zoals Google Secret Manager of HashiCorp Vault. Een gelekte sleutel kan onbeperkt op jouw rekening draaien tot je hem intrekt.
:::

De gratis tier (Gemini Developer API) is bedoeld om te testen en kleine projecten te draaien. De exacte limieten verschillen per model en wijzigen regelmatig; raadpleeg de actuele [rate limits](https://ai.google.dev/gemini-api/docs/rate-limits)-pagina. In juni 2026 valt `gemini-2.5-flash` onder de gratis tier, terwijl de Pro-modellen achter facturering staan. Voor hogere limieten activeer je betaling in het gekoppelde Google Cloud-project.

## Welk model kies je

Houd er rekening mee dat modelnamen snel verouderen. Oudere modellen zoals `gemini-2.0-flash` en `gemini-1.5-pro` zijn inmiddels afgesloten. Controleer altijd de [modellenpagina](https://ai.google.dev/gemini-api/docs/models) voor de actuele lijst. Stand juni 2026:

| Model | Geschikt voor |
|---|---|
| `gemini-2.5-flash` | Snelle, kostenefficiënte tekstgeneratie met redenering. Goede standaardkeuze. |
| `gemini-2.5-flash-lite` | Hoogvolume, laagste kosten en latency. |
| `gemini-2.5-pro` | Complexe redenering, lange context en hoge nauwkeurigheid. |
| `gemini-3.5-flash` | Nieuwste lijn met sterke prestaties op agent- en codeertaken. |

In de voorbeelden hieronder gebruiken we `gemini-2.5-flash` als veilige standaard.

## Eerste API-call via cURL

De snelste manier om de API te testen is via cURL, zonder iets te installeren. Geef je sleutel mee in de `x-goog-api-key`-header (veiliger dan de oude `?key=`-query, want hij belandt niet in serverlogs of browsergeschiedenis):

```bash
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Geef een korte uitleg van het begrip machine learning."}]
      }
    ]
  }'
```

Het antwoord heeft de volgende structuur:

```json
{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "Machine learning is..."}],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 14,
    "candidatesTokenCount": 120,
    "totalTokenCount": 134
  }
}
```

Het gegenereerde antwoord lees je uit via `candidates[0].content.parts[0].text`.

## Generatieparameters instellen

Je stuurt het gedrag van de tekstgeneratie via `generationConfig`:

```json
{
  "contents": [
    {
      "role": "user",
      "parts": [{"text": "Schrijf een productbeschrijving."}]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "topP": 0.9,
    "topK": 40,
    "maxOutputTokens": 512,
    "stopSequences": ["---"]
  }
}
```

| Parameter | Uitleg |
|---|---|
| `temperature` | Hogere waarde geeft creatiever resultaat, lager geeft deterministischer resultaat. |
| `topP` | Nucleus sampling: de cumulatieve kans waarbinnen tokens worden gekozen. |
| `topK` | Aantal kandidaat-tokens dat per stap wordt overwogen. |
| `maxOutputTokens` | Maximum aantal tokens in het antwoord (model-afhankelijk). |
| `stopSequences` | Reeksen waarop de generatie vroegtijdig stopt. |

:::tip title="Kies temperature op de taak"
Voor feitelijke taken (samenvatten, gegevens extraheren) werkt een lage `temperature` van 0.2 tot 0.4 het best, omdat het antwoord dan voorspelbaarder is. Voor creatieve taken (teksten schrijven, brainstormen) geeft 0.8 tot 1.0 meer variatie.
:::

## Tekst genereren met Python

Installeer de unified SDK:

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

De API-sleutel wordt automatisch uit de omgevingsvariabele `GEMINI_API_KEY` gelezen:

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

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Leg uit wat een API is in eenvoudige bewoordingen.",
    config=types.GenerateContentConfig(
        temperature=0.4,
        max_output_tokens=512,
    ),
)

print(response.text)
```

## Tekst genereren met JavaScript

Installeer de unified SDK:

```bash
npm install @google/genai
```

```javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Wat is het verschil tussen AI en ML?",
  config: {
    temperature: 0.4,
    maxOutputTokens: 512,
  },
});

console.log(response.text);
```

Net als bij Python leest de SDK de sleutel uit `GEMINI_API_KEY`. Wil je hem expliciet meegeven, dan kan dat via `new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY })`.

## Context meegeven met meerdere turns

Voor een enkelvoudige prompt is één `contents`-item genoeg. Wil je een gesprek of voorbeelden meegeven, dan voeg je extra turns toe met afwisselend `role: user` en `role: model`:

```json
{
  "contents": [
    { "role": "user", "parts": [{"text": "Vertaal 'hello' naar het Nederlands."}] },
    { "role": "model", "parts": [{"text": "hallo"}] },
    { "role": "user", "parts": [{"text": "En 'goodbye'?"}] }
  ]
}
```

:::tip title="Stuur het model met een systeeminstructie"
Geef vaak een `systemInstruction` mee om de toon, stijl en grenzen van het model vast te leggen, bijvoorbeeld "Antwoord altijd in het Nederlands en in maximaal drie zinnen". Zo hoef je dat niet in elke prompt te herhalen.
:::

## Antwoorden veilig verwerken

Vertrouw nooit blind op de structuur van het antwoord. Een betrouwbare extractie in Python:

```python
def extract_text(response) -> str:
    try:
        return response.candidates[0].content.parts[0].text
    except (IndexError, AttributeError, TypeError):
        return ""
```

Controleer daarnaast `finishReason`:

- `STOP`: de generatie is normaal afgerond.
- `MAX_TOKENS`: het antwoord is afgekapt; verhoog `maxOutputTokens` of vraag een korter antwoord.
- `SAFETY`: de output is geblokkeerd door een safety-filter; pas je prompt aan.

:::faq
### Welk model kies ik voor tekstgeneratie?
Voor de meeste toepassingen is `gemini-2.5-flash` een goede standaard: snel en kostenefficiënt. Kies `gemini-2.5-pro` voor complexe redenering, lange context of hoge nauwkeurigheid. Controleer altijd de modellenpagina, want oudere modellen zoals `gemini-2.0-flash` zijn afgesloten.

### Moet ik de oude of de nieuwe SDK gebruiken?
Gebruik de nieuwe unified Google GenAI SDK (`google-genai` voor Python, `@google/genai` voor JavaScript). De oudere `google-generativeai` en `@google/generative-ai` zijn sinds eind 2025 deprecated en krijgen geen nieuwe functies meer.

### Hoe geef ik mijn API-sleutel het veiligst mee?
Gebruik de `x-goog-api-key`-header in plaats van de `?key=`-query. De header belandt niet in serverlogs, proxylogs of browsergeschiedenis. Bewaar de sleutel in een omgevingsvariabele of secret manager, nooit in je broncode.

### Hoe weet ik hoeveel tokens mijn prompt verbruikt?
Lees `usageMetadata` uit het antwoord (`promptTokenCount`, `candidatesTokenCount`, `totalTokenCount`) of roep vooraf de `countTokens`-methode aan.

### Wat doe ik bij een leeg antwoord?
Controleer eerst `finishReason`. Bij `SAFETY` is de prompt of het antwoord gefilterd; herformuleer dan je prompt. Vang in code altijd het geval af dat `candidates` leeg is, zodat je app niet crasht.

### Kan ik meerdere kandidaatantwoorden tegelijk opvragen?
Ja, via `candidateCount` in `generationConfig`. Niet elk model of elke tier ondersteunt meer dan één kandidaat; controleer de documentatie van het model dat je gebruikt.
:::