OpenAI API : Guide de spécification et d'implémentation de l'API Responses et des Structured Outputs

Introduction

En entrant dans l'année 2025, l'API OpenAI a atteint un tournant majeur. En mars 2025, l'API Responses a été officiellement publiée (GA), consolidant les capacités de conversation de l'API Chat Completions et les fonctionnalités d'intégration d'outils de l'API Assistants en un seul endpoint. L'API Assistants héritée est prévue pour être désactivée le 26 août 2026.

De plus, les Structured Outputs, qui garantissent que les sorties du modèle respectent strictement un schéma JSON, démontrent leur véritable potentiel lorsqu'elles sont combinées avec l'API Responses. Depuis leur publication en août 2024, elles ont considérablement amélioré la fiabilité des workflows agentiques et des pipelines d'extraction de données.

Cet article présente d'abord le panorama global de l'API OpenAI en 2025, puis plonge dans les spécifications et les détails d'implémentation de ces deux sujets clés.

Informations sur les sources
Les spécifications et les données de performance dans cet article font référence à la documentation officielle OpenAI (developers.openai.com/api), au guide de migration officiel (developers.openai.com/api/docs/guides/migrate-to-responses), et au blog officiel (openai.com/index/introducing-structured-outputs-in-the-api).

1. Aperçu du panorama des APIs

Les principales catégories de l'API OpenAI en 2025 sont organisées comme suit :

OpenAI a positionné l'API Responses comme la destination principale pour les nouvelles fonctionnalités, et la désactivation de l'API Assistants le 26 août 2026 a été officiellement confirmée (source : Guide de migration officiel). Bien que l'API Chat Completions continuera à être supportée sans date de désactivation, l'API Responses est la recommandation actuelle pour les nouveaux projets.

Les Structured Outputs ne sont pas un endpoint indépendant comme ceux du tableau ci-dessus, mais plutôt une option de contrôle du format de sortie disponible pour l'API Responses et l'API Chat Completions. Elle est spécifiée en utilisant le paramètre text.format dans la première et le paramètre response_format dans la seconde. Cet article se concentre particulièrement sur sa combinaison avec l'API Responses.

2. API Responses

2.1 Aperçu

L'API Responses est un nouveau primitive qui succède à l'API Chat Completions et intègre les fonctionnalités de l'API Assistants. Elle a atteint la disponibilité générale (GA) en mars 2025.

Le changement le plus significatif est la capacité à persister l'état de la conversation côté serveur. Contrairement aux Chat Completions traditionnels qui nécessitaient d'inclure tout l'historique de la conversation dans chaque requête, l'API Responses permet de continuer une conversation simplement en passant un previous_response_id.

2.2 Requête de base

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Tell me the weather in Tokyo.",
});

console.log(response.output_text); // Récupérer le texte directement avec le helper output_text

2.3 Le helper output_text

output_text est une propriété de commodité fournie par le SDK OpenAI, pas une partie de la spécification de l'API elle-même.

Dans la réponse brute de l'API Responses, le texte est imbriqué dans la structure suivante :

response.output[0].content[0].text

output_text résume le processus de parcours de ce chemin. En interne, il renvoie le texte du premier élément du tableau output qui a type: "message" et un bloc content avec type: "output_text".

// Les deux produisent la même sortie
console.log(response.output_text);
console.log(response.output[0].content[0].text);

Cependant, il peut ne pas fonctionner comme prévu si le premier élément du tableau output n'est pas un message texte — par exemple, lorsqu'un appel d'outil se produit. Pour du code agentique robuste utilisant des outils, il est préférable de parcourir le tableau output et de vérifier le type.

for (const item of response.output) {
  if (item.type === "message") {
    for (const block of item.content) {
      if (block.type === "output_text") {
        console.log(block.text);
      }
    }
  }
}

2.4 role dans les messages d'entrée

Lorsque vous passez un tableau à input, vous pouvez spécifier un role pour chaque message. Le role indique au modèle « qui fait cette déclaration », et il y a trois types.

const response = await client.responses.create({
  model: "gpt-4o",
  input: [
    {
      role: "system",
      content: "You are a helpful Japanese assistant. Please answer concisely.",
    },
    {
      role: "user",
      content: "Tell me about JavaScript array methods.",
    },
  ],
});

Si vous passez une chaîne directement à input (comme dans l'exemple de la section 2.2), cette chaîne est traitée comme un message avec role: "user". Utilisez le format tableau si vous souhaitez un contrôle fin sur le comportement du modèle ou si vous souhaitez fournir des instructions system.

2.5 Structure de la réponse

Contrairement aux choices de Chat Completions, les résultats sont renvoyés dans un tableau output.

{
  "id": "resp_68af4030...",
  "object": "response",
  "created_at": 1756315696,
  "model": "gpt-4o",
  "output": [
    {
      "id": "msg_68af4033...",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The weather in Tokyo is sunny."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 12,
    "total_tokens": 27
  }
}

2.6 Conversation multi-tours

Il existe deux façons de réaliser une conversation multi-tours avec l'API Responses.

1. Passer l'historique sous forme de tableau dans input

C'est la méthode traditionnelle de l'API Chat Completions. Vous maintenez et gérez l'historique de la conversation côté client et incluez tous les messages dans chaque requête.

const history = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "Tell me the weather in Tokyo." },
  { role: "assistant", content: "It is sunny in Tokyo today." },
];

const response = await client.responses.create({
  model: "gpt-4o",
  input: [...history, { role: "user", content: "How about tomorrow?" }],
});

Comme l'état n'est pas conservé sur le serveur, l'avantage est que vous pouvez librement manipuler l'historique, par exemple en supprimant ou en résumant des messages spécifiques. Cependant, à mesure que la conversation s'allonge, le nombre de tokens d'entrée augmente, impactant à la fois le coût et la latence.

2. Passer previous_response_id (exclusif à l'API Responses)

C'est la méthode de gestion d'état côté serveur nouvellement introduite avec l'API Responses. En passant simplement l'ID de la réponse précédente, les serveurs d'OpenAI garderont l'historique de la conversation.

// Premier tour
const response1 = await client.responses.create({
  model: "gpt-4o",
  input: "Tell me the weather in Tokyo.",
});

// Deuxième tour : le contexte est hérité en utilisant uniquement previous_response_id
const response2 = await client.responses.create({
  model: "gpt-4o",
  input: "How about tomorrow?",
  previous_response_id: response1.id,
});

Le client n'a pas besoin de maintenir ou envoyer tout l'historique, ce qui maintient la taille des requêtes petite. De plus, lors de l'utilisation de modèles de raisonnement comme o1 ou o3, les tokens de réflexion sont préservés entre les tours, ce qui est un avantage significatif car cela améliore la précision pour les tâches nécessitant un raisonnement continu.

Pour utiliser cette méthode, la réponse doit être sauvegardée sur le serveur. Notez que bien que le paramètre store soit true par défaut, le définir à store: false rendra impossible la référence par ID.

Critères de sélection

Si une gestion de conversation persistante est requise, l'intégration avec l'API Conversations est également possible.

2.7 Outils intégrés

L'un des plus grands avantages de l'API Responses est l'ensemble d'outils intégrés disponibles sans infrastructure supplémentaire.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Search for the latest OpenAI news and summarize it.",
  tools: [
    { type: "web_search_preview" },
    { type: "file_search" },
    { type: "code_interpreter" },
  ],
});

Intégration MCP (Model Context Protocol)

Les Connectors sont des wrappers MCP maintenus par OpenAI pour des services populaires comme Google Workspace ou Dropbox, tandis que les serveurs MCP distants sont n'importe quel serveur sur l'internet public qui implémente le protocole MCP distant (source : Guide OpenAI Connectors et MCP).

L'API Responses peut s'intégrer avec des serveurs MCP distants supportant les protocoles de transport Streamable HTTP ou HTTP/SSE. Lorsqu'un outil est spécifié, l'API récupère d'abord la liste des outils disponibles depuis le serveur (mcp_list_tools), et le modèle appelle ensuite les outils nécessaires de cette liste.

Exemple de connexion de base (source : Guide OpenAI Using tools)

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Roll 2d6 and tell me the result.",
  tools: [
    {
      type: "mcp",
      server_label: "dice_server",           // Identifiant pour le serveur (arbitraire)
      server_url: "https://example.com/mcp", // URL du serveur MCP
      require_approval: "never",             // Approuver automatiquement les appels d'outils
    },
  ],
});

console.log(response.output_text);

Contrôle d'approbation avec require_approval

Par défaut, tous les appels d'outils nécessitent une approbation explicite du développeur. Vous pouvez contrôler ce comportement avec require_approval (source : Guide OpenAI Connectors et MCP).

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Tell me about the MCP specification's transport protocols.",
  tools: [
    {
      type: "mcp",
      server_label: "deepwiki",
      server_url: "https://mcp.deepwiki.com/mcp",
      require_approval: {
        never: {
          // Ces deux outils ne nécessitent pas d'approbation ; les autres si
          tool_names: ["ask_question", "read_wiki_structure"],
        },
      },
    },
  ],
});

Connexion aux serveurs nécessitant une authentification

Si le serveur MCP nécessite une authentification, passez le token en utilisant le paramètre headers.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Fetch some data.",
  tools: [
    {
      type: "mcp",
      server_label: "my_server",
      server_url: "https://my-mcp-server.example.com/mcp",
      require_approval: "never",
      headers: {
        Authorization: `Bearer ${process.env.MCP_ACCESS_TOKEN}`,
      },
    },
  ],
});

Mise en cache de la liste d'outils : Bien que la récupération de la liste d'outils depuis le serveur MCP (mcp_list_tools) se produise par requête, dans les conversations multi-tours utilisant previous_response_id, la liste d'outils est incluse dans la réponse précédente, donc la re-récupération est ignorée (source : OpenAI Cookbook: MCP Tool Guide).

2.8 Principaux paramètres de requête

2.9 Comparaison avec Chat Completions

2.10 Modèles de raisonnement (série o)

Distincts de la série GPT, OpenAI propose un groupe de modèles appelés modèles de raisonnement. Ces modèles exécutent un processus de réflexion interne étape par étape (Chain-of-Thought) avant de générer une réponse. Cette réflexion interne est comptée comme des tokens de raisonnement, qui ne sont pas inclus dans la sortie finale.

Ils démontrent une précision significativement supérieure à GPT-4o pour les tâches nécessitant un raisonnement en plusieurs étapes, telles que les mathématiques, le codage, l'inférence logique et l'analyse complexe. D'un autre côté, la latence et les coûts sont plus élevés car la réflexion prend du temps.

Les principaux modèles en 2025 sont :

La profondeur de raisonnement peut être ajustée avec le paramètre reasoning_effort (voir 2.8). low est un raisonnement léger qui réduit la latence et le coût, tandis que high est un raisonnement profond pour une précision maximale.

const response = await client.responses.create({
  model: "o3",
  input: "Find the general term for this sequence: 1, 1, 2, 3, 5, 8, 13, ...",
  reasoning_effort: "high",
});

De plus, dans les conversations multi-tours utilisant previous_response_id (voir 2.6, méthode 2), les tokens de raisonnement sont préservés entre les tours. Lors d'un approfondissement du même problème sur plusieurs tours, la précision et l'efficacité s'améliorent car le modèle hérite du raisonnement du tour précédent au lieu de repartir de zéro.

3. Structured Outputs

3.1 Aperçu et contexte

Forcer de manière fiable les sorties LLM au format JSON a été un défi clé pour l'intégration d'applications. OpenAI a résolu cela progressivement :

Le mode JSON (fonctionnalité héritée) garantit un JSON syntaxiquement correct, mais ne garantit pas l'adhérence à un schéma. Il y avait un risque de champs requis manquants ou de champs supplémentaires non souhaités.

Les Structured Outputs, publiées en août 2024, garantissent une adhérence à 100 % à un schéma JSON spécifié par le développeur (source : Blog officiel OpenAI).

Les évaluations internes (evals) chez OpenAI montrent que gpt-4o-2024-08-06 atteint une adhérence de 100 % à des schémas JSON complexes en utilisant les Structured Outputs, un bond considérable par rapport aux moins de 40 % de gpt-4-0613 (source : Blog officiel OpenAI).

3.2 Fonctionnement

L'API OpenAI réalise les sorties structurées en convertissant le schéma JSON spécifié en une grammaire hors-contexte (CFG). Cette grammaire contraint les tokens pouvant être générés lors de l'échantillonnage, imposant la conformité au schéma. Pour cette raison, la première fois qu'un nouveau schéma est envoyé, il y a une latence supplémentaire pour le pré-traitement de la grammaire, mais les requêtes suivantes avec le même schéma n'ont pas cette pénalité.

Note (modèles fine-tunés) : Pour les modèles fine-tunés, une latence supplémentaire se produit à la première requête utilisant un nouveau schéma. Les requêtes suivantes avec le même schéma n'ont pas cela. Les autres modèles n'ont pas cette limitation. (Source : Guide Structured Outputs)

3.3 Deux façons d'utiliser

Les Structured Outputs sont fournies sous deux formes sur l'API.

La première est via l'appel de fonction (tools), activé en définissant strict: true dans la définition de la fonction. Disponible pour tous les modèles à partir de gpt-4-0613, cela convient pour connecter les capacités du modèle aux applications (par exemple, accéder à une fonction de requête de base de données).

La seconde est via le paramètre response_format / text.format, où spécifier un json_schema convient pour que le modèle réponde à l'utilisateur dans un format structuré (par exemple, afficher différentes parties séparément dans une UI de tutoriel mathématique).

3.4 Exemple d'implémentation (API Responses)

Dans l'API Responses, le paramètre a été déplacé de response_format vers text.format (source : Guide de migration officiel).

À propos de description dans le schéma

Il est fortement recommandé d'inclure une description pour chaque champ dans votre schéma JSON. La description agit comme une instruction pour le modèle, fournissant des indices pour l'aider à déterminer correctement ce qui doit aller dans ce champ. Les noms de champs généraux comme explanation ou output sont particulièrement susceptibles d'être mal compris par le modèle sans description.

Lors de l'utilisation de Zod, utilisez .describe("..."). Lors de l'écriture directe du schéma JSON, spécifiez-le avec la clé "description" dans l'objet de propriété.

Définition du schéma avec Zod (Recommandé)

import OpenAI from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const client = new OpenAI();

const Step = z.object({
  explanation: z.string().describe("Explanation of what is being done in this calculation step."),
  output: z.string().describe("The calculation result for this step (formula or numerical value)."),
});

const MathResponse = z.object({
  steps: z.array(Step).describe("A list of steps for the solution."),
  final_answer: z.string().describe("The final answer to the equation (e.g., x = -3.75)."),
});

const response = await client.responses.parse({
  model: "gpt-4o",
  input: [
    { role: "system", content: "You are a math tutor. Explain step-by-step." },
    { role: "user", content: "Solve 8x + 7 = -23" },
  ],
  text: { format: zodResponseFormat(MathResponse, "math_response") },
});

const result = response.output_parsed;
console.log(result.final_answer);
for (const step of result.steps) {
  console.log(step.explanation, "->", step.output);
}

Spécification directe du schéma JSON

const response = await client.responses.create({
  model: "gpt-4o",
  input: [
    { role: "system", content: "You are a math tutor." },
    { role: "user", content: "Solve 8x + 7 = -23" },
  ],
  text: {
    format: {
      type: "json_schema",
      name: "math_response",
      strict: true,
      schema: {
        type: "object",
        description: "A response showing the step-by-step solution of an equation.",
        properties: {
          steps: {
            type: "array",
            description: "A list of steps for the solution.",
            items: {
              type: "object",
              properties: {
                explanation: {
                  type: "string",
                  description: "Explanation of what is being done in this calculation step.",
                },
                output: {
                  type: "string",
                  description: "The calculation result for this step (formula or numerical value).",
                },
              },
              required: ["explanation", "output"],
              additionalProperties: false,
            },
          },
          final_answer: {
            type: "string",
            description: "The final answer to the equation (e.g., x = -3.75).",
          },
        },
        required: ["steps", "final_answer"],
        additionalProperties: false,
      },
    },
  },
});

Note : Le champ correct dans l'API Responses est text.format. L'ancienne clé response_format est dépréciée dans l'API Responses (source : Communauté développeurs OpenAI).

3.5 Structured Outputs dans l'appel de fonction

Pour appliquer les Structured Outputs à un appel d'outil, ajoutez strict: true à la définition de la fonction.

const response = await client.responses.create({
  model: "gpt-4o",
  input: "Tell me the delivery date for order #12345",
  tools: [
    {
      type: "function",
      name: "get_delivery_date",
      description: "Get the scheduled delivery date for an order.",
      strict: true,
      parameters: {
        type: "object",
        properties: {
          order_id: { type: "string" },
        },
        required: ["order_id"],
        additionalProperties: false,
      },
    },
  ],
});

Restriction : Lors de l'utilisation des Structured Outputs pour l'appel de fonction, parallel_tool_calls doit être défini à false.

3.6 Ce que les Structured Outputs garantissent (et ce qu'elles ne garantissent pas)

Exemple de gestion du refusal :

const response = await client.responses.parse({
  model: "gpt-4o",
  input: [/* ... */],
  text: { format: zodResponseFormat(MathResponse, "math_response") },
});

if (response.output[0].content[0].type === "refusal") {
  console.log("Model refused:", response.output[0].content[0].refusal);
} else {
  const result = response.output_parsed;
}

3.7 Contraintes de schéma en mode strict

En mode strict: true, certaines fonctionnalités JSON Schema sont restreintes (source : Guide Structured Outputs).

• additionalProperties: false est requis.
• Toutes les propriétés doivent être incluses dans le tableau required.
• L'utilisation directe de anyOf au niveau de l'objet racine n'est pas autorisée.
• Des restrictions s'appliquent aux combinaisons comme oneOf, anyOf, etc.

Pour éviter les divergences entre schémas et définitions de types, OpenAI recommande officiellement et fortement d'utiliser le SDK avec le support natif de Zod.

4. API Realtime

L'API Realtime, qui a atteint la disponibilité générale (GA) en 2025, est une API spécialisée pour le streaming vocal et textuel bidirectionnel à faible latence via WebRTC, WebSocket ou SIP. Elle est conçue pour des cas d'utilisation d'interaction en temps réel tels que les agents vocaux connectés directement depuis un navigateur ou l'intégration avec des systèmes téléphoniques (PBX), distinguant clairement son utilisation de l'API Responses. Pour plus de détails, consultez le Guide officiel de l'API Realtime.

5. Streaming

L'API Responses supporte le streaming au format Server-Sent Events (SSE), vous permettant de recevoir de longues réponses de manière incrémentielle.

const stream = await client.responses.stream({
  model: "gpt-4o",
  input: "Tell me in detail about the beginning of the universe.",
});

for await (const event of stream) {
  if (
    event.type === "response.output_text.delta" &&
    event.delta
  ) {
    process.stdout.write(event.delta);
  }
}

Les Structured Outputs peuvent également être combinées avec le streaming, auquel cas un JSON complet et conforme au schéma est retourné à la fin.

6. En-têtes de réponse HTTP

Les réponses API incluent des en-têtes utiles pour le débogage et la surveillance du débit.

Si vous souhaitez spécifier un ID de requête depuis le côté client, ajoutez l'en-tête X-Client-Request-Id.

7. Limites de débit

Les limites de débit sont appliquées par organisation et projet (pas par utilisateur).

• RPM (Requests Per Minute) : Nombre de requêtes par minute.
• TPM (Tokens Per Minute) : Nombre de tokens par minute.

Les niveaux d'utilisation sont automatiquement mis à niveau en fonction des paiements cumulés et de l'historique d'utilisation. Si 429 Too Many Requests est retourné, il est recommandé de réessayer avec un backoff exponentiel (source : Guide sur les limites de débit).

import retry from "async-retry";

async function callApiWithBackoff(params) {
  return retry(
    async () => {
      return await client.responses.create(params);
    },
    {
      retries: 6,
      minTimeout: 1000,
      maxTimeout: 60000,
      randomize: true,
    }
  );
}

8. Stabilité des versions et épinglage du modèle

Les alias comme gpt-4o sont périodiquement mis à jour vers de nouveaux snapshots, ce qui peut modifier la sortie même pour le même prompt. En production, il est recommandé d'épingler un nom de snapshot comme gpt-4o-2024-08-06 et de toujours effectuer une évaluation (eval) lors de la mise à jour.

Résumé

Liens utiles

• Guide de migration de l'API Responses — Guide de migration officiel.
• Guide Structured Outputs — Guide officiel des Structured Outputs.
• Introducing Structured Outputs in the API — Blog de publication officiel.
• Guide de l'API Realtime — Détails sur la voix et le texte bidirectionnel en temps réel.
• Guide sur les limites de débit — Détails sur les limites de débit.
• Journal des modifications OpenAI — Historique des mises à jour de l'API.