Wat is een API? Uitleg aan de hand van AI en je eerste curl

👁 117 keer gelezen

Een API is een afspraak tussen twee programma’s: het ene programma stuurt een verzoek in een vastgesteld formaat, en het andere stuurt een antwoord terug in eveneens een vastgesteld formaat. Wanneer jouw script een AI-model vraagt om een e-mail samen te vatten, klikt het niet in een chatvenster, maar verstuurt het via internet een pakketje tekst in JSON-formaat en krijgt het JSON terug. Dit artikel is de eerste stap in het traject AI API vanaf nul, waarin ik alles laat zien aan de hand van echte verzoeken die zijn uitgevoerd op mijn computer.

Wat is een API in begrijpelijke taal: het loket met het formulier

De eenvoudigste manier om je een API voor te stellen, is als een loket bij een overheidsinstantie waar ze uitsluitend ingevulde formulieren aannemen. Je ziet de achterliggende kantoorruimte niet en weet niet wie het werk feitelijk uitvoert. Je weet echter drie dingen:

• naar welk loket je moet gaan - dit is het adres oftewel het endpoint, bijvoorbeeld https://openrouter.ai/api/v1/chat/completions;
• hoe je het formulier invult - dit is het formaat van het verzoek zoals beschreven in de documentatie: welke velden verplicht zijn en welke optioneel;
• hoe je jezelf legitimeert - dit is de API-sleutel (API key), die je meestuurt bij elk verzoek.

De baliemedewerker stuurt je ofwel de voltooide aanvraag terug, ofwel een briefje met een foutcode: “handtekening ontbreekt”, “te veel aanvragen vandaag” of “het systeem werkt niet”. Bij een API zijn dit de HTTP-statuscodes, die we hieronder bespreken.

Het verschil tussen een gewone chat en een API is dat de chat (zoals ChatGPT, Claude of Gemini) een kant-en-klare applicatie voor mensen is, terwijl een API programmatische toegang biedt tot hetzelfde model. Via een API onthoudt het model je eerdere gesprekken niet standaard en zijn er geen knoppen of geschiedenisoverzichten. Daar staat tegenover dat je het duizend keer kunt aanroepen vanuit een spreadsheet, een bot of een geautomatiseerd nachtelijk script. Je betaalt dan geen vast abonnement, maar voor verbruikte tokens (tekstdeeltjes) - dit leg ik uit in het artikel AI-tokens: wat zijn het en wat kosten ze?.

Verzoek en antwoord (request en response)

Elke communicatie met een API bestaat uit twee delen. Het verzoek (request) bevat:

1. De methode - wat je wilt doen. Naar AI-modellen stuur je vrijwel altijd een POST-verzoek, omdat je inhoud meestuurt.
2. Het adres - het specifieke endpoint van de functie, zoals tekst genereren of een lijst met modellen opvragen.
3. Headers - metadata: de API-sleutel (Authorization: Bearer ...) en het type inhoud (Content-Type: application/json).
4. De body - de eigenlijke gegevens: welk model je aanroept, welke berichten je stuurt en welke parameters gelden.

Het antwoord (response) bevat een statuscode (zoals 200, wat betekent dat alles goed is gegaan) en de inhoud, waarin de gegenereerde tekst en het aantal verbruikte tokens staan. Zo ziet een echt antwoord eruit dat ik op 4 oktober 2026 ontving van het model GPT-6 Luna via OpenRouter (ingekort tot de belangrijkste velden):

{
  "id": "gen-1791114764-uKPpeyAgJg4GJmOQhMp4",
  "object": "chat.completion",
  "model": "openai/gpt-6-luna",
  "provider": "OpenAI",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Vertaling van het Poolse origineel: Krakau betovert met zijn historische Grote Markt, sfeervolle straatjes en rijke geschiedenis."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 16,
    "completion_tokens": 36,
    "total_tokens": 52,
    "cost": 0.0000196
  }
}

Dit lees je als volgt: het model antwoordde met een Poolstalige zin over Krakau (vertaald: “Krakau betovert met de historische Grote Markt, sfeervolle straatjes en een rijke geschiedenis”), sloot normaal af (finish_reason: stop), verbruikte 16 tokens voor de invoer en 36 voor de uitvoer, en het hele verzoek kostte 0,0000196 USD (ongeveer ca. 0,0000175 EUR volgens de ECB-referentiekoers van 12 oktober 2026, bron: https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml), oftewel minder dan twee duizendste dollarcent.

JSON in 2 minuten

JSON (JavaScript Object Notation) is een tekstgebaseerd gegevensformaat dat leesbaar is voor zowel mensen als programmeertalen. Je hoeft slechts vijf onderdelen te kennen:

• { } - een object: een verzameling van “sleutel: waarde”-paren, zoals {"model": "openai/gpt-6-luna"};
• [ ] - een array oftewel lijst, bijvoorbeeld een reeks berichten in een dialoog;
• "tekst" - tekst staat altijd tussen dubbele aanhalingstekens (enkele aanhalingstekens zijn ongeldig);
• getallen zonder aanhalingstekens: 0.7, 1024 - met een punt als scheidingsteken, geen komma;
• true, false, null - waar, onwaar, of geen waarde.

Een verzoek naar een AI-model is een object met het veld model en de lijst messages. Elk bericht heeft een rol (system voor instructies aan het model, user voor jouw invoer, assistant voor eerdere reacties van het model) en de inhoud. Hieronder staat de vertaling van de oorspronkelijke Poolse testprompt (“Napisz jedno zdanie o Krakowie.”):

{
  "model": "openai/gpt-6-luna",
  "messages": [
    {"role": "user", "content": "Schrijf één zin over Krakau."}
  ]
}

De meest gemaakte fout bij beginners is een komma achter het laatste element van een lijst of object. JSON staat dat niet toe en de server reageert dan met foutcode 400. Wil je dat een model zelf gestructureerde data produceert in plaats van alleen platte tekst, bekijk dan de handleiding Structured output: hoe je AI dwingt om te antwoorden in JSON.

HTTP-methodes: GET, POST en de rest

In de praktijk gebruik je tijdens de eerste weken voornamelijk twee methodes: GET om te controleren wat er beschikbaar is, en POST om tekst te laten genereren.

Statuscodes en fouten: 401, 429, 500 en meer

Een statuscode is een driecijferig getal aan het begin van de response. Het eerste cijfer geeft aan waar de oorzaak ligt: 2xx betekent succes, 4xx duidt op een fout aan jouw kant en 5xx wijst op een probleem bij de server.

Ik heb getest wat er feitelijk gebeurt als je de sleutel vergeet. Dit is het resultaat van een verzoek aan OpenRouter zonder Authorization-header:

$ curl -s https://openrouter.ai/api/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"openai/gpt-6-luna","messages":[{"role":"user","content":"hoi"}]}'
{"error":{"message":"No cookie auth credentials found","code":401}}

En zo zien twee fouten eruit die zijn opgevangen door mijn Python-script: een ongeldige sleutel en een niet-bestaand model. Opvallend detail: OpenRouter geeft bij een onbekend model status 400 terug en geen 404, dus ga er in je code niet blind van uit dat één situatie altijd dezelfde statuscode oplevert.

401: controleer API-sleutel (Error code: 401 - {'error': {'message': 'User not found.', 'code': 401}})

400: pas verzoek aan (Error code: 400 - {'error': {'message': 'openai/gpt-7-nie-istnieje is not a valid model ID', 'code': 400}})

Hoe je deze statuscodes netjes opvangt en verzoeken na een 429 automatisch opnieuw probeert, behandel ik in Je eerste AI API-verzoek in Python.

Eerste stappen met curl: een verzoek via de terminal

curl is een commandoregelprogramma om HTTP-verzoeken te versturen. Het is standaard aanwezig in Windows 10 en 11 (als curl.exe), macOS en Linux, dus je hoeft niets te installeren. We beginnen met een GET-verzoek waarvoor geen sleutel nodig is: de modellijst van OpenRouter opvragen:

{"data":[{"id":"inclusionai/ling-3.1-flash","canonical_slug":"inclusionai/ling-3.1-flash-20261002","hugging_face_id":null,"name":"inclusionAI: Ling 3.1 Flash","created":1790950024,"description":"Ling 3.1 Flash is a hybrid reasoning mixture-of-experts model from inclusionAI, with 25B active parameters out of 560B total.","context

Als resultaat kreeg ik een object met de lijst data, waarin op 4 oktober 466 modellen stonden. Nu volgt een POST-verzoek: een echte vraag aan het model. Hiervoor heb je een sleutel nodig (instructies voor vier aanbieders vind je in het artikel API-sleutels: hoe je ze aanmaakt en veilig bewaart). In Git Bash, op Linux en macOS (aangepast met vertaalde testprompt):

#!/usr/bin/env bash
# Eerste verzoek via curl (Git Bash, Linux, macOS). Vooraf: export OPENROUTER_API_KEY=sk-or-v1-...
curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna",
    "messages": [{"role": "user", "content": "Schrijf één zin over Krakau."}]
  }'

In PowerShell zorgen aanhalingstekens binnen JSON soms voor problemen. Daarom plaats ik de inhoud van het verzoek in een bestand genaamd verzoek.json, waarna curl dit bestand verstuurt. Let op het gebruik van curl.exe in plaats van curl, aangezien curl in oudere PowerShell-versies een alias was voor een ander commando:

# Windows PowerShell: inhoud van het verzoek in het bestand verzoek.json (voorkomt problemen met aanhalingstekens)
# Vooraf in hetzelfde venster: $env:OPENROUTER_API_KEY = "sk-or-v1-..."
curl.exe -s https://openrouter.ai/api/v1/chat/completions `
  -H "Authorization: Bearer $env:OPENROUTER_API_KEY" `
  -H "Content-Type: application/json" `
  -d "@verzoek.json"

Beide varianten heb ik getest op Windows 11 (Git Bash met curl 8.22 en Windows PowerShell). In de oorspronkelijke test met de Poolse prompt (“Napisz jedno zdanie o Krakowie.”) gaf het model telkens één zin over Krakau terug, waarbij elk verzoek ongeveer 0,00002 USD kostte (ongeveer ca. 0,0000179 EUR, ECB-koers 12 oktober 2026). Beide scripts zijn opgenomen in het startpakket api-starterarchief.

Volgende stappen

1. Account en sleutel instellen: API-sleutel bij OpenAI, Anthropic, Google AI Studio en OpenRouter.
2. Schrijf je eerste script: Je eerste AI API-verzoek in Python.
3. Bereken je verbruik: AI-tokens en kostencalculator.
4. Zodra je de basis van API’s beheerst, ga je door naar automatisering: AI-agents vanaf de basis.

Veelgestelde vragen

Wat is een API in eenvoudige bewoordingen?

Het is een gestandaardiseerde manier waarop software een opdracht geeft aan andere software: het stuurt een verzoek in een vastgesteld formaat en ontvangt een antwoord in een afgesproken vorm. Het programma hoeft niet te weten hoe de interne verwerking werkt.

Waar staat de afkorting API voor?

Application Programming Interface, oftewel een koppelvlak voor applicatieprogrammering. Het vormt het raakvlak tussen twee programma’s, vergelijkbaar met hoe een beeldscherm en knoppen de interface vormen voor een mens.

Moet je kunnen programmeren om een API te gebruiken?

Voor een eerste testopdracht niet: curl en een kant-en-klaar commando volstaan. Wil je er daadwerkelijk taken mee automatiseren, dan is basiskennis van Python handig, of kun je gebruikmaken van automatiseringstools zoals n8n of Zapier, die de API-verzoeken voor je uitvoeren.

Wat is het verschil tussen een API en ChatGPT?

ChatGPT is een complete applicatie met een maandelijks abonnement, gespreksgeschiedenis en een gebruikersinterface. De OpenAI API biedt directe toegang tot de modellen voor software, wordt afgerekend per token en kent geen ingebouwde chatgeschiedenis of vensters. Een ChatGPT-abonnement omvat geen API-tegoed; dit zijn gescheiden accounts en betalingssystemen.

Wat is een REST API?

Dit is het gangbaarste architectuurmodel voor web-API’s: bronnen hebben hun eigen URL-adressen, bewerkingen worden gekozen met HTTP-methodes (GET, POST, DELETE) en gegevens worden vrijwel altijd uitgewisseld via JSON. API’s van AI-modellen zijn volgens dit principe opgebouwd.

Bronnen en controledatum

De verzoeken zijn uitgevoerd op 4 oktober 2026 op Windows 11 via OpenRouter. De totale kosten van de voorbeelden in dit artikel bleven onder 0,0001 USD (ca. 0,000089 EUR op basis van de ECB-referentiekoers van 12 oktober 2026, bron: https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml).

• OpenRouter - Quickstart
• OpenRouter - foutcodes
• MDN - HTTP-statuscodes
• json.org - beschrijving van het JSON-formaat
• Anthropic - API-fouten (waaronder 529)

// lees verderEerste AI-API-aanroep in Python: stappenplanHandleidingenWat zijn embeddings en vector databases? Uitleg en testHandleidingenOpenAI API key: kosten, instellen en je eerste requestHandleidingen

Kinetyra