De Python SDK installeren
Op deze pagina
De Python SDK installeren
De openai Python SDK is de officiële bibliotheek voor interactie met de API. Deze les leidt u door het installatieproces en zet een schone projectstructuur op die u gedurende de rest van de cursus zult gebruiken.
Vereisten en installatie
U heeft Python 3.10 of nieuwer nodig—het minimum vereist door de openai SDK (versie 3.42.1 per 2 november 2026, volgens PyPI)—een pakketbeheerder (pip of uv) en de API-sleutel die u in de vorige les heeft verkregen. Begin met het controleren van uw interpreter, aangezien ontwikkelmachines vaak meerdere versies hosten:
python --version
# Python 3.12.4
Installatie vereist slechts één commando: pip install openai, of uv pip install openai als u uv gebruikt, wat aanzienlijk sneller is. Maak er echter een gewoonte van om binnen een virtuele omgeving te werken. Dit voorkomt het veelvoorkomende scenario waarbij u zes maanden later ontdekt dat twee projecten incompatibele versies van dezelfde bibliotheek vereisen.
# Maak een virtuele omgeving aan
python -m venv .venv
# Activeren (Linux/macOS)
source .venv/bin/activate
# Activeren (Windows)
.venv\Scripts\activate
# Installeer de SDK
pip install openai
Twee metgezellen duiken in bijna elk project op en verdienen installatie naast de SDK. Pydantic helpt bij het definiëren van schema’s voor Gestructureerde Uitvoer (Structured Output), wat u later zult zien; python-dotenv laadt het .env-bestand in omgevingsvariabelen.
# Installeer met ondersteuning voor Pydantic dataclasses
pip install openai pydantic
# Installeer met python-dotenv voor omgevingsvariabelen
pip install openai python-dotenv
Controleer tot slot of de import werkt en noteer de geïnstalleerde versie. Dit is het eerste informatiepunt dat u moet verstrekken als u een supportticket opent.
import openai
print(f"OpenAI SDK version: {openai.__version__}")
# Output: OpenAI SDK version: 1.68.0 (or newer)
Eén client, alle API’s
De SDK draait om één enkel clientobject dat het volledige platform blootlegt via submodules. U hoeft niets nieuws te instantiëren om over te schakelen van tekstgeneratie naar embeddings of moderatie.
from openai import OpenAI
client = OpenAI()
# Responses API (tekst, functieaanroepen, gestructureerde uitvoer)
client.responses.create(...)
# Chat Completions API (verouderd)
client.chat.completions.create(...)
# Embeddings
client.embeddings.create(...)
# Afbeeldingen
client.images.generate(...)
# Audio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)
# Moderatie
client.moderations.create(...)
Configureer de client voor uw context
De standaardwaarden van de SDK werken voor experimenten, maar schieten tekort voor webapplicaties. De standaard time-out is tien minuten: in een HTTP-API waarvan wordt verwacht dat deze binnen seconden reageert, betekent dit dat een vastgelopen request een worker veel te lang bezet houdt. Verlaag deze waarde en verhoog het aantal automatische pogingen, dat standaard op twee staat.
from openai import OpenAI
client = OpenAI(
timeout=60.0, # 60 seconden (standaard: 10 minuten)
max_retries=3, # 3 pogingen bij fout (standaard: 2)
)
De parameter base_url speelt in op een andere behoefte: het routeren van oproepen via een bedrijfsproxy die uitgaand verkeer logt, of naar een service die een compatibele API blootlegt.
# Handig voor bedrijfsproxies of compatibele API's
client = OpenAI(
base_url="https://your-proxy.company.com/v1"
)
Tot slot, als uw applicatie vertrouwt op asyncio—FastAPI, aiohttp, en dergelijke—gebruik dan AsyncOpenAI. De synchrone client zou de event loop blokkeren tijdens de generatie, waardoor de voordelen van asynchrone code teniet worden gedaan.
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
# Gebruik met await
import asyncio
async def main():
response = await async_client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(response.output_text)
asyncio.run(main())
# Output: Hello! How can I help you today?
Structureer uw project
Kies vanaf het begin voor een organisatie die clientconfiguratie isoleert van de rest van uw code. Dit voorkomt dat tientallen OpenAI()-aanroepen door uw project worden verspreid, elk met zijn eigen instellingen.
my-project/
├── .env # API-sleutel (NOOIT committen naar git)
├── .gitignore # Bevat .env
├── requirements.txt # Afhankelijkheden
├── src/
│ ├── __init__.py
│ ├── client.py # OpenAI client configuratie
│ └── main.py # Entry point
└── tests/
└── test_api.py
Het bestand src/client.py centraliseert de client-factory: op de dag dat u de time-out wijzigt of een proxy toevoegt, hoeft u slechts één locatie aan te passen.
from openai import OpenAI
from dotenv import load_dotenv
load_dotenv()
def get_client() -> OpenAI:
"""Retourneert een geconfigureerde OpenAI client."""
return OpenAI(
max_retries=3,
timeout=30.0
)
En requirements.txt legt de minimaal verwachte versies vast:
openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0
Drie veelvoorkomende fouten
Een ModuleNotFoundError op openai wijst bijna altijd op een niet-actieve virtuele omgeving of een andere omgeving dan waar u het pakket heeft geïnstalleerd. Zoek de interpreter die daadwerkelijk wordt gebruikt met which python op Linux en macOS, of where python op Windows, en installeer vervolgens opnieuw met pip install --upgrade openai. Een AuthenticationError wijst op de omgevingsvariabele: print os.environ.get("OPENAI_API_KEY", "NOT DEFINED") om problemen uit te sluiten—het .env-bestand wordt niet geladen als load_dotenv() niet is aangeroepen voordat de client werd geïnstantieerd. Tot slot duidt een foutmelding over een onbekende parameter meestal op een SDK die te oud is voor de functie die u gebruikt: pip install --upgrade openai lost dit op.
Belangrijkste punten
- Installeer de SDK met
pip install openaibinnen een virtuele omgeving - De
OpenAI()client is het toegangspunt voor alle API’s - Gebruik
AsyncOpenAI()voor asynchrone applicaties - Configureer time-out en retry-pogingen op basis van uw behoeften
- Structureer uw project met een
.env-bestand en een gecentraliseerde client