Comment utiliser l'API OpenAI Responses

Ce guide vous expliquera comment utiliser l'API OpenAI Responses de bout en bout : à la fin, vous serez en mesure d'envoyer une requête à POST /v1/responses, de lire la sortie imbriquée qu'elle renvoie, d'activer les outils intégrés, de gérer l'état de la conversation à travers les appels, et de vérifier l'intégralité du contrat dans Apidog. L'API Responses est la nouvelle interface d'OpenAI pour générer des sorties de modèle, et le guide officiel de Responses explique pourquoi OpenAI oriente désormais les nouveaux projets vers elle. Si vous testez déjà l'ancien point de terminaison, vous pouvez réutiliser la majeure partie de cette configuration, de la même manière que le flux de travail de notre guide de test de l'API ChatGPT.

bouton

Ce dont vous avez besoin en premier

Avant d'envoyer une requête, assurez-vous d'avoir quelques éléments en place :

Une clé API OpenAI avec accès à un modèle polyvalent actuel. Conservez la clé dans une variable d'environnement, et non collée dans une commande ou un fichier partagé.
Un nom de modèle que votre compte peut réellement appeler. Plutôt que d'en coder un en dur, vérifiez la liste des modèles dans votre tableau de bord OpenAI et confirmez-le par rapport au point de terminaison.
Un moyen d'envoyer des requêtes HTTP brutes et d'inspecter le JSON qui en résulte. Un terminal avec curl fonctionne pour un premier appel, et Apidog est ce que vous utiliserez pour affirmer et simuler la réponse plus tard.

Il est également utile de savoir ce que fait le point de terminaison avant de l'appeler. L'API Responses expose un seul point de terminaison, POST /v1/responses. Vous envoyez un nom de modèle et une input, et vous recevez en retour un objet de réponse qui peut contenir du texte brut, des appels de fonction et les résultats d'outils hébergés par OpenAI comme la recherche web ou la recherche de fichiers. Un seul appel peut exécuter un tour multi-étapes complet : le modèle décide de rechercher sur le web, lit les résultats, puis écrit une réponse, et la réponse enregistre chaque étape qu'il a effectuée.

Deux choses le distinguent d'un point de terminaison de texte brut. Premièrement, il peut exécuter des outils intégrés côté serveur, vous n'avez donc pas besoin de configurer votre propre recherche ou bac à sable. Deuxièmement, il est par défaut avec état. Chaque réponse reçoit un id, et vous pouvez transmettre cet id à la requête suivante afin qu'OpenAI conserve l'historique de la conversation pour vous. OpenAI décrit l'API Responses comme l'évolution des Chat Completions et la recommande pour les nouveaux projets, en intégrant les leçons tirées de la bêta de l'API Assistants. Ainsi, au lieu de trois modèles mentaux, vous en obtenez un seul.

Savoir comment elle diffère des Chat Completions

Si vous avez utilisé POST /v1/chat/completions, le changement concerne principalement la forme et l'état. Les Chat Completions prennent un tableau de messages et renvoient des choices. Vous gérez vous-même la transcription complète, renvoyant chaque tour précédent à chaque appel. Les outils sont quelque chose que vous implémentez de votre côté.

L'API Responses prend une input (une chaîne ou une liste d'éléments typés) et renvoie une output (une liste d'éléments typés). Elle peut stocker le tour pour vous et exécuter des outils hébergés sans plomberie supplémentaire.

Voici la comparaison pratique :

Aspect	Chat Completions	API Responses
Point de terminaison	`POST /v1/chat/completions`	`POST /v1/responses`
Corps de la requête	tableau `messages`	`input` (chaîne ou éléments) + `instructions`
Structure de la sortie	`choices[].message`	liste `output` d'éléments typés
État de la conversation	Vous renvoyez l'historique complet	`store` + `previous_response_id`
Outils intégrés	Vous les construisez	`web_search`, `file_search`, `code_interpreter`, et plus encore
Statut	Pris en charge, aucune dépréciation annoncée	Recommandé pour les nouveaux projets

Les Chat Completions ne vont pas disparaître. OpenAI déclare qu'elles resteront prises en charge, et vous pouvez migrer un flux utilisateur à la fois plutôt que de tout réécrire d'un coup. L'API Assistants est celle qui a une date limite : OpenAI l'a dépréciée le 26 août 2025, avec un arrêt prévu le 26 août 2026, donc les nouveaux travaux d'agents devraient commencer sur Responses.

Effectuez votre première requête

Voici un appel minimal. Remplacez le nom du modèle par celui auquel votre compte a accès, et gardez votre clé hors de la commande elle-même.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does.",
    "instructions": "You are a concise technical writer. No marketing language.",
    "store": true
  }'

Vous transmettez ici trois éléments importants : le model, l'input (votre invite), et les instructions (la direction au niveau du système). La définition de store sur true indique à OpenAI de sauvegarder la réponse afin que vous puissiez continuer le fil de discussion plus tard.

Lisez la réponse

Une réponse tronquée ressemble à ceci :

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 24,
    "total_tokens": 52
  }
}

Notez la structure, car c'est la partie qui pose problème. Le texte que vous voulez se trouve à output[0].content[0].text, et non dans un champ de niveau supérieur. Les SDK officiels ajoutent un accesseur pratique output_text qui agrège tous les éléments de texte en une seule chaîne, mais cette propriété est une aide du SDK, et non une partie du JSON HTTP brut. Lorsque vous appelez directement le point de terminaison, vous lisez le chemin imbriqué. L'id de niveau supérieur est ce que vous réutiliserez pour l'état, et usage.total_tokens vous indique le coût de l'appel.

Ajoutez des outils intégrés

La principale caractéristique est qu'OpenAI exécute certains outils pour vous. Vous les listez dans un tableau tools et le modèle décide quand les appeler. Les types intégrés vérifiés incluent :

web_search pour les recherches internet en direct avec citations (l'ancienne web_search_preview fonctionne toujours pour les intégrations héritées mais manque de nouveaux contrôles).
file_search pour la récupération à travers les fichiers que vous avez téléchargés.
code_interpreter pour l'exécution et l'analyse de code dans un bac à sable.
computer_use pour piloter une interface informatique.
image_generation pour produire des images en ligne.

L'activation d'un outil est un petit ajout au corps de la requête :

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [{ "type": "web_search" }]
}

Lorsque le modèle utilise un outil, le tableau output gagne des entrées qui documentent l'étape, comme un élément web_search_call à côté du message final. C'est utile plus tard : vous pouvez vérifier qu'un outil a réellement été déclenché, et pas seulement que du texte a été renvoyé.

Continuez la conversation à travers les appels

L'état fonctionne via deux paramètres. store est défini par défaut sur true, ce qui signifie qu'OpenAI enregistre l'objet de réponse (conservé pendant 30 jours par défaut) et renvoie un id. Transmettez cet id en tant que previous_response_id lors de votre prochain appel et le modèle poursuivra le fil de discussion sans que vous ayez à renvoyer la transcription :

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}

Si vous préférez garder les choses sans état, ou si vous avez une exigence de rétention de données nulle, définissez store sur false et gérez le contexte vous-même. Pour les flux vocaux et audio en temps réel et à faible latence, OpenAI utilise une surface différente ; notre guide de l'API GPT en temps réel couvre ce cas. Et si vous orchestrez des agents multi-étapes en plus de tout cela, les modèles s'alignent avec le SDK OpenAI Agents.

Comment le tester dans Apidog

Apidog est une plateforme de test, de conception et de simulation d'API. Ce n'est pas un SDK OpenAI ni une bibliothèque de code, vous n'écrirez donc pas de Python avec. Ce que vous faites à la place : construire la requête HTTP brute vers /v1/responses, l'envoyer et écrire des assertions sur le JSON qui en résulte. C'est exactement le type de vérification de contrat qui détecte une intégration défectueuse avant que vos utilisateurs ne le fassent.

Voici la configuration, étape par étape.

Stockez la clé dans une variable d'environnement

Dans Apidog, créez un environnement (par exemple, "OpenAI Prod") et ajoutez une variable comme OPENAI_API_KEY. Conservez la valeur dans l'environnement, et non dans la requête, afin que le secret ne soit jamais commis dans une collection partagée. Ensuite, construisez une nouvelle requête POST vers https://api.openai.com/v1/responses et ajoutez l'en-tête Authorization: Bearer {{OPENAI_API_KEY}}. Apidog substitue la variable au moment de l'envoi.

Définissez le corps sur JSON et collez la requête précédente. Cliquez sur envoyer. Vous verrez l'objet de réponse complet, formaté, avec le tableau output imbriqué.

Affirmez sur les champs de réponse

Un succès 200 ne prouve pas que la réponse a la forme attendue par votre application. Ajoutez des assertions pour qu'une régression échoue bruyamment. Vérifications utiles contre une réponse /v1/responses :

status est égal à completed.
output[0].content[0].text existe et n'est pas vide.
usage.total_tokens est supérieur à 0.
Lorsque vous envoyez des tools, un élément dans output a un type égal à web_search_call.

Le générateur d'assertions visuelles d'Apidog vous permet de cibler ces chemins JSON sans écrire de scripts de test, et notre modèle de cas de test API montre comment structurer de telles vérifications. Enregistrez la requête dans une collection et elle devient un test répétable que vous pouvez exécuter en CI.

Simulez la réponse pour un développement hors ligne

Les appels OpenAI coûtent de l'argent et nécessitent un accès réseau, ce qui est délicat lorsque vous construisez l'interface utilisateur qui consomme la réponse ou exécutez des tests dans un pipeline qui ne devrait pas appeler une API payante. La fonction de simulation d'Apidog résout ce problème. Enregistrez une charge utile /v1/responses représentative comme simulation, pointez votre application vers l'URL de simulation Apidog, et votre frontend obtiendra la bonne forme JSON sans dépenser un seul jeton. Lorsque le véritable point de terminaison change, vous mettez à jour une seule simulation au lieu de courir après les échecs dans chaque test. Notre explicateur d'API de simulation décrit l'approche générale.

Cette distinction est importante. Vous testez par rapport au point de terminaison réel pour vérifier le contrat d'OpenAI, et vous le simulez pour un développement rapide, hors ligne et déterministe. Les deux s'exécutent à partir du même projet Apidog.

Foire aux questions

L'API Responses remplace-t-elle les Chat Completions ?

Pas de force. OpenAI qualifie Responses d'évolution des Chat Completions et la recommande pour les nouveaux projets, mais les Chat Completions restent prises en charge sans date de dépréciation annoncée. Vous pouvez migrer un flux à la fois. L'API Assistants est celle qui est retirée, avec une date d'arrêt en 2026.

Quelle est la différence entre `store` et `previous_response_id` ?

store contrôle si OpenAI enregistre l'objet de réponse (il est par défaut sur true et conserve pendant 30 jours). previous_response_id est la façon dont vous liez une nouvelle requête à une requête stockée afin que le modèle continue la conversation côté serveur. Vous les utilisez ensemble pour les fils de discussion avec état, et désactivez store lorsque vous souhaitez un comportement sans état.

Quels modèles supportent l'API Responses ?

Les modèles polyvalents actuels d'OpenAI sont conçus pour fonctionner avec l'API Responses, mais la disponibilité dépend de votre compte et du modèle que vous choisissez. Plutôt que de coder en dur un nom de modèle, vérifiez la liste des modèles dans votre tableau de bord OpenAI, puis confirmez-le par rapport au point de terminaison. Envoyer une requête rapide via Apidog et lire le champ model dans la réponse est un moyen rapide de vérifier ce que votre clé peut réellement appeler.

Puis-je tester les outils intégrés sans écrire de code ?

Oui. Ajoutez un tableau tools au corps JSON dans Apidog, envoyez la requête, et affirmez que l'élément d'appel d'outil correspondant (comme web_search_call) apparaît dans le tableau output. Vous vérifiez le comportement d'OpenAI via HTTP, aucun SDK n'est donc requis. Pour tester plus largement les appels d'outils d'agent, consultez comment générer des collections de tests API à partir de spécifications OpenAPI.

En résumé

Vous avez maintenant la boucle complète : un point de terminaison, POST /v1/responses, qui gère le texte, les outils hébergés et l'état de la conversation côté serveur. Envoyez une requête, lisez l'output imbriqué, ajoutez un tableau tools lorsque vous avez besoin d'une recherche ou d'une exécution de code, et chaînez previous_response_id pour maintenir un fil de discussion. Parce que la forme est différente des Chat Completions, le moyen le plus sûr est de vérifier le contrat vous-même plutôt que de vous fier à votre mémoire de l'ancienne API.

C'est là qu'Apidog intervient. Construisez la requête, stockez votre clé comme variable d'environnement, affirmez sur les champs output imbriqués, et simulez la réponse pour le travail hors ligne, le tout dans un seul projet. Téléchargez Apidog et pointez un test vers /v1/responses pour voir exactement ce que votre intégration reçoit. Vous pouvez effectuer toute la configuration dans Apidog sans écrire une seule ligne de code de test.