OpenAI API voor beginners: je eerste Responses-call (2026)

De OpenAI API laat je vanuit eigen code modellen en hulpmiddelen aanroepen; voor nieuw werk is de Responses API het aanbevolen startpunt. Bewaar je sleutel in OPENAI_API_KEY, installeer de officiële SDK en test eerst één kleine server-side Python-call voordat je functies, bestanden of tools toevoegt.

Wat is de OpenAI API?

ChatGPT is een kant-en-klare toepassing waarin je direct met een model werkt. De OpenAI API is een programmeerinterface voor je eigen software. Je code verstuurt invoer, ontvangt een gestructureerd antwoord en bepaalt daarna wat er met dat antwoord gebeurt.

Dat verschil is belangrijk. Een ChatGPT-account of abonnement is niet hetzelfde als API-toegang. Voor de API maak je in het OpenAI-platform een project en een geheime sleutel aan. Het gebruik en de instellingen van die API-omgeving beheer je apart.

Praktische toepassingen zijn bijvoorbeeld:

een interne assistent die tekst uit een eigen systeem samenvat;
een serverfunctie die conceptteksten maakt voor menselijke controle;
classificatie van binnenkomende vragen;
een workflow die gestructureerde gegevens uit tekst haalt;
een toepassing die later zoeken, bestanden of eigen functies toevoegt.

Begin met een klein tekstverzoek. Voeg pas extra hulpmiddelen toe nadat je de basisaanroep, foutafhandeling en logging begrijpt. Wil je eerst oefenen met gewone code en prompts, lees dan code schrijven met ChatGPT en goede prompts maken.

Waarom beginnen met de Responses API?

OpenAI adviseert de Responses API voor nieuw werk. Eén response kan tekst, hulpmiddelacties en andere getypeerde uitvoer bevatten. Voor een eenvoudige tekstcall geeft de officiële SDK je de handige eigenschap response.output_text.

De oudere Chat Completions API bestaat nog voor bestaande integraties. Voor een nieuwe beginnersgids is het niet logisch om daar de basis op te bouwen, omdat je dan later andere request- en responsevormen moet leren voor hulpmiddelen en agentische workflows. De officiële migratiegids legt de verschillen uit.

Gebruik in je eerste test alleen:

één OpenAI-client;
één model;
een korte instructie;
één concrete invoer;
response.output_text als uitvoer.

Zo weet je bij een fout precies welke laag je moet controleren.

Stappenplan: je eerste Responses-call in Python

Stap 1: maak een apart API-project

Open het OpenAI-platform en maak een project voor je eerste test. Gebruik later aparte projecten of sleutels voor ontwikkeling en productie. Dan kun je gebruik, toegang en rotatie beter afbakenen.

Maak een nieuwe geheime sleutel aan en kopieer die direct naar een veilige plek. Deel de waarde niet in een chat, issue, e-mail, screenshot of repository. Een sleutel geeft toegang tot je API-project en hoort daarom alleen terecht te komen in een serveromgeving die jij beheert.

Stap 2: zet de sleutel in een omgevingsvariabele

Gebruik op macOS of Linux in de terminal:

export OPENAI_API_KEY="<jouw-geheime-sleutel>"

Gebruik in Windows PowerShell:

setx OPENAI_API_KEY "<jouw-geheime-sleutel>"

Open na setx een nieuwe PowerShell-sessie voordat je de Python-code uitvoert. De officiële SDK leest OPENAI_API_KEY automatisch. Je hoeft de sleutel dus niet als argument in je programma te zetten.

In een gedeelde of productieomgeving gebruik je bij voorkeur de secretsmanager van je hostingplatform. De productierichtlijnen van OpenAI adviseren om sleutels niet in code of openbare repositories te plaatsen.

Stap 3: maak een lokale Python-omgeving

Controleer eerst of Python beschikbaar is:

python --version

Op sommige systemen heet het commando python3. Maak daarna een virtuele omgeving:

python -m venv .venv

Activeer die omgeving op macOS of Linux:

source .venv/bin/activate

Gebruik op Windows:

.venv\Scripts\Activate.ps1

Een virtuele omgeving houdt de SDK en andere pakketten bij dit project. Voeg .venv en eventuele lokale .env-bestanden toe aan .gitignore.

Stap 4: installeer de officiële SDK

Installeer de Python-SDK:

pip install openai

Gebruik geen willekeurig pakket met een vergelijkbare naam. De OpenAI Developer quickstart verwijst naar het officiële openai-pakket en bevat de actuele basisvoorbeelden.

Stap 5: maak één kleine API-call

Maak een bestand voorbeeld.py:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    instructions="Antwoord kort en duidelijk in het Nederlands.",
    input="Noem drie controles voordat ik AI-tekst publiceer.",
)

print(response.output_text)

Voer het bestand uit:

python voorbeeld.py

De client leest je sleutel uit OPENAI_API_KEY. client.responses.create stuurt het verzoek naar de Responses API. instructions beschrijft het gewenste gedrag, input bevat de opdracht en response.output_text geeft de verzamelde tekstuitvoer terug.

Het voorbeeld volgt de actuele modelalias uit de officiële quickstart. Een alias kan later naar een nieuwere versie wijzen. Controleer voor productie altijd de actuele modeldocumentatie en test je eigen taken, limieten en outputcontract.

Stap 6: controleer het antwoord als data

Print in een eerste test gerust alleen output_text. In een echte toepassing controleer je ook of het verzoek is geslaagd en of de uitvoer past bij je verwachte vorm. AI-uitvoer kan onjuist, onvolledig of ongeschikt zijn, ook wanneer de API-call technisch slaagt.

Maak daarom een kleine acceptatietest:

gebruik drie representatieve invoeren;
leg vast wat elk antwoord minimaal moet bevatten;
controleer ongewenste inhoud;
bewaar geen gevoelige invoer in gewone logs;
laat belangrijke uitvoer door een mens beoordelen.

Voor workflows die persoonsgegevens kunnen verwerken, lees ook ChatGPT en de AVG. Dezelfde zorgvuldigheid geldt voor API-invoer, logs en downstreamsystemen.

Stap 7: voeg pas daarna productiegedrag toe

Een werkend terminalvoorbeeld is nog geen veilige productie-integratie. Voeg daarna in kleine stappen toe:

een serverendpoint dat invoer valideert;
een maximum voor invoerlengte;
time-outs en een begrensd aantal retries;
logging zonder sleutel of gevoelige inhoud;
monitoring per project of sleutel;
een duidelijk outputcontract;
menselijke controle voor belangrijke beslissingen;
tests met representatieve en ongeldige invoer.

Zet een geheime API-sleutel nooit in browser-JavaScript of een mobiele app. Laat zo'n client je eigen server aanroepen en laat alleen die server met OpenAI communiceren.

Je prompt uitbreiden zonder de code onnodig complex te maken

Houd instructie en invoer gescheiden. instructions bevat de vaste rol, beperkingen en gewenste vorm. input bevat de concrete taak en gegevens van dat verzoek.

Bijvoorbeeld:

response = client.responses.create(
    model="gpt-5.6",
    instructions=(
        "Vat de invoer samen in drie bullets. "
        "Noem ontbrekende informatie apart en verzin geen feiten."
    ),
    input="De tekst die je toepassing ontvangt.",
)

Vermijd een grote stapel tegenstrijdige regels. Benoem het gewenste resultaat, de belangrijke beperkingen en wat de toepassing moet doen wanneer informatie ontbreekt. De tekstgids van OpenAI bevat actuele uitleg over instructies, invoer en tekstuitvoer.

Wil je een programmeertaak eerst interactief uitwerken voordat je haar automatiseert, gebruik dan de veilige werkwijze uit de Codex-startgids. Zet pas een stabiele, geteste taak achter een API-endpoint.

Fouten gericht oplossen

De sleutel wordt niet gevonden

Controleer in dezelfde terminal waarin je Python uitvoert of de omgevingsvariabele bestaat. Print nooit de volledige sleutel. Een veilige controle is alleen vaststellen of de variabele aanwezig is:

import os

if not os.getenv("OPENAI_API_KEY"):
    raise RuntimeError("OPENAI_API_KEY ontbreekt")

Je krijgt een 401-fout

Een 401 wijst meestal op authenticatie. Controleer of de juiste omgeving wordt geladen, de sleutel nog actief is en je code niet per ongeluk een lege waarde gebruikt. Maak bij een vermoeden van lekkage een nieuwe sleutel, werk de serveromgeving bij en trek de oude sleutel in.

Je krijgt een 429-fout

Een 429 kan samenhangen met rate limits of beschikbare gebruiksruimte. Verlaag gelijktijdigheid en voeg een begrensde retry met exponentiële wachttijd en willekeurige spreiding toe. Onsuccesvolle verzoeken kunnen nog steeds meetellen voor een limiet, dus blijf niet onbeperkt opnieuw proberen. De rate-limitgids beschrijft deze aanpak.

De code werkt, maar het antwoord is niet bruikbaar

Maak de opdracht concreter. Benoem de gewenste vorm, noodzakelijke context, grenzen en controlepunten. Test vervolgens dezelfde set invoeren opnieuw. Verander niet tegelijk het model, de prompt, de foutafhandeling en de outputparser, want dan weet je niet welke wijziging het gedrag beïnvloedde.

Veelgemaakte fouten

De sleutel in broncode zetten. Gebruik OPENAI_API_KEY of een secretsmanager en roteer een gelekte sleutel direct.
De sleutel naar de browser sturen. Browsercode en mobiele apps zijn geen veilige plek voor een geheime serversleutel.
Een nieuw project op Chat Completions bouwen. Begin met de Responses API, tenzij je bewust een bestaande integratie onderhoudt.
Alleen op een technisch geslaagde call testen. Controleer ook de inhoud, structuur en ongewenste uitvoer.
Onbegrensd opnieuw proberen. Gebruik een maximumaantal pogingen en exponentiële wachttijd.
Gevoelige invoer volledig loggen. Log alleen wat je voor diagnose nodig hebt en scherm persoonsgegevens en geheimen af.
Meteen meerdere tools toevoegen. Bevestig eerst dat één kleine tekstcall betrouwbaar werkt.

Veelgestelde vragen

Wat is het verschil tussen ChatGPT en de OpenAI API?

ChatGPT is een kant-en-klare toepassing. Met de OpenAI API laat je eigen servercode een model aanroepen en verwerk je het antwoord zelf in je website, app of workflow.

Heb ik ChatGPT Plus nodig voor de OpenAI API?

Nee. ChatGPT en de API hebben een aparte toegang en gebruiksregistratie. Maak voor de API een project en sleutel aan in het OpenAI-platform.

Welke API gebruik ik voor een nieuw project?

Begin voor nieuwe teksttoepassingen met de Responses API. Die gebruikt één response-object, biedt output_text voor gewone tekst en sluit aan op hulpmiddelen zoals zoeken en bestandsanalyse.

Waar bewaar ik mijn OpenAI API-sleutel?

Bewaar de sleutel server-side in OPENAI_API_KEY of in een secretsmanager. Zet hem nooit in broncode, een openbare repository, browsercode, een mobiele app of een screenshot.

Welk model gebruik ik in het eerste voorbeeld?

Het officiële quickstartvoorbeeld gebruikt de actuele gpt-5.6-alias. Controleer vóór productie in de officiële modeldocumentatie welk model past bij je kwaliteit, snelheid en gebruikslimieten.

Waarom krijg ik een 401-fout?

Controleer of OPENAI_API_KEY in dezelfde terminal of serveromgeving beschikbaar is, of de sleutel nog actief is en of je toepassing niet per ongeluk een lege of oude waarde leest.

Wat doe ik bij een 429-fout?

Verlaag het aantal gelijktijdige verzoeken en probeer een beperkt aantal keren opnieuw met exponentiële wachttijd en willekeurige spreiding. Blijf niet onbeperkt hetzelfde verzoek herhalen.