DEV Community

Cover image for Comment utiliser l'API OpenAI Responses
Antoine Laurent
Antoine Laurent

Posted on • Originally published at apidog.com

Comment utiliser l'API OpenAI Responses

Ce guide montre comment utiliser l’API OpenAI Responses de bout en bout : envoyer une requête à POST /v1/responses, lire la sortie imbriquée, activer les outils intégrés, gérer l’état d’une conversation entre plusieurs appels, puis vérifier le contrat HTTP 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 l’oriente vers les nouveaux projets. Si vous testez déjà l’ancien point de terminaison, vous pouvez réutiliser une grande partie de votre configuration, comme dans notre guide de test de l’API ChatGPT.

Essayez Apidog aujourd’hui

Ce dont vous avez besoin

Avant d’appeler l’API, préparez ces éléments :

  • Une clé API OpenAI avec accès à un modèle compatible.
  • Une variable d’environnement pour stocker la clé, par exemple OPENAI_API_KEY.
  • Un nom de modèle réellement disponible pour votre compte.
  • Un client HTTP pour envoyer des requêtes brutes : curl, Apidog ou tout autre outil équivalent.
  • Un moyen d’inspecter le JSON retourné et d’écrire des assertions sur sa structure.

Le point de terminaison principal est :

POST https://api.openai.com/v1/responses
Enter fullscreen mode Exit fullscreen mode

Vous envoyez un model et une input, puis l’API renvoie un objet de réponse contenant une liste output. Cette sortie peut inclure du texte, des appels de fonctions et des résultats d’outils hébergés par OpenAI, comme la recherche web ou la recherche de fichiers.

Deux points sont importants :

  1. L’API peut exécuter des outils intégrés côté serveur.
  2. Elle peut conserver l’état d’une conversation via un id de réponse et previous_response_id.

Différences avec Chat Completions

Si vous avez déjà utilisé POST /v1/chat/completions, le changement principal concerne la forme des données et la gestion de l’état.

Avec Chat Completions, vous envoyez un tableau messages et vous récupérez choices[].message. Vous devez renvoyer vous-même l’historique complet à chaque appel.

Avec Responses, vous envoyez une input et vous récupérez une liste output d’éléments typés. Vous pouvez aussi chaîner les appels avec previous_response_id.

Aspect Chat Completions API Responses
Point de terminaison POST /v1/chat/completions POST /v1/responses
Corps de requête Tableau messages input + instructions
Structure de sortie choices[].message Liste output d’éléments typés
État de conversation Vous renvoyez l’historique complet store + previous_response_id
Outils intégrés À implémenter côté application web_search, file_search, code_interpreter, etc.
Statut Pris en charge Recommandé pour les nouveaux projets

Les Chat Completions restent prises en charge. Vous pouvez donc migrer progressivement. L’API Assistants, elle, a été dépréciée le 26 août 2025, avec un arrêt prévu le 26 août 2026.

Envoyer une première requête

Voici un appel minimal avec curl.

Remplacez gpt-5.5 par un modèle disponible dans votre compte OpenAI.

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
  }'
Enter fullscreen mode Exit fullscreen mode

Les champs essentiels sont :

  • model : le modèle à appeler.
  • input : la demande utilisateur.
  • instructions : les consignes de comportement du modèle.
  • store : indique si OpenAI doit stocker la réponse pour pouvoir continuer la conversation ensuite.

Lire la réponse

Une réponse simplifié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
  }
}
Enter fullscreen mode Exit fullscreen mode

Le texte final n’est pas dans un champ de premier niveau. Dans le JSON brut, il se trouve ici :

output[0].content[0].text
Enter fullscreen mode Exit fullscreen mode

À surveiller dans votre intégration :

  • id : à réutiliser comme previous_response_id.
  • status : doit généralement être completed.
  • output[] : contient les messages et les éventuels appels d’outils.
  • usage.total_tokens : utile pour suivre la consommation.

Les SDK officiels peuvent exposer un raccourci comme output_text, mais ce champ est une aide du SDK, pas une propriété du JSON HTTP brut.

Activer les outils intégrés

L’API Responses peut déclencher des outils côté serveur. Vous les déclarez dans le tableau tools, puis le modèle décide quand les utiliser.

Exemple avec la recherche web :

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

Types d’outils intégrés mentionnés par OpenAI :

  • web_search : recherche web avec citations.
  • file_search : recherche dans des fichiers téléversés.
  • code_interpreter : exécution et analyse de code dans un bac à sable.
  • computer_use : contrôle d’une interface informatique.
  • image_generation : génération d’images en ligne.

Lorsque le modèle utilise un outil, output contient des éléments supplémentaires, par exemple un élément de type web_search_call, en plus du message final.

C’est utile pour les tests : vous pouvez vérifier que l’outil a bien été appelé, et pas seulement qu’un texte a été généré.

Continuer une conversation

La continuité fonctionne avec deux paramètres :

  • store
  • previous_response_id

Quand store est activé, OpenAI conserve l’objet de réponse et renvoie un id.

Vous pouvez ensuite envoyer une nouvelle requête comme ceci :

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

Le modèle poursuit alors le fil de discussion sans que vous renvoyiez tout l’historique.

Si vous voulez une intégration sans état, définissez :

{
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

Dans ce cas, votre application doit gérer elle-même le contexte.

Pour les flux vocaux ou audio temps réel à faible latence, OpenAI utilise une autre surface d’API. Voir notre guide de l’API GPT en temps réel. Pour les agents multi-étapes, consultez aussi le SDK OpenAI Agents.

Tester l’API Responses dans Apidog

Apidog sert ici à tester le contrat HTTP de l’API. Vous ne l’utilisez pas comme SDK OpenAI, mais comme client de test, de conception et de simulation d’API.

Objectif :

  1. Construire la requête POST /v1/responses.
  2. Envoyer la requête réelle à OpenAI.
  3. Inspecter le JSON retourné.
  4. Ajouter des assertions sur les champs critiques.
  5. Simuler la réponse pour le développement hors ligne.

1. Stocker la clé API dans un environnement

Dans Apidog :

  1. Créez un environnement, par exemple OpenAI Prod.
  2. Ajoutez une variable OPENAI_API_KEY.
  3. Créez une requête POST.
  4. Utilisez l’URL : 
https://api.openai.com/v1/responses
Enter fullscreen mode Exit fullscreen mode

Ajoutez ensuite les en-têtes :

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Puis collez un corps JSON comme celui-ci :

{
  "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
}
Enter fullscreen mode Exit fullscreen mode

Apidog remplace {{OPENAI_API_KEY}} au moment de l’envoi.

2. Ajouter des assertions sur la réponse

Un statut HTTP 200 ne suffit pas. Votre application dépend d’une forme JSON précise.

Ajoutez des assertions sur ces champs :

  • status est égal à completed.
  • output[0].content[0].text existe.
  • output[0].content[0].text n’est pas vide.
  • usage.total_tokens est supérieur à 0.
  • Si tools contient web_search, alors un élément de output doit avoir type = web_search_call.

Exemple de logique de vérification :

status == "completed"
output[0].content[0].text exists
usage.total_tokens > 0
Enter fullscreen mode Exit fullscreen mode

Le générateur d’assertions visuelles d’Apidog permet de cibler ces chemins JSON sans écrire de script. Pour structurer ce type de validation, vous pouvez aussi consulter ce modèle de cas de test API.

Une fois la requête enregistrée dans une collection, elle devient un test réutilisable, y compris en CI.

3. Simuler la réponse pour le développement hors ligne

Les appels OpenAI coûtent de l’argent et nécessitent un accès réseau. Pour développer une interface ou exécuter des tests déterministes, vous pouvez simuler la réponse.

Dans Apidog :

  1. Enregistrez une réponse /v1/responses représentative.
  2. Créez une simulation basée sur ce JSON.
  3. Pointez votre application vers l’URL de simulation Apidog.
  4. Développez contre la même structure JSON sans appeler OpenAI.

Votre frontend reçoit alors une réponse de même forme que l’API réelle, par exemple avec :

{
  "id": "resp_mock",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Mocked response for local development."
        }
      ]
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Le principe est simple :

  • Test réel : vérifier le contrat d’OpenAI.
  • Simulation : développer vite, hors ligne, avec des réponses déterministes.

Pour plus de contexte, voir cet explicateur sur les API de simulation.

Foire aux questions

L’API Responses remplace-t-elle Chat Completions ?

Pas immédiatement. OpenAI présente Responses comme l’évolution de Chat Completions et la recommande pour les nouveaux projets, mais Chat Completions reste pris en charge sans date de dépréciation annoncée.

Vous pouvez migrer un flux utilisateur à la fois.

Quelle est la différence entre store et previous_response_id ?

store indique si OpenAI conserve l’objet de réponse. Il est activé par défaut et la conservation est de 30 jours par défaut.

previous_response_id permet de lier une nouvelle requête à une réponse stockée précédente.

Utilisez les deux pour les conversations avec état. Désactivez store si vous voulez gérer vous-même tout le contexte.

Quels modèles supportent l’API Responses ?

Les modèles polyvalents actuels d’OpenAI sont conçus pour fonctionner avec Responses, mais la disponibilité dépend de votre compte.

Ne codez pas un nom de modèle en dur sans vérification. Consultez la liste des modèles dans votre tableau de bord OpenAI, puis envoyez une requête de test et vérifiez le champ model dans la réponse.

Peut-on tester les outils intégrés sans écrire de code ?

Oui.

Dans Apidog :

  1. Ajoutez un tableau tools au corps JSON.
  2. Envoyez la requête.
  3. Vérifiez que l’élément d’appel d’outil attendu apparaît dans output.

Exemple :

{
  "model": "gpt-5.5",
  "input": "Search the web and summarize the result.",
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Assertion attendue :

output contains item where type == "web_search_call"
Enter fullscreen mode Exit fullscreen mode

Pour aller plus loin sur les collections de tests, voir comment générer des collections de tests API à partir de spécifications OpenAPI.

En résumé

L’API Responses centralise la génération de texte, les outils hébergés et l’état de conversation autour d’un seul point de terminaison :

POST /v1/responses
Enter fullscreen mode Exit fullscreen mode

La boucle d’implémentation est la suivante :

  1. Envoyer une requête avec model, input et éventuellement instructions.
  2. Lire le texte dans output[0].content[0].text.
  3. Ajouter tools si vous avez besoin de recherche, de fichiers ou d’exécution de code.
  4. Chaîner les appels avec previous_response_id.
  5. Tester le contrat JSON au lieu de supposer qu’il ressemble à Chat Completions.

Avec Apidog, vous pouvez construire la requête, stocker votre clé dans une variable d’environnement, ajouter des assertions sur output, puis simuler la réponse pour le développement hors ligne. Téléchargez Apidog et pointez une requête de test vers /v1/responses pour vérifier exactement ce que votre intégration reçoit.

Top comments (0)