Installer le SDK Python

Le SDK Python openai est la bibliothèque officielle pour interagir avec l’API. Cette leçon vous accompagne de l’installation jusqu’à une structure de projet propre, celle que vous garderez pour toute la suite de la formation.

Prérequis et installation

Il vous faut Python 3.8 ou plus récent — les versions 3.11 et 3.12 sont recommandées —, un gestionnaire de paquets (pip ou uv) et la clé API obtenue à la leçon précédente. Commencez par confirmer votre interpréteur, car une machine de développement en héberge souvent plusieurs :

python --version
# Python 3.12.4

L’installation elle-même tient en une commande, pip install openai, ou uv pip install openai si vous utilisez uv, sensiblement plus rapide. Prenez toutefois l’habitude de travailler dans un environnement virtuel : c’est ce qui vous évitera de découvrir six mois plus tard que deux projets exigent des versions incompatibles de la même bibliothèque.

# Créer un environnement virtuel
python -m venv .venv

# Activer (Linux/macOS)
source .venv/bin/activate

# Activer (Windows)
.venv\Scripts\activate

# Installer le SDK
pip install openai

Deux compagnons reviennent dans presque tous les projets et méritent d’être installés en même temps. Pydantic sert à décrire les schémas du Structured Output, que vous verrez plus loin ; python-dotenv charge le fichier .env dans les variables d’environnement.

# Installer avec le support des dataclasses Pydantic
pip install openai pydantic

# Installer avec python-dotenv pour les variables d'environnement
pip install openai python-dotenv

Vérifiez enfin que l’import fonctionne et notez la version installée : c’est la première information à fournir si vous ouvrez un ticket.

import openai
print(f"SDK OpenAI version : {openai.__version__}")
# Résultat : SDK OpenAI version : 1.68.0 (ou version plus récente)

Un client, toutes les API

Le SDK s’organise autour d’un objet client unique qui expose l’ensemble de la plateforme sous forme de sous-modules. Vous n’avez donc rien à instancier de nouveau pour passer de la génération de texte aux embeddings ou à la modération.

from openai import OpenAI

client = OpenAI()

# Responses API (texte, function calling, structured output)
client.responses.create(...)

# Chat Completions API (legacy)
client.chat.completions.create(...)

# Embeddings
client.embeddings.create(...)

# Images
client.images.generate(...)

# Audio
client.audio.transcriptions.create(...)
client.audio.speech.create(...)

# Modération
client.moderations.create(...)

Configurer le client selon votre contexte

Les valeurs par défaut du SDK conviennent à l’expérimentation, beaucoup moins à une application web. Le timeout est fixé à dix minutes : dans une API HTTP qui doit répondre en quelques secondes, cela signifie qu’une requête bloquée immobilise un worker très longtemps. Réduisez-le, et augmentez le nombre de tentatives automatiques, qui vaut deux par défaut.

from openai import OpenAI

client = OpenAI(
    timeout=60.0,  # 60 secondes (défaut : 10 minutes)
    max_retries=3,  # 3 tentatives en cas d'erreur (défaut : 2)
)

Le paramètre base_url répond à un autre besoin : router les appels vers un proxy d’entreprise qui journalise le trafic sortant, ou vers un service exposant une API compatible.

# Utile pour les proxys d'entreprise ou les API compatibles
client = OpenAI(
    base_url="https://votre-proxy.entreprise.com/v1"
)

Enfin, si votre application repose sur asyncio — FastAPI, aiohttp et consorts —, utilisez AsyncOpenAI. Le client synchrone bloquerait la boucle d’événements pendant toute la génération, ce qui annulerait le bénéfice de l’asynchrone.

from openai import AsyncOpenAI

async_client = AsyncOpenAI()

# Utilisation avec await
import asyncio

async def main():
    response = await async_client.responses.create(
        model="gpt-5.6-terra",
        input="Bonjour !"
    )
    print(response.output_text)

asyncio.run(main())
# Résultat : Bonjour ! Comment puis-je vous aider aujourd'hui ?

Structurer votre projet

Adoptez dès maintenant une organisation qui isole la configuration du client du reste de votre code. Vous éviterez ainsi la dispersion de dizaines d’appels à OpenAI() aux quatre coins du projet, chacun avec ses propres réglages.

mon-projet/
├── .env                  # Clé API (JAMAIS dans git)
├── .gitignore            # Inclut .env
├── requirements.txt      # Dépendances
├── src/
│   ├── __init__.py
│   ├── client.py         # Configuration du client OpenAI
│   └── main.py           # Point d'entrée
└── tests/
    └── test_api.py

Le fichier src/client.py centralise la fabrique de client : le jour où vous changez de timeout ou ajoutez un proxy, un seul endroit est à modifier.

from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

def get_client() -> OpenAI:
    """Retourne un client OpenAI configuré."""
    return OpenAI(
        max_retries=3,
        timeout=30.0
    )

Et le requirements.txt fige les versions minimales attendues :

openai>=1.60.0
python-dotenv>=1.0.0
pydantic>=2.0.0

Trois pannes fréquentes

Un ModuleNotFoundError sur openai signale presque toujours un environnement virtuel inactif ou différent de celui où vous avez installé le paquet. Localisez l’interpréteur réellement utilisé avec which python sous Linux et macOS, where python sous Windows, puis réinstallez avec pip install --upgrade openai. Une AuthenticationError renvoie à la variable d’environnement : affichez os.environ.get("OPENAI_API_KEY", "NON DÉFINIE") pour lever le doute — le .env n’est pas chargé si load_dotenv() n’a pas été appelé avant l’instanciation du client. Enfin, une erreur portant sur un paramètre inconnu indique en général un SDK trop ancien pour la fonctionnalité que vous employez : pip install --upgrade openai résout le cas.

Points clés à retenir

Installez le SDK avec pip install openai dans un environnement virtuel
Le client OpenAI() est le point d’entrée vers toutes les API
Utilisez AsyncOpenAI() pour les applications asynchrones
Configurez timeout et retries selon vos besoins
Structurez votre projet avec un fichier .env et un client centralisé