+190 XP

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 API est désormais l'interface par défaut, et comment streamer les tokens 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 :

bash
export OPENAI_API_KEY="sk-proj-..."
pip install openai

Le 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 cré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 :

python
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 :

python
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 (persona, 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 arrê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'impression 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 :

python
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éma que vous définissez. Vous passez un JSON Schema (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.

python
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 ?

CHOIX MULTIPLES

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.

CHOIX MULTIPLES

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 :

python
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 :

python
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_tokens pour 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-mini ou gpt-5-nano avec 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) avec instructions et input. 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-mini est un bon point de départ, le dernier flagship GPT-5.x pour le travail difficile) et ajustez l'effort de reasoning au lieu de passer à un modèle de raisonnement séparé.
  • Définissez OPENAI_API_KEY comme variable d'environnement et souvenez-vous que votre solde API est distinct de tout abonnement ChatGPT.
  • Utilisez Structured Outputs (responses.parse avec 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éfinissez max_output_tokens avec une marge suffisante.
  • Streamez les interfaces face à l'utilisateur en filtrant les événements response.output_text.delta, et capturez RateLimitError avec 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
Voir le plan d'action complet →