API Chat Completions d’OpenAI : guide des fonctionnalités et de l’utilisation

Créer une application reposant sur l’IA ne consiste pas seulement à demander à un modèle de générer des réponses. Il vous faut aussi un moyen fiable de gérer les conversations, d’orienter les réponses et de relier le tout à votre application. L’API Chat Completions d’OpenAI rend cela possible en donnant aux développeurs le contrôle de la manière dont l’IA traite les messages et génère des réponses. Si vous souhaitez comprendre son fonctionnement et l’utiliser dans vos propres projets, cet article vous présente tout ce que vous devez savoir.

L’API Chat Completions d’OpenAI permet aux développeurs d’intégrer les modèles de langage d’OpenAI dans des applications et des services. Elle génère des réponses à partir d’une séquence de messages et prend en charge des tâches telles que la conversation, les réponses aux questions, la génération de contenu et l’analyse de texte.

Chat Completions reste pris en charge. Pour les nouveaux projets, OpenAI recommande la Responses API. Ce guide se concentre sur Chat Completions afin d’expliquer son format de message, ses paramètres de requête et son utilisation avec des SDK compatibles.

Contrairement au point de terminaison Completions hérité (/v1/completions), qui accepte un prompt textuel, Chat Completions accepte une liste structurée de messages. Chaque message possède un rôle, tel que developer, user ou assistant, qui aide le modèle à interpréter les instructions et le contexte de la conversation. Les rôles et les types de contenu pris en charge dépendent du modèle sélectionné.

Les développeurs peuvent utiliser l’API pour créer diverses fonctionnalités reposant sur l’IA, notamment :

• Applications conversationnelles : créez des chatbots IA, des assistants virtuels et des systèmes de support client qui répondent aux messages des utilisateurs.

• Génération de contenu : générez des articles, des descriptions de produits, des e-mails, des résumés et d’autres contenus écrits.

• Analyse de texte : classez des textes, extrayez des informations, analysez le sentiment et identifiez les points clés dans des documents.

• Assistance au codage : générez des extraits de code, expliquez des concepts de programmation et aidez les développeurs à résoudre les erreurs.

• Traitement du langage : traduisez, reformulez, simplifiez et relisez des textes dans différentes langues.

L’API offre un moyen flexible de connecter des modèles de langage à des logiciels existants, ce qui permet aux développeurs d’intégrer des réponses générées par l’IA dans leurs applications sans avoir à créer ni à héberger leurs propres modèles de langage.

L’API Chat Completions repose sur un flux de requête et de réponse. Une application envoie au point de terminaison de l’API une requête contenant un identifiant de modèle et une liste de messages. Le modèle sélectionné traite l’entrée et renvoie une réponse générée.

Le flux de base comprend les étapes suivantes :

1. Préparer la conversation : l’application recueille l’entrée de l’utilisateur et l’organise dans une liste de messages. Les messages précédents de la conversation peuvent également être inclus pour fournir du contexte.

2. Envoyer une requête API : l’application envoie une requête POST à https://api.openai.com/v1/chat/completions avec le modèle sélectionné et la liste de messages. Les requêtes utilisent un en-tête Authorization: Bearer <API_KEY>. La méthode client.chat.completions.create() du SDK Python gère cette structure de requête et l’authentification.

3. Traiter l’entrée : le modèle interprète les messages, prend en compte leurs rôles et leur contenu, puis génère une réponse en fonction du contexte et des paramètres fournis.

4. Recevoir la réponse : une requête sans streaming renvoie une réponse JSON contenant la complétion générée et des métadonnées. Lorsque le streaming est activé, l’API envoie une séquence d’événements envoyés par le serveur (SSE), que l’application traite à mesure de leur arrivée.

5. Afficher ou traiter la sortie : l’application extrait le message généré et l’affiche à l’utilisateur ou le transmet à un autre composant de l’application.

Le flux repose sur le modèle de requête et de réponse de l’API Chat Completions d’OpenAI.

Pour utiliser efficacement l’API Chat Completions, les développeurs doivent comprendre ses principaux paramètres de requête et leur incidence sur le comportement du modèle.

Le paramètre model indique quel modèle de langage traite la requête. Les différents modèles peuvent offrir des capacités, des vitesses de réponse, des performances de raisonnement et des tarifs différents.

Les développeurs doivent sélectionner un modèle en fonction de la complexité de la tâche, de la qualité de réponse attendue, des exigences de latence et du budget.

Le paramètre messages contient un tableau de messages de conversation. Chaque message inclut généralement les champs role et content.

Les rôles courants incluent :

Choisissez le rôle d’instruction pris en charge par votre modèle ; vous n’avez pas besoin d’envoyer à la fois des messages system et developer pour les mêmes instructions. Pour conserver le contexte d’un tour à l’autre, incluez l’historique pertinent de la conversation dans chaque requête. Les fournisseurs compatibles peuvent prendre en charge des rôles différents ; consultez donc leur propre documentation de modèle lorsque vous adaptez une intégration.

Pour les modèles et configurations qui le prennent en charge, temperature contrôle le caractère aléatoire de l’échantillonnage. La référence de l’API définit une plage de 0 à 2, avec une valeur par défaut de 1. Vérifiez la prise en charge des paramètres du modèle sélectionné avant de définir une valeur personnalisée.

• Température basse : produit des réponses plus ciblées et prévisibles, ce qui est utile pour la classification, l’extraction d’informations et les tâches structurées.

• Température élevée : permet davantage de variations dans le texte généré, ce qui peut être utile pour le brainstorming et l’écriture créative.

Certaines configurations de raisonnement n’acceptent pas de valeurs personnalisées pour temperature ou top_p. Pour ces configurations, omettez ces paramètres d’échantillonnage et utilisez plutôt des contrôles pris en charge, tels que l’effort de raisonnement et les limites de sortie.

Lorsqu'il est pris en charge, top_p contrôle la sélection des tokens par échantillonnage nucleus. Il définit le seuil de probabilité cumulée utilisé pour choisir les tokens candidats.

Par exemple, une valeur de 0,1 signifie que le modèle considère les tokens compris dans les 10 % supérieurs de la masse de probabilité cumulée. Des valeurs plus faibles produisent généralement une sortie plus ciblée, tandis que des valeurs plus élevées autorisent davantage de variations.

OpenAI recommande d'ajuster temperature ou top_p, plutôt que de modifier les deux simultanément.

Le paramètre max_completion_tokens définit le nombre maximal de tokens que le modèle peut générer dans une réponse, y compris les tokens de raisonnement le cas échéant.

Définir une limite appropriée aide les développeurs à contrôler la longueur de la sortie et à gérer la consommation de tokens. Si le modèle atteint cette limite avant d'avoir terminé sa réponse, la complétion peut se terminer avec le motif de fin length.

Le paramètre stream détermine si l'API renvoie la réponse générée en une seule fois ou progressivement à mesure qu'elle est produite.

• false : renvoie la réponse complète une fois la génération terminée.

• true : transmet les données de réponse à l'application en continu via des événements envoyés par le serveur (SSE).

Le streaming est utile pour les interfaces de chat et les applications dans lesquelles les utilisateurs ont intérêt à voir les réponses s'afficher progressivement plutôt que d'attendre l'intégralité de la sortie.

Le paramètre response_format sélectionne le format de sortie sur les modèles pris en charge. Le texte est le format par défaut. Définir type sur json_object active le mode JSON, qui produit un JSON valide sans imposer de schéma particulier. Ajoutez aux messages une instruction demandant de renvoyer du JSON.

Pour des champs et des types de données prévisibles, utilisez les sorties structurées basées sur JSON Schema avec type: "json_schema" et strict: true sur un modèle compatible. Seul le sous-ensemble pris en charge de JSON Schema peut être utilisé en mode strict. Avant de traiter le résultat, vérifiez l'absence de refus ou de réponse tronquée. Consultez le guide des sorties structurées pour les détails de configuration.

Le paramètre tool_choice contrôle la sélection des outils lorsque le modèle prend en charge l'appel d'outils via Chat Completions. La prise en charge dépend à la fois du modèle et de sa configuration de raisonnement ; certains modèles plus récents nécessitent l'API Responses pour utiliser des outils. Vérifiez ces exigences avant d'ajouter des outils à une requête.

Les paramètres courants incluent :

• none : empêche le modèle d'appeler des outils.

• auto : permet au modèle de décider s'il doit appeler un outil disponible.

• required : oblige le modèle à appeler un ou plusieurs outils.

Cette fonctionnalité prend en charge l'appel de fonctions, ce qui permet à une application de relier les décisions générées par le modèle à des fonctions, des bases de données et des services externes. L'application est responsable de l'exécution de la fonction demandée et du renvoi de son résultat au modèle.

Utilisez la référence de l'API Chat Completions pour les définitions des paramètres et les exigences de compatibilité des modèles. L'exemple Python ci-dessous utilise une requête texte simple, sans outils.

Les développeurs peuvent accéder à l'API Chat Completions via des requêtes HTTP ou un SDK officiel. L'exemple suivant utilise Python pour envoyer une requête conversationnelle et récupérer la réponse générée.

Étape 1 : obtenir une clé API

Créez une clé API sur la plateforme API d'OpenAI et assurez-vous que votre compte a accès au modèle sélectionné ainsi qu'à des crédits API ou à une capacité de facturation suffisants. Stockez la clé dans une variable d'environnement plutôt que dans le code source de l'application. Sur macOS ou Linux, exécutez :

Remplacez YOUR_API_KEY par votre propre clé. Sous Windows, définissez la même variable OPENAI_API_KEY dans votre shell ou dans l'environnement système.

Étape 2 : installer le SDK Python OpenAI

Installez la bibliothèque Python officielle à l'aide de pip :

Étape 3 : initialiser le client API

Importez le SDK et initialisez le client. OpenAI() lit automatiquement la variable d'environnement OPENAI_API_KEY définie à l'étape 1.

Étape 4 : envoyer une requête de complétion de chat

Appelez client.chat.completions.create() avec un modèle et une liste de messages. Cet exemple utilise gpt-6-astra avec un faible effort de raisonnement et une limite totale de génération de 4 096 tokens. Si ce modèle n'est pas disponible pour votre compte, choisissez un modèle prenant en charge Chat Completions et ajustez les paramètres selon sa documentation.

Dans cet exemple :

• model identifie le modèle de langage utilisé pour générer la réponse.

• messages fournissent les instructions et l'entrée utilisateur.

• reasoning_effort définit l'effort de raisonnement pour les modèles prenant en charge ce paramètre.

• max_completion_tokens limite le nombre de tokens générés, y compris les tokens de raisonnement. Il ne garantit pas une quantité précise de texte visible.

• response.choices[0].message.content extrait la réponse de l'assistant.

Traiter la réponse de l’API

Pour cette requête sans streaming, l’API renvoie du JSON contenant la complétion et les métadonnées de la requête. Le SDK Python l’analyse dans un objet ChatCompletion, d’où l’accès aux champs via des attributs tels que response.choices[0].message.content.

Les champs importants de la réponse incluent :

Le champ finish_reason peut aider les développeurs à comprendre comment une génération s’est terminée. Les valeurs courantes sont notamment stop, length et tool_calls.

Les développeurs peuvent également examiner le champ usage pour suivre la consommation de token en entrée et en sortie, ce qui est utile pour estimer les coûts liés à l’API et optimiser son utilisation dans l’application.

Cet exemple présente une réponse textuelle de base. Lorsque vous ajoutez le streaming, une sortie structurée ou des outils, mettez à jour la requête et la logique de traitement des réponses en fonction du modèle et du point de terminaison sélectionnés.

Pour les développeurs qui cherchent une alternative à l’API OpenAI Chat Completions, Kimi API donne accès aux grands modèles de langage de Moonshot AI via un format d’API compatible avec OpenAI.

Kimi propose les interfaces Chat Completions, Responses et Messages. L’exemple ci-dessous utilise son point de terminaison Chat Completions compatible avec OpenAI afin de réutiliser le flux de travail du SDK présenté plus haut. Configurez une clé Kimi API, définissez l’URL de base Kimi et sélectionnez un modèle pris en charge. Consultez la documentation de Kimi pour les paramètres des modèles, les rôles des messages et la prise en charge des outils.

Étape 1 : obtenir une clé Kimi API

Inscrivez-vous sur la plateforme Kimi API et créez une clé API dans la console développeur. Vérifiez votre solde, votre accès aux modèles et les limites de débit du compte avant d’effectuer votre première requête.

Stockez la clé Kimi dans une variable d’environnement distincte. Sous macOS ou Linux, exécutez :

Remplacez YOUR_KIMI_API_KEY par votre propre clé Kimi. Sous Windows, définissez la même variable KIMI_API_KEY dans votre environnement.

Étape 2 : installer le SDK Python OpenAI

Si le SDK n’est pas déjà installé, exécutez :

Étape 3 : configurer le client Kimi API

Créez un kimi_client distinct à l’aide de l’URL de base Kimi et de la variable KIMI_API_KEY définie à l’étape 1. La lecture de la clé avec os.environ permet de signaler immédiatement sous forme d’erreur l’absence d’une variable d’environnement.

Étape 4 : envoyer une requête Chat Completions

Utilisez la même méthode du SDK avec le client Kimi. Cette requête sélectionne kimi-k3, utilise le rôle system pris en charge par Kimi pour les instructions et renvoie une réponse textuelle sans streaming.

• Options de modèles pour différentes charges de travail : Kimi K3.1 Pro prend en charge le raisonnement complexe, le codage à long terme et le travail de connaissance. Sa variante Highspeed offre des sorties plus rapides avec les mêmes capacités de modèle. L’exemple ci-dessus utilise Kimi K3 ; consultez la liste actuelle des modèles pour connaître leur disponibilité et les recommandations de migration.

• Compatibilité avec l’API OpenAI : les développeurs habitués au format OpenAI Chat Completions peuvent réutiliser une structure de requête similaire et les flux de travail des SDK pris en charge pour intégrer les modèles Kimi.

• Conversations à plusieurs tours : les développeurs peuvent fournir l’historique des messages pour prendre en charge des conversations tenant compte du contexte, des assistants virtuels et des applications interactives.

• Streaming et appels de fonctions : l’API prend en charge les réponses en streaming et les flux de travail d’appel d’outils, ce qui permet aux développeurs de créer des applications plus interactives et de connecter les modèles à des fonctions externes.

• Entrée multimodale : les modèles Kimi pris en charge peuvent traiter différents types d’entrée, notamment du texte, des images et des vidéos, selon les capacités du modèle.

Lorsqu’ils utilisent l’API Chat Completions, les développeurs peuvent rencontrer des erreurs liées à l’authentification, à la configuration de l’API, à la disponibilité des modèles ou aux limites de requêtes. Comprendre ces problèmes courants peut vous aider à les identifier et à faire fonctionner correctement votre intégration :

• Clé API invalide ou manquante : des erreurs d’authentification, telles qu’une erreur HTTP 401, peuvent survenir si la clé API est incorrecte, expirée, révoquée ou mal configurée. Vérifiez que la clé est valide, que la variable d’environnement est correctement chargée et que la requête inclut les identifiants d’authentification appropriés.

• URL de base de l’API incorrecte : les requêtes envoyées à un point de terminaison incorrect peuvent renvoyer des erreurs telles que 404 ou des échecs de connexion. Vérifiez que l’URL de base correspond à la documentation du fournisseur d’API et que la requête utilise le chemin de point de terminaison adéquat. Lorsque vous passez d’OpenAI à un fournisseur compatible, n’oubliez pas de mettre à jour l’URL de base en conséquence.

• ID de modèle invalide ou indisponible : une requête peut échouer si le nom de modèle indiqué est incorrect, indisponible pour votre compte ou non pris en charge par le point de terminaison sélectionné. Consultez la documentation du fournisseur relative aux modèles et vérifiez que l’ID du modèle correspond à celui disponible pour votre compte API.

• Longueur de contexte dépassée : si l’ensemble des messages d’entrée et de la sortie générée dépasse la fenêtre de contexte du modèle, l’API peut rejeter la requête. Réduisez la longueur de l’entrée, supprimez l’historique de conversation inutile ou résumez les messages précédents avant de renvoyer la requête.

• Sortie tronquée : une réponse peut s’interrompre avant d’avoir terminé le contenu demandé si elle atteint la limite max_completion_tokens. Augmentez la limite de token lorsque cela est pris en charge, ou divisez une tâche de génération longue en requêtes plus petites. Vous pouvez également examiner choices[].finish_reason afin de vérifier si la réponse s’est terminée en raison de la limite length.

• Limite de débit ou quota dépassé : pour OpenAI, une erreur HTTP 429 peut indiquer une limite de débit de requêtes ou de token, une limite de dépenses ou une autre restriction d’utilisation. Examinez le type et le code de l’erreur avant de réessayer. En cas de limite de débit temporaire, réduisez la fréquence des requêtes et respectez Retry-After lorsqu’il est fourni, ou utilisez un délai d’attente exponentiel.

Si l’erreur indique que les crédits sont épuisés ou qu’une limite de facturation ou de dépenses a été atteinte, vérifiez le solde et les paramètres de facturation du compte ; des tentatives répétées ne rétabliront pas l’accès. Si vous utilisez Kimi ou un autre fournisseur compatible, consultez la documentation de ce fournisseur sur les codes d’erreur, car les codes d’état et les règles de quota peuvent différer.

Pour déboguer plus efficacement, vérifiez le code d’état HTTP et le message d’erreur renvoyés par l’API avant de modifier les paramètres de votre requête. Ces informations permettent de distinguer les problèmes d’authentification, les erreurs de configuration et les limites d’utilisation.

L’API Chat Completions peut prendre en charge un large éventail de scénarios applicatifs. Son format de messages structuré et ses paramètres de génération personnalisables la rendent adaptée aussi bien aux fonctionnalités textuelles simples qu’aux flux de travail d’IA plus complexes.

• Chatbots d’IA et assistants virtuels : les développeurs peuvent utiliser l’API pour créer des assistants conversationnels destinés aux sites web, aux applications mobiles et aux plateformes de service client. En transmettant les messages précédents dans les requêtes suivantes, les applications peuvent conserver le contexte de la conversation et fournir des réponses plus pertinentes.

• Création de contenu et révision de texte : l’API peut générer et transformer du texte à partir des instructions de l’utilisateur. Les applications peuvent l’utiliser pour rédiger des articles de blog, écrire des textes marketing, résumer des contenus longs, reformuler des paragraphes et adapter les styles d’écriture à différents publics et objectifs.

• Classification de texte et extraction d’informations : les entreprises peuvent intégrer l’API dans des flux de travail qui traitent de grands volumes de texte. Par exemple, elle peut classer les retours clients, identifier le sentiment exprimé, extraire des informations importantes des messages et organiser des contenus non structurés dans des catégories prédéfinies.

• Assistants de programmation : L’API peut prendre en charge les outils de développement logiciel en générant du code, en expliquant des concepts de programmation, en suggérant des solutions et en aidant les développeurs à identifier les erreurs. Les applications peuvent également connecter le modèle à des outils de développement externes grâce à l’appel de fonctions.

• Workflows métier propulsés par l’IA : Les développeurs peuvent intégrer l’API à des applications métier afin d’automatiser les tâches répétitives liées au langage. Cela inclut notamment le traitement des demandes clients, la génération de rapports, l’extraction d’informations à partir de documents et la préparation de réponses fondées sur des instructions prédéfinies.

L’API Chat Completions d’OpenAI offre aux développeurs un moyen concret d’intégrer une IA conversationnelle à leurs applications et de créer des expériences utilisateur plus utiles. Le choix du bon modèle, la compréhension de ses paramètres et le traitement rigoureux des réponses de l’API peuvent réellement influencer les performances d’une application. Toutefois, les développeurs ne sont pas obligés de s’appuyer sur un seul fournisseur pour créer des solutions propulsées par l’IA. Si vous souhaitez explorer une autre option, essayez Kimi API et découvrez comment sa configuration compatible avec OpenAI répond à vos besoins de développement.