API chat completions : compatible OpenAI et traitée dans l'UE

POST /v1/chat/completions reçoit une conversation et renvoie le message suivant de l'assistant. La conversation est une liste de messages, chacun avec un role (system, user, assistant ou tool) et un content. Le modèle relit toute la liste à chaque appel : l'API ne conserve rien. Pour poursuivre un échange, ajoutez la réponse et la nouvelle question, puis renvoyez la liste.

Comme le format est celui d'OpenAI, les SDK officiels Python et JavaScript, LangChain, LlamaIndex et la plupart des frameworks d'agents l'appellent sans adaptateur. Le champ model désigne le modèle : en changer revient à modifier une chaîne.

Seuls model et messages sont obligatoires. max_tokens limite la longueur de la réponse, tandis que temperature et top_p règlent sa variabilité : une valeur basse pour l'extraction ou la classification, plus élevée pour la rédaction. stop interrompt la génération sur une chaîne donnée et seed rend les résultats plus reproductibles.

Avec stream: true, les tokens arrivent au fur et à mesure. tools permet au modèle d'appeler vos fonctions et response_format impose un JSON conforme à un schéma. Avec un modèle de vision, les images passent dans content sous forme de parties image_url. Un paramètre non pris en charge est ignoré ou refusé avec un message explicite.

Une requête réussie renvoie un objet avec un id, le model qui a répondu et un tableau choices. Le texte se trouve dans choices[0].message.content. Si le modèle choisit d'appeler un outil, message.tool_calls contient à la place le nom de la fonction et ses arguments JSON.

finish_reason indique pourquoi la génération s'est arrêtée : stop pour une fin naturelle, length quand max_tokens est atteint, tool_calls quand le modèle attend le résultat de vos outils. L'objet usage donne prompt_tokens, completion_tokens et total_tokens : c'est la base de facturation, et ce que vous devriez journaliser pour suivre vos coûts par fonctionnalité.

La plupart des fonctionnalités suivent la même structure : un message système fixe qui pose le ton et les règles, quelques passages de contexte récupérés, puis la question de l'utilisateur. Gardez ce message système identique d'une requête à l'autre pour que le cache de prompts puisse le réutiliser, et placez le contenu variable à la fin.

Lorsque le résultat est lu par un programme (étiquettes, routage, champs extraits), associez une temperature basse à response_format pour obtenir un JSON valide plutôt que du texte libre. Pour une interface de chat, diffusez la réponse en streaming et résumez les anciens échanges avant d'atteindre la fenêtre de contexte du modèle.

Les erreurs reprennent le format d'OpenAI : un statut HTTP et un objet error avec message, type et code. Un 400 signale le plus souvent un champ invalide ou un prompt qui dépasse la fenêtre de contexte. Un 401 indique une clé absente ou erronée, un 404 un identifiant de modèle inconnu, un 429 une limite de votre offre atteinte.

Vérifiez finish_reason à chaque réponse. Avec length, la réponse est tronquée : augmentez max_tokens ou demandez une réponse plus courte. Réessayez les erreurs 429 et 5xx avec un délai exponentiel, en respectant l'en-tête Retry-After lorsqu'il est présent.