Tokens tellen met de Gemini API

Waarom tokens tellen

Tokens zijn de rekeneenheid van taalmodellen. Een token is gemiddeld zo'n 4 tekens in het Engels en 3 tot 4 tekens in het Nederlands. Tokentelling helpt je bij vier dingen:

• Kostenschatting: bereken vooraf de verwachte kosten van je prompts.
• Context-limietbeheer: voorkom fouten doordat je input het contextvenster overschrijdt.
• Efficientie: optimaliseer prompts en bespaar onnodige tokens.
• Debugging: begrijp waarom een call duurder of goedkoper uitvalt dan verwacht.

Het tellen zelf is gratis. De count_tokens-methode kost geen credits en heeft een eigen quotum van ongeveer 3.000 verzoeken per minuut.

Tokens tellen voor een call

from google import genai
import os

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

prompt = "Schrijf een gedetailleerde uitleg van hoe het internet werkt."

count_result = client.models.count_tokens(
    model="gemini-2.5-flash",
    contents=prompt,
)
print(f"Tokenaantal: {count_result.total_tokens}")

kosten_per_miljoen = 0.30
geschatte_kosten = (count_result.total_tokens / 1_000_000) * kosten_per_miljoen
print(f"Geschatte inputkosten: ${geschatte_kosten:.6f}")

Tokens tellen na een call

Elke respons bevat usage_metadata met het exacte verbruik:

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Wat is de hoofdstad van Japan?",
)

meta = response.usage_metadata
print(f"Prompt tokens: {meta.prompt_token_count}")
print(f"Kandidaat tokens: {meta.candidates_token_count}")
print(f"Totaal: {meta.total_token_count}")

if meta.cached_content_token_count:
    print(f"Uit cache: {meta.cached_content_token_count}")
if meta.thoughts_token_count:
    print(f"Denk-tokens: {meta.thoughts_token_count}")

Bij denkende modellen verschijnt thoughts_token_count apart. Die denk-tokens worden als output gefactureerd, dus reken ze mee in je kostenraming.

Tokengewichten per modaliteit

Niet alle content kost evenveel. De richtwaarden volgens de officiele documentatie:

from google.genai import types

with open("diagram.png", "rb") as f:
    afbeelding = f.read()

count_met_afbeelding = client.models.count_tokens(
    model="gemini-2.5-flash",
    contents=[
        "Beschrijf dit diagram:",
        types.Part.from_bytes(data=afbeelding, mime_type="image/png"),
    ],
)
print(f"Tokens met afbeelding: {count_met_afbeelding.total_tokens}")

count_alleen_tekst = client.models.count_tokens(
    model="gemini-2.5-flash",
    contents="Beschrijf dit diagram:",
)
print(f"Alleen tekst: {count_alleen_tekst.total_tokens}")

verschil = count_met_afbeelding.total_tokens - count_alleen_tekst.total_tokens
print(f"Afbeelding kost: {verschil} tokens")

Context-limiet bewaken

Gemini 2.5 Flash en Gemini 3.5 Flash hebben een contextvenster van 1.048.576 tokens. Gemini 2.5 Pro biedt 1 miljoen tokens. Bouw altijd een veiligheidsmarge in, zodat het antwoord van het model er nog bij past.

MODEL_TOKEN_LIMIET = 1_048_576

def binnen_limiet(contents, marge: float = 0.9) -> bool:
    count = client.models.count_tokens(
        model="gemini-2.5-flash",
        contents=contents,
    )
    effectieve_limiet = MODEL_TOKEN_LIMIET * marge
    return count.total_tokens < effectieve_limiet

def splits_in_chunks(tekst: str, max_tokens: int = 50_000) -> list:
    woorden = tekst.split()
    chunks = []
    huidig = []

    for woord in woorden:
        huidig.append(woord)
        count = client.models.count_tokens(
            model="gemini-2.5-flash",
            contents=" ".join(huidig),
        )
        if count.total_tokens >= max_tokens:
            huidig.pop()
            chunks.append(" ".join(huidig))
            huidig = [woord]

    if huidig:
        chunks.append(" ".join(huidig))

    return chunks

Kosten berekenen per model

Tarieven per miljoen tokens (betaalde tier, standaard, stand juni 2026). Controleer de actuele prijzen altijd op de officiele prijspagina, want tarieven worden regelmatig herzien.

KOSTEN_PER_MILJOEN = {
    "gemini-2.5-flash-lite": {"input": 0.10, "output": 0.40},
    "gemini-2.5-flash": {"input": 0.30, "output": 2.50},
    "gemini-2.5-pro": {"input": 1.25, "output": 10.00},
    "gemini-3.5-flash": {"input": 1.50, "output": 9.00},
}

def bereken_kosten(model_naam: str, input_tokens: int, output_tokens: int) -> dict:
    tarieven = KOSTEN_PER_MILJOEN.get(model_naam, {"input": 0, "output": 0})
    input_kosten = (input_tokens / 1_000_000) * tarieven["input"]
    output_kosten = (output_tokens / 1_000_000) * tarieven["output"]
    return {
        "input_tokens": input_tokens,
        "output_tokens": output_tokens,
        "input_kosten_usd": round(input_kosten, 6),
        "output_kosten_usd": round(output_kosten, 6),
        "totaal_usd": round(input_kosten + output_kosten, 6),
    }

Tokenverbruik loggen voor productie

import logging
from datetime import datetime, timezone

logger = logging.getLogger("gemini.tokens")

def genereer_en_log(model_naam: str, prompt: str, call_id: str = "") -> str:
    response = client.models.generate_content(
        model=model_naam,
        contents=prompt,
    )
    meta = response.usage_metadata

    kosten = bereken_kosten(
        model_naam,
        meta.prompt_token_count,
        meta.candidates_token_count,
    )

    logger.info(
        "gemini_call",
        extra={
            "call_id": call_id,
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "prompt_tokens": meta.prompt_token_count,
            "output_tokens": meta.candidates_token_count,
            "kosten_usd": kosten["totaal_usd"],
        },
    )

    return response.text

Door per call het verbruik te loggen, kun je later precies zien welke prompts of gebruikers de meeste tokens verbruiken en waar optimalisatie het meest oplevert.