Premier appel à l’API OpenAI en Python : clé, Responses, erreurs

Vous voulez ajouter un peu d’intelligence à une application : un assistant qui répond aux questions des clients, un script qui résume des courriels, une fonction qui reformule un texte. La porte d’entrée la plus directe est l’API d’OpenAI, qui expose les modèles GPT derrière un simple appel HTTP. Le problème, quand on débute, c’est de franchir les premières minutes : où récupérer une clé, comment l’utiliser sans la fuiter, quel appel écrire, et que faire quand le serveur renvoie une erreur. Ce tutoriel vous fait passer de zéro à un premier appel qui fonctionne, proprement, en Python.

Au fil de cette série, nous construisons un assistant de support client pour une petite entreprise : il répondra aux questions, consultera l’état d’une commande et renverra des données structurées. Ici, nous posons la toute première brique — l’appel de base au modèle — et nous la rendons robuste.

🎯 Ce que vous allez apprendre

• Créer une clé d’API et la stocker sans jamais l’écrire en dur dans le code.
• Installer le SDK officiel et envoyer votre premier appel avec l’API Responses.
• Structurer une conversation avec un message système et un message utilisateur.
• Lire la réponse et le décompte de jetons (tokens) consommés.
• Attraper les erreurs courantes (clé invalide, quota dépassé, limite de débit) et réessayer intelligemment.

🛠️ Ce que vous allez construire

Un petit script assistant.py qui prend une question en français, l’envoie à un modèle GPT avec une consigne de rôle (« tu es l’assistant de la boutique »), affiche la réponse et indique combien de jetons l’appel a coûté. À la fin, vous aurez une fonction réutilisable que les tutoriels suivants viendront enrichir.

Prérequis

• Python 3.10 ou plus récent installé (vérifiez avec python --version).
• Un compte sur la plateforme OpenAI et un moyen de paiement ajouté (l’API est payante à l’usage, facturée en dollars ; un premier appel coûte une fraction de centime).
• Des bases en Python : appeler une fonction, manipuler un dictionnaire. Test express : si vous savez ce que fait print(maliste[0]), vous êtes prêt.
• ⏱️ Temps estimé : environ 25 minutes.

Étape 1 — Créer et sécuriser votre clé d’API

Tout appel à l’API est authentifié par une clé secrète. Cette clé identifie votre compte et lui impute la facturation : elle se traite comme un mot de passe. La règle d’or est de ne jamais l’écrire dans le code source ni la pousser sur un dépôt Git, car une clé exposée publiquement est aussitôt scannée et exploitée par des robots.

Connectez-vous à la plateforme OpenAI, ouvrez la page API keys de votre tableau de bord, cliquez sur « Create new secret key », nommez-la (par exemple assistant-boutique) et copiez la valeur affichée. Vous ne la reverrez plus : si vous la perdez, vous en régénérez une autre. Stockez-la ensuite dans une variable d’environnement, qui est l’endroit standard où le SDK ira la chercher tout seul.

# Sous Linux ou macOS, dans le terminal (session courante)
export OPENAI_API_KEY="sk-votre-cle-secrete-ici"

# Sous Windows PowerShell
$env:OPENAI_API_KEY = "sk-votre-cle-secrete-ici"

Le nom OPENAI_API_KEY n’est pas arbitraire : c’est exactement celui que la bibliothèque officielle lit par défaut. En définissant cette variable, vous évitez de coller la clé dans chaque fichier. Pour qu’elle persiste entre deux sessions, ajoutez la ligne export à votre ~/.bashrc (Linux/macOS) ou utilisez la variable d’environnement système sous Windows. Vérifiez qu’elle est bien posée avec echo $OPENAI_API_KEY : vous devez voir s’afficher votre clé, et non une ligne vide.

✅ Point d’étape — Votre clé existe et la variable d’environnement la contient. Si echo ne renvoie rien, c’est que la variable n’est pas définie dans ce terminal : relancez la commande export dans la même fenêtre que celle où vous exécuterez Python.

Étape 2 — Installer le SDK et écrire le premier appel

OpenAI publie une bibliothèque Python officielle qui encapsule les appels HTTP, la gestion des clés et le typage des réponses. On l’installe avec pip, idéalement dans un environnement virtuel pour ne pas polluer votre Python système.

# Créer un environnement virtuel (recommandé)
python -m venv .venv
source .venv/bin/activate      # Windows : .venv\Scripts\activate

# Installer la bibliothèque officielle
pip install openai

L’activation de l’environnement isole les dépendances du projet ; vous saurez qu’elle a réussi car votre invite de commande est préfixée par (.venv). Une fois openai installé, écrivons le cœur du tutoriel. L’API recommandée aujourd’hui pour tout nouveau projet s’appelle Responses : un seul appel, une entrée, une sortie texte. Créez un fichier assistant.py.

from openai import OpenAI

# Le client lit automatiquement la variable OPENAI_API_KEY
client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input="Explique en une phrase ce qu'est une API."
)

print(response.output_text)

Trois lignes font tout le travail. OpenAI() instancie un client qui trouve votre clé dans l’environnement. responses.create envoie la requête : on lui donne le nom du modèle et le texte d’entrée. La propriété output_text rassemble pour vous le texte généré, sans avoir à parcourir une structure complexe. Lancez python assistant.py : après une à deux secondes, une phrase explicative s’affiche dans le terminal. Vous venez d’appeler un modèle GPT.

Pourquoi gpt-5.4 et pas le tout dernier modèle ? Parce que c’est le modèle « de travail » : un excellent rapport qualité-prix pour la grande majorité des usages. Le modèle phare gpt-5.5 est plus capable mais plus cher, tandis que gpt-5.4-mini et gpt-5.4-nano sont nettement moins coûteux pour des tâches simples. On revient sur ces arbitrages dans le tutoriel consacré aux coûts.

✅ Point d’étape — Le script affiche une phrase cohérente. Si rien ne s’affiche ou si une exception apparaît, ne corrigez rien au hasard : l’étape 4 décrit les erreurs typiques et leur cause exacte.

Étape 3 — Donner un rôle à l’assistant avec des messages

Une chaîne de caractères suffit pour un test, mais une vraie application a besoin de cadrer le comportement du modèle : son ton, sa langue, ce qu’il a le droit de dire. Pour cela, on remplace le texte simple par une liste de messages, chacun avec un rôle. Le rôle system (ou « développeur ») pose les règles ; le rôle user porte la question réelle de l’utilisateur.

from openai import OpenAI

client = OpenAI()

def repondre(question):
    response = client.responses.create(
        model="gpt-5.4",
        input=[
            {"role": "system", "content":
                "Tu es l'assistant de la boutique Baobab Informatique. "
                "Tu reponds en francais, poliment et en deux phrases maximum. "
                "Si tu ne sais pas, tu invites a contacter le service client."},
            {"role": "user", "content": question},
        ],
    )
    return response.output_text

print(repondre("Quels sont vos horaires d'ouverture ?"))

La consigne système agit comme une fiche de poste remise au modèle avant chaque échange. Ici, elle impose le français, un ton poli, une longueur courte et un comportement de repli quand l’information manque. Le message utilisateur, lui, varie à chaque appel. En testant plusieurs questions, vous constaterez que les réponses respectent le cadre : c’est l’effet direct du message system. Cette fonction repondre() est la brique que les prochains tutoriels vont enrichir, notamment pour lui permettre de consulter de vraies données.

Étape 4 — Gérer les erreurs et réessayer proprement

En production, un appel réseau échoue tôt ou tard : clé mal configurée, quota épuisé, ou trop de requêtes envoyées en peu de temps. Un script qui plante à la moindre erreur n’est pas utilisable. Le SDK lève des exceptions typées que l’on peut intercepter pour réagir au cas par cas plutôt que de tout faire échouer.

from openai import OpenAI, AuthenticationError, RateLimitError, APIError

client = OpenAI()

def repondre_sur(question):
    try:
        response = client.responses.create(
            model="gpt-5.4",
            input=[{"role": "user", "content": question}],
        )
        return response.output_text
    except AuthenticationError:
        return "Cle d'API invalide : verifiez la variable OPENAI_API_KEY."
    except RateLimitError:
        return "Trop de requetes ou quota epuise : patientez puis reessayez."
    except APIError as e:
        return "Erreur cote serveur : " + str(e)

Chaque branche cible une cause précise. AuthenticationError signale une clé absente ou erronée — l’erreur de débutant la plus fréquente. RateLimitError apparaît soit quand vous dépassez la cadence autorisée, soit quand votre crédit est épuisé. APIError couvre les incidents côté serveur. Pour les limites de débit, la bonne pratique n’est pas d’abandonner mais de réessayer après une courte attente, en doublant le délai à chaque échec — une technique appelée « repli exponentiel ».

import time
from openai import RateLimitError

def repondre_avec_reprise(question, essais=4):
    for n in range(essais):
        try:
            r = client.responses.create(
                model="gpt-5.4",
                input=[{"role": "user", "content": question}],
            )
            return r.output_text
        except RateLimitError:
            attente = 2 ** n          # 1s, 2s, 4s, 8s
            print("Limite atteinte, nouvelle tentative dans", attente, "s")
            time.sleep(attente)
    return "Service momentanement indisponible, reessayez plus tard."

La boucle tente l’appel jusqu’à quatre fois, en attendant 1, puis 2, puis 4 secondes entre les essais. Ce délai croissant laisse au serveur le temps de « respirer » et évite d’aggraver la saturation. En conditions réelles, vous verrez le message d’attente s’afficher rarement ; quand il apparaît, le script se rétablit seul au lieu de planter.

✅ Point d’étape — Coupez volontairement votre clé (videz la variable) et relancez : vous devez obtenir le message « Cle d’API invalide » et non une trace d’erreur Python. C’est le signe que la gestion d’erreurs fonctionne.

Étape 5 — Vérifier le coût de chaque appel

Chaque réponse contient un objet usage qui détaille les jetons consommés. Un jeton correspond à peu près à trois quarts d’un mot en anglais, un peu moins en français. Comme la facturation se fait au jeton, savoir lire ce décompte dès le départ vous évite les mauvaises surprises à la fin du mois.

r = client.responses.create(
    model="gpt-5.4",
    input="Resume en trois points les avantages d'une API.",
)
print(r.output_text)
print("Jetons en entree :", r.usage.input_tokens)
print("Jetons en sortie :", r.usage.output_tokens)
print("Total :", r.usage.total_tokens)

Les jetons d’entrée correspondent à votre requête (consigne système comprise), ceux de sortie à la réponse générée. La sortie est facturée plus cher que l’entrée, ce qui incite à demander des réponses concises quand le contexte le permet. Affichez ces chiffres pendant vos tests : vous prendrez vite la mesure de ce que coûte réellement chaque type de requête. Le tutoriel sur le streaming et les coûts approfondit le calcul et le budget.

🐞 Pièges fréquents

Maîtriser le coût et la connexion

L’API se facture en dollars et au jeton, ce qui rend le coût proportionnel à l’usage : aucun abonnement fixe, mais une vigilance nécessaire quand le volume monte. Trois réflexes limitent la facture sans dégrader la qualité. D’abord, choisir le bon modèle : gpt-5.4-mini ou gpt-5.4-nano suffisent pour classer un message ou extraire un champ, et coûtent une fraction du modèle phare. Ensuite, plafonner la longueur des réponses via une consigne (« deux phrases maximum ») pour réduire les jetons de sortie. Enfin, définir une limite de dépense mensuelle (« usage limit ») dans le tableau de bord, qui coupe les appels au-delà d’un seuil et protège d’une boucle accidentelle.

Côté infrastructure, une connexion instable rend les délais d’attente et les reprises automatiques d’autant plus utiles : la boucle de repli de l’étape 4 absorbe les micro-coupures sans intervention. Pour développer hors ligne ou tester sans consommer de crédit, vous pouvez aussi remplacer temporairement l’appel réel par une fonction qui renvoie une réponse fixe, puis rebrancher l’API une fois la logique au point.

✅ Récapitulatif

Vous êtes parti d’un compte vide et vous disposez maintenant d’une fonction repondre() qui interroge un modèle GPT, respecte un rôle imposé, encaisse les erreurs sans planter et affiche son coût en jetons. Vous savez où vit la clé, pourquoi elle ne doit jamais entrer dans le code, et comment choisir un modèle selon le besoin. C’est exactement le socle sur lequel les prochaines briques — appel de fonctions, sorties structurées, recherche sémantique — vont s’appuyer.

🧾 Aide-mémoire

💪 À vous de jouer

Modifiez la fonction repondre() pour qu’elle accepte un deuxième paramètre ton (« formel » ou « amical ») et l’injecte dans la consigne système. Testez la même question avec les deux tons.

def repondre(question, ton="formel"):
    consigne = ("Tu es l'assistant de Baobab Informatique. Reponds en francais, "
                "en deux phrases. Adopte un ton " + ton + ".")
    r = client.responses.create(
        model="gpt-5.4",
        input=[
            {"role": "system", "content": consigne},
            {"role": "user", "content": question},
        ],
    )
    return r.output_text

Tutoriels associés

• Function calling avec GPT : laisser le modèle appeler vos fonctions
• Sorties structurées JSON fiables avec l’API OpenAI
• 🔝 Retour au guide principal de la série
• Documentation officielle : OpenAI — Developer quickstart

FAQ

Faut-il payer pour tester l’API ?
Oui, l’API est facturée à l’usage et nécessite un moyen de paiement, mais un appel de test coûte une fraction de centime. Fixez une limite de dépense pour développer sans risque.

Quelle différence entre l’API Responses et l’ancienne API Chat Completions ?
Responses est l’interface recommandée pour les nouveaux projets ; elle simplifie l’appel et gère mieux les usages avancés. Chat Completions reste disponible et fonctionnel, mais Responses est le choix par défaut aujourd’hui.

Ma clé a-t-elle expiré si je vois une erreur d’authentification ?
Le plus souvent non : la variable d’environnement n’est simplement pas définie dans le terminal courant. Vérifiez avec echo avant de régénérer une clé.

Puis-je utiliser un autre langage que Python ?
Oui, OpenAI publie aussi un SDK officiel pour JavaScript/TypeScript et l’API est accessible en HTTP depuis n’importe quel langage. Les concepts (clé, modèle, entrée, sortie) sont identiques.