ChatGPT · L'API : vos premiers vrais appels
Le moyen le plus rapide de dépasser la fenêtre ChatGPT est de faire répondre le même modèle depuis votre propre code, et avec OpenAI, cela tient en une dizaine de lignes. Cette leçon couvre ces dix lignes : ce qui est propre à OpenAI, pourquoi la Responses APIAPIApplication Programming Interface : une interface standardisée qui permet aux applications de communiquer et d'échanger des données sans connaître leur fonctionnement interne respectif.Voir la définition complète → est désormais l'interface par défaut, et comment streamer les tokenstokensUn token est l'unité de base de texte que traitent les modèles de langage : le plus souvent un fragment de mot, un mot entier ou un signe de ponctuation, plutôt qu'un simple caractère.Voir la définition complète → au fur et à mesure qu'ils arrivent.
Configurez une fois, puis oubliez
Récupérez une clé sur la page des clés API. Traitez-la comme un mot de passe : elle est liée à la facturation, et quiconque la détient peut dépenser vos crédits. Ne la collez jamais dans du code et ne la committez jamais dans git.
Définissez-la comme variable d'environnement pour que le SDK la trouve automatiquement :
export OPENAI_API_KEY="sk-proj-..."
pip install openaiLe SDK Python officiel lit OPENAI_API_KEY tout seul, vous n'écrivez donc jamais la clé dans votre script. Une frontière compte ici : votre compte API et votre abonnement ChatGPT sont distincts. ChatGPT Plus ou Pro ne vous donne pas de crcrLe pourcentage de visiteurs ou de prospects qui réalisent une action attendue (achat, inscription, formulaire de contact), calculé en divisant les conversions par le nombre total d'opportunités.Voir la définition complète →édits API, et l'usage de l'API est facturé au token sur un solde différent. Ils partagent les modèles, pas le portefeuille.
Votre premier vrai appel
Voici un script complet et exécutable qui utilise la Responses API, l'interface principale actuelle d'OpenAI :
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5-mini",
instructions="You are a terse assistant. Answer in one sentence.",
input="Explain what an idempotent API request is.",
)
print(response.output_text)Exécutez-le et vous obtenez une seule phrase propre en retour. Passons aux éléments propres à OpenAI.
client = OpenAI()
Cette ligne construit le client et récupère silencieusement votre clé d'environnement. Tout ce que vous faites passe par cet objet : génération de texte, embeddings, fichiers, audio. Vous le configurez une seule fois.
model="gpt-5-mini"
La chaîne du modèle est un vrai choix facturable, pas une étiquette. La famille actuelle est GPT-5, lancée en août 2025 et mise à jour depuis par des versions intermédiaires (GPT-5.1 en novembre 2025, GPT-5.2 en décembre 2025). En pratique, vous choisissez un niveau : le dernier flagship complet (par exemple gpt-5.2) pour le travail le plus difficile, gpt-5-mini comme cheval de trait au quotidien, et gpt-5-nano pour les appels bon marché à fort volume. Un classifieur ou un formateur demande nano. Un bot de support se contente généralement de mini. Une tâche de planification en plusieurs étapes peut justifier le flagship.
Vous verrez encore d'anciens noms dans les tutoriels : la gamme GPT-4.1 et les modèles de raisonnement de la série o comme o3 et o4-mini. Ils fonctionnaient comme des familles séparées. GPT-5 intègre le raisonnement dans une seule gamme, vous ne changez donc plus de famille de modèles pour obtenir un modèle qui réfléchit avant de répondre. Vérifiez la liste et les tarifs actuels sur la page des modèles, car la gamme évolue sans cesse et de nouvelles versions intermédiaires arrivent tous les quelques mois.
Effort de raisonnement
Les modèles GPT-5 raisonnent avant de répondre, et vous contrôlez l'intensité avec un seul paramètre :
response = client.responses.create(
model="gpt-5-mini",
reasoning={"effort": "low"},
input="Classify this email as billing, bug, or other: 'I was charged twice.'",
)Un effort faible est plus rapide et moins cher. Un effort élevé aide en mathématiques, en code et en planification en plusieurs étapes. Pour une extraction ou une classification simple, commencez bas et n'augmentez que si la qualité baisse. Les niveaux d'effort pris en charge varient un peu selon les modèles, vérifiez donc la page du modèle si une valeur est refusée.
instructions vs input
C'est l'amélioration la plus nette apportée par la Responses API. instructions contient le pilotage au niveau système (personapersonaUne représentation semi-fictive, fondée sur des données, de votre client idéal : ses objectifs, ses frustrations, ses comportements et ses critères de décision.Voir la définition complète →, règles, format de sortie). input est le tour réel de l'utilisateur. Vous n'avez plus à construire à la main une liste de dictionnaires de messages étiquetés par rôle pour les appels simples. Pour un échange unique, deux chaînes suffisent.
response.output_text
Un accesseur pratique qui aplatit la réponse en chaîne de texte finale. L'objet response complet contient davantage : la consommation de tokens, le modèle qui vous a réellement servi, les appels d'outils et des blocs de contenu structurés. Pour un travail rapide, output_text est ce qu'il vous faut. En production, vous lirez les champs plus riches.
Responses ou Chat Completions ?
Vous verrez les deux dans les tutoriels, il faut donc connaître la différence.
Chat Completions (client.chat.completions.create) est l'interface plus ancienne, largement copiée. Elle prend une liste messages de dictionnaires {"role": ..., "content": ...}. Elle fonctionne toujours et n'est pas dépréciée, le code existant ne risque donc rien.
Responses (client.responses.create) est ce qu'OpenAI recommande pour les nouveaux projets. Elle peut conserver l'état de la conversation pour vous, dispose d'outils intégrés (recherche web, recherche de fichiers, code interpreter) que vous activez sans les câbler vous-même, et gère plus proprement l'usage d'outils en plusieurs étapes. La documentation de la Responses API est la référence canonique.
Un troisième nom apparaît dans les anciens guides : l'Assistants API. OpenAI l'a dépréciée au profit de Responses et l'a arrarrL'Annual Recurring Revenue (ARR) est le revenu normalisé et prévisible qu'une entreprise par abonnement attend de ses contrats actifs sur une année.Voir la définition complète →êtée le 26 août 2026. Les tutoriels qui s'appuient dessus ne fonctionnent plus. Si vous héritez de code Assistants, portez-le vers Responses (les threads correspondent aux conversations, les assistants aux prompts réutilisables associés à des outils).
Règle empirique : nouveau code, commencez par Responses. N'utilisez Chat Completions que si vous étendez quelque chose qui s'en sert déjà.
Streaming : les tokens au fur et à mesure
Attendre qu'une longue réponse soit entièrement générée avant d'afficher quoi que ce soit donne aux utilisateurs l'impressionimpressionLe nombre total de fois qu'une publicité ou un contenu est affiché, indépendamment des clics. Chaque affichage compte pour une impression, même auprès de la même personne.Voir la définition complète → que c'est cassé. Le streaming envoie les tokens à mesure que le modèle les produit, ce qui donne l'effet machine à écrire que vous voyez dans ChatGPT.
Vous l'activez avec stream=True et vous itérez sur les événements :
from openai import OpenAI
client = OpenAI()
stream = client.responses.create(
model="gpt-5-mini",
input="Write a two-line haiku about slow APIs.",
stream=True,
)
for event in stream:
if event.type == "response.output_text.delta":
print(event.delta, end="", flush=True)
print()Le stream renvoie des événements typés, pas seulement du texte brut. Vous filtrez sur response.output_text.delta pour capter les fragments de texte incrémentaux. D'autres types d'événements signalent le début de la réponse, l'appel d'un outil et la fin de la génération. flush=True force l'affichage immédiat de chaque fragment dans le terminal au lieu de le mettre en mémoire tampon.
Avec les modèles de raisonnement, il peut y avoir une courte pause avant le premier token de texte, le temps que le modèle réfléchisse. Un effort de raisonnement plus faible la raccourcit.
Le streaming ne change rien au coût ni au résultat final. Il change seulement *le moment* où vous voyez les octets. Utilisez-le pour toute interface face à l'utilisateur et passez-vous-en pour les traitements batch que personne ne regarde.
Trois spécificités OpenAI à connaître tôt
Structured Outputs
Quand vous avez besoin que le modèle renvoie des données que votre code peut parser, ne le suppliez pas de produire du JSON dans le prompt en espérant que ça passe. Utilisez Structured Outputs, qui force la réponse à respecter un schémamaUtiliser un logiciel pour automatiser les tâches et campagnes marketing répétitives, afin de personnaliser à grande échelle sur des canaux comme l'email, le web et le social.Voir la définition complète → que vous définissez. Vous passez un JSON SchemaSchemaUn schema est le plan formel qui définit comment les données sont structurées, nommées, typées et reliées entre elles au sein d'une base de données, d'un fichier ou d'un message.Voir la définition complète → (ou un modèle Pydantic en Python) et OpenAI garantit la forme, vous n'aurez donc plus jamais à écrire de parsing défensif pour un bloc markdown parasite.
from pydantic import BaseModel
from openai import OpenAI
client = OpenAI()
class Ticket(BaseModel):
priority: str
summary: str
response = client.responses.parse(
model="gpt-5-mini",
input="My checkout button has been broken for two days, losing sales.",
text_format=Ticket,
)
ticket = response.output_parsed
print(ticket.priority, "|", ticket.summary)response.output_parsed vous renvoie un objet Ticket typé. Pour qui construit de vraies fonctionnalités, c'est le plus gros gain de fiabilité. Le guide Structured Outputs détaille les règles de schéma.
Function calling
Le modèle peut décider d'appeler des fonctions que vous exposez, en renvoyant le nom de la fonction et les arguments pour que vous l'exécutiez. Vous décrivez vos fonctions, le modèle en choisit une quand c'est pertinent, vous l'exécutez, puis vous lui renvoyez le résultat. Les assistants qui utilisent des outils reposent sur cette primitive. Notez la frontière : le function calling de l'API n'est pas la même chose que les GPT Actions des Custom GPTs. Les Actions sont la version no-code dans le produit ChatGPT. Le function calling est le mécanisme brut que vous contrôlez dans le code.
L'Agents SDK
Quand un appel de fonction devient une boucle de planification, d'appels d'outils et de vérification des résultats, passez à l'Agents SDK. C'est le framework officiel d'OpenAI pour les agents en plusieurs étapes : il gère la boucle d'appels d'outils, les handoffs entre agents spécialisés et les garde-fous, pour que vous n'ayez pas à coder l'orchestration à la main. Vous n'en avez pas besoin pour vos premiers appels. Dès qu'un seul appel Responses ne suffit plus, c'est l'étape suivante naturelle, et il s'appuie directement sur la Responses API.
Vérification des acquis
1. Pourquoi définir votre clé OpenAI comme variable d'environnement plutôt que de l'écrire directement dans votre script ?
2. Un collègue estime que son abonnement ChatGPT Plus devrait couvrir son usage de l'API. Quelle est la bonne clarification ?
3. Vous devez construire un classifieur de texte rapide et bon marché qui se contente d'étiqueter les messages entrants. Quel choix de modèle convient le mieux ?
4. Sélectionnez TOUTES les affirmations correctes sur la Responses API et le client OpenAI tels que décrits dans la leçon.
Sélectionnez toutes les réponses correctes.
5. Sélectionnez TOUTES les affirmations correctes sur la distinction entre 'instructions' et 'input' dans la Responses API.
Sélectionnez toutes les réponses correctes.
Lire correctement l'objet response
Pour tout ce qui dépasse la démo, arrêtez d'afficher output_text et commencez à inspecter l'objet complet. Deux champs comptent tout de suite.
Usage. Chaque réponse indique le nombre de tokens :
print(response.usage.input_tokens, response.usage.output_tokens)
print(response.usage.output_tokens_details.reasoning_tokens)C'est ainsi que vous mesurez le coût. Les tokens d'entrée (votre prompt et vos instructions) et les tokens de sortie (la génération) sont tarifés différemment, et la sortie est généralement la plus chère. Les tokens de raisonnement qu'un modèle GPT-5 consomme pour réfléchir sont facturés comme de la sortie alors que vous ne les voyez jamais, une réponse courte peut donc coûter plus cher que prévu. Journaliser l'usage dès le premier jour vous évite une facture surprise.
Le modèle servi. Le champ model vous indique quelle version exacte du modèle a répondu. Selon que vous figez un snapshot daté ou un alias qui se met à jour automatiquement, c'est ce champ qui vous confirme ce qui a tourné. Pour un comportement reproductible en production, figez un snapshot précis plutôt qu'un alias flottant. Avec des versions intermédiaires tous les quelques mois, c'est plus important qu'avant.
Les erreurs que vous rencontrerez vraiment
Les vrais appels échouent pour de vraies raisons. Gérez explicitement les cas courants :
from openai import OpenAI, RateLimitError, APIError
client = OpenAI()
try:
response = client.responses.create(
model="gpt-5-mini",
input="Summarize the API economy in one line.",
)
print(response.output_text)
except RateLimitError:
print("Slow down or upgrade your tier, then retry with backoff.")
except APIError as err:
print(f"OpenAI-side issue: {err}")RateLimitError est celle que les débutants rencontrent en premier. Les nouveaux comptes API démarrent sur un tier d'usage bas avec des limites par minute modestes, et les tiers augmentent automatiquement avec l'ancienneté du compte et vos dépenses. Ne traitez pas une rate limit comme un bug. Traitez-la comme un signal pour ajouter des retries avec backoff, ce que le SDK peut faire pour vous via le paramètre max_retries du client. APIError et ses sous-classes couvrent l'authentification, les requêtes invalides et les erreurs serveur transitoires. Capturez-les pour qu'un raté ponctuel ne fasse pas planter votre application.
Maîtriser latence et coût
Quelques habitudes paient immédiatement :
- Plafonnez la sortie avec
max_output_tokenspour qu'un modèle bavard ne s'éternise pas et ne fasse pas grimper la facture. Sur les modèles de raisonnement, le plafond inclut les tokens de raisonnement cachés, gardez donc de la marge : un plafond trop serré peut interrompre la réponse avant qu'un texte visible n'apparaisse. - Dimensionnez correctement le modèle et l'effort. La majeure partie du trafic de production tourne très bien sur
gpt-5-miniougpt-5-nanoavec un effort de raisonnement faible. Réservez le flagship et l'effort élevé aux tâches qui en ont besoin. - Streamez les appels face à l'utilisateur, et envoyez les appels de fond indépendants en parallèle plutôt que dans une boucle lente. La vitesse perçue vient du streaming, le débit réel de la concurrence.
Ces leviers (plafond de sortie, modèle et effort, concurrence) couvrent l'essentiel de l'optimisation du coût et de la latence que vous ferez au début.
Points clés
- Démarrez le nouveau code sur la Responses API (
client.responses.create) avecinstructionsetinput. Gardez Chat Completions pour les bases de code existantes. L'Assistants API a été arrêtée en août 2026, portez donc tout ancien code Assistants vers Responses. - Partez par défaut sur la famille GPT-5 (
gpt-5-miniest un bon point de départ, le dernier flagship GPT-5.x pour le travail difficile) et ajustez l'effort dereasoningau lieu de passer à un modèle de raisonnement séparé. - Définissez
OPENAI_API_KEYcomme variable d'environnement et souvenez-vous que votre solde API est distinct de tout abonnement ChatGPT. - Utilisez Structured Outputs (
responses.parseavec un modèle Pydantic) dès que vous avez besoin de données parsables, au lieu de demander du JSON dans le prompt en espérant que ça marche. - Lisez
response.usage, y compris les tokens de raisonnement, dès le premier jour, et définissezmax_output_tokensavec une marge suffisante. - Streamez les interfaces face à l'utilisateur en filtrant les événements
response.output_text.delta, et capturezRateLimitErroravec du backoff plutôt que de laisser votre application planter.
À faire, tiré de cette leçon
Ces actions sont compilées dans le plan d'action du rôle.
- Démarrez tout nouveau code sur l'API Responses et lisez response.usage dès le premier jour