Claude API voor beginners: je eerste request (2026)

De Claude API laat je Claude vanuit je eigen applicatie aanroepen via de Messages API. Je kunt veilig beginnen met één klein Python-script, zolang je de API-key buiten de code bewaart en zelf de relevante gesprekscontext beheert.

In het kort

Maak een API-key in de Claude Console en sla die op als secret.
Installeer de officiële Python SDK in een aparte virtuele omgeving.
Verstuur één user-bericht via client.messages.create.
Lees alleen tekstblokken uit die daadwerkelijk als tekst zijn teruggegeven.
Bewaar bij vervolgvragen zelf de relevante gespreksgeschiedenis.
Log fouttype en request-ID, maar nooit de API-key of gevoelige promptinhoud.
Controleer model, limieten en productdocumentatie opnieuw voor productie.

Wil je eerst begrijpen wat Claude in de gewone chat kan? Begin dan met Claude voor beginners. Vergelijk je ook de ontwikkelaarsroute van OpenAI, lees dan ChatGPT API voor beginners.

Voor je begint

De officiële Claude-quickstart noemt een Console-account en een API-key als voorwaarden. Voor het Python-voorbeeld heb je ook een lokale Python-omgeving nodig; de actuele documentatie van de Python SDK vermeldt de ondersteunde Python-versie en installatie-instructies.

Maak voor een eerste proef een aparte ontwikkelwerkruimte en gebruik synthetische gegevens. Zet klantdata, wachtwoorden, persoonsgegevens en bedrijfsgeheimen pas in een integratie nadat je toegang, logging, retentie, leveranciersvoorwaarden en je eigen beveiligingsmaatregelen hebt beoordeeld. Gebruik de praktische privacycheck voor AI als startpunt voor die beoordeling.

Stappenplan: je eerste Claude API-request

Stap 1: maak een afgebakende API-key

Open de Claude Console via de route uit de officiële quickstart en maak een API-key voor je ontwikkelomgeving. Geef de key een herkenbare naam, koppel hem aan de juiste werkruimte en noteer welke applicatie de key mag gebruiken.

Kopieer de key rechtstreeks naar je secret store of lokale omgevingsvariabele. Zet hem niet tijdelijk in een notitiebestand in je repository.

Stap 2: maak een virtuele Python-omgeving

Maak een lege projectmap en start daarin een virtuele omgeving:

python -m venv .venv
source .venv/bin/activate
python -m pip install anthropic

Op Windows activeer je de virtuele omgeving met de opdracht die bij je shell hoort. De installatie-opdracht pip install anthropic volgt de actuele Python SDK-handleiding.

Stap 3: zet de key als omgevingsvariabele

Voer op macOS of Linux in dezelfde terminalsessie uit:

export ANTHROPIC_API_KEY="jouw-api-key"

Gebruik in een gedeelde of gehoste omgeving de secretfunctie van je platform. Voeg een lokaal .env-bestand alleen toe als je toepassing dat bewust inleest en zorg dat het bestand in .gitignore staat.

Stap 4: maak het kleinste werkende script

Maak app.py met deze inhoud:

from anthropic import Anthropic

client = Anthropic()

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    system="Antwoord in het Nederlands en benoem onzekerheid.",
    messages=[
        {
            "role": "user",
            "content": "Geef drie controlepunten voor een zakelijke e-mail.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Het model in dit voorbeeld komt uit de officiële quickstart zoals gecontroleerd op 29 juli 2026. Een model-ID is geen tijdloze standaard: controleer voor productie de actuele modeldocumentatie en test of jouw werkruimte toegang heeft.

max_tokens is volgens de Messages API-referentie een bovengrens voor de gegenereerde uitvoer. Claude kan eerder stoppen. Gebruik daarom niet alleen deze waarde om af te dwingen dat een antwoord inhoudelijk compleet of kort genoeg is.

Stap 5: voer uit en controleer het antwoord

Start het script:

python app.py

Controleer niet alleen of tekst verschijnt. Leg ook vast:

welk model en welke instellingen je gebruikte;
of de uitvoer aan je inhoudelijke criteria voldoet;
welke stop_reason is teruggegeven;
welke request-ID bij de respons hoort;
of je logs geen key of gevoelige invoer bevatten.

De officiële SDK maakt de request-ID op een top-level respons beschikbaar via message._request_id. Volgens de API-foutendocumentatie helpt die ID bij foutonderzoek en een supportvraag.

Stap 6: beheer vervolgvragen zelf

De handleiding voor de Messages API beschrijft de gewone API als stateless. Voor een vervolgvraag stuur je de relevante eerdere beurten daarom opnieuw mee:

messages = [
    {"role": "user", "content": "Noem drie controlepunten."},
    {"role": "assistant", "content": "1. Doel 2. Feiten 3. Toon"},
    {"role": "user", "content": "Werk punt 2 uit met een voorbeeld."},
]

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=512,
    messages=messages,
)

Sla niet automatisch een onbeperkte geschiedenis op. Kies relevante beurten, minimaliseer persoonsgegevens en bepaal bewust hoe lang je applicatie gesprekken bewaart.

Stap 7: voeg foutafhandeling en begrensde retries toe

De officiële Python SDK heeft getypeerde fouten. Een compacte basis ziet er zo uit:

import anthropic

try:
    message = client.messages.create(
        model="claude-opus-5",
        max_tokens=512,
        messages=[{"role": "user", "content": "Vat deze tekst samen."}],
    )
except anthropic.RateLimitError:
    print("Tijdelijk begrensd. Probeer later opnieuw.")
except anthropic.APIConnectionError:
    print("De API is niet bereikbaar.")
except anthropic.APIStatusError as error:
    print(f"API-fout: {error.status_code}")

Gebruik in productie vertraging met een maximum, een beperkt aantal pogingen en een veilige foutmelding voor de gebruiker. De actuele rate-limitdocumentatie zegt dat limieten per organisatie, werkruimte en modelgroep kunnen verschillen en dat een 429-respons retry-informatie kan bevatten. Hardcode daarom geen limietgetallen uit een blog of oud voorbeeld.

Van proef naar productie

Een geslaagd testscript is nog geen betrouwbare integratie. Voeg minimaal deze controles toe:

Geheimbeheer: bewaar keys in een secret store, roteer ze en beperk toegang per omgeving.
Invoervalidatie: begrens lengte en bestandstype voordat je data verstuurt.
Uitvoervalidatie: controleer schema, verplichte velden en toegestane acties.
Timeouts en retries: voorkom eindeloze wachttijd en herhaal geen niet-idempotente actie blind.
Observability: log model, timing, fouttype en request-ID zonder gevoelige inhoud.
Evaluaties: test vaste normale voorbeelden, randgevallen en kwaadaardige invoer bij iedere relevante wijziging.
Menselijke controle: laat risicovolle of onomkeerbare acties expliciet goedkeuren.

Voor een agent die bestanden en commando's mag uitvoeren gelden extra risico's. Gebruik daarvoor de aparte gids Claude Code veilig instellen.

Veelgemaakte fouten

De key in de broncode zetten: een repository, foutmelding of screenshot kan de key lekken. Gebruik een omgevingsvariabele of secret store.
Een model-ID als blijvende constante behandelen: modellen en toegangsrechten veranderen. Controleer de officiële documentatie en voer een vaste evaluatieset uit.
Aannemen dat de API het gesprek bewaart: de gewone Messages API verwacht dat jouw applicatie de relevante geschiedenis opnieuw meestuurt.
Alle contentblokken als tekst behandelen: controleer het bloktype voordat je .text uitleest.
Alle fouten op dezelfde manier herhalen: authenticatie-, permissie- en invoerfouten vragen een andere oplossing dan een tijdelijke verbinding- of rate-limitfout.
Alleen op een mooi antwoord testen: controleer ook brondata, weigeringen, onvolledige invoer, time-outs en uitvoer die niet aan je schema voldoet.

Veelgestelde vragen

Wat heb je nodig om de Claude API te gebruiken?

Je hebt toegang tot de Claude Console, een API-key en een lokale of gehoste omgeving nodig die HTTPS-verzoeken kan versturen. Voor het Python-voorbeeld installeer je daarnaast de officiële Anthropic SDK.

Is een Claude-chatabonnement hetzelfde als API-toegang?

Behandel Claude in de chat en de Claude API als afzonderlijke producten. Controleer in de Claude Console of je organisatie, werkruimte, API-key, limieten en factureringsinstellingen geschikt zijn voor jouw integratie.

Welk Claude-model moet je in de code invullen?

Gebruik een model-ID die op het moment van bouwen in de officiële modeldocumentatie staat en waarvoor jouw werkruimte toegang heeft. Het voorbeeld gebruikt de model-ID uit de officiële quickstart van 29 juli 2026, maar controleer die keuze opnieuw voordat je de code in productie zet.

Bewaart de Messages API automatisch je gesprek?

Nee. De gewone Messages API is stateless, dus je applicatie stuurt bij een vervolgvraag de relevante eerdere user- en assistant-berichten opnieuw mee.

Waar bewaar je de Anthropic API-key?

Bewaar de key in een geheime omgevingsvariabele of een beheerde secret store en nooit in broncode, screenshots, logregels of een publieke repository. Trek een gelekte key direct in en maak een nieuwe aan.

Wat betekent max_tokens?

max_tokens is de bovengrens voor het aantal tokens dat Claude in dat antwoord mag genereren. Het model kan eerder stoppen, dus de waarde is geen garantie voor een vaste antwoordlengte.

Hoe handel je een rate limit af?

Vang de getypeerde rate-limitfout van de SDK af, respecteer de retry-after-informatie en probeer later opnieuw met begrensde vertraging. Bekijk je actuele limieten in de Claude Console in plaats van vaste limietgetallen in je applicatie te zetten.