Chat completion

POST/v1/chat/completions

La route /chat/completions permet de générer une réponse à partir d’un échange conversationnel structuré en messages (system, user, assistant). Elle est adaptée aux cas d’usage simples de type chatbot, avec un historique clair et un schéma proche des premières API OpenAI.

Attention

Cette route est progressivement amenée à être remplacée par /responses, plus flexible et plus complète.

Structure

Chaque requête doit inclure un JSON similaire à :

Corps de requête

{
  "model": "ClovisLLM",
  "messages": [
    { "role": "system", "content": "Tu es un assistant utile." },
    { "role": "user", "content": "Explique-moi ce qu’est une API." }
  ],
  "temperature": 0.7,
  "max_tokens": 2000
}

Description des champs

Champ	Type	Obligatoire	Description
model	int	✔️	Nom du modèle
messages	array	✔️	Historique des messages
temperature	float		Créativité (0 = déterministe)
max_tokens	int		Limite de tokens générés
top_p	float		Nucleus sampling
n	int		Nombre de réponses
stream	boolean		Streaming de la réponse
stop	stringarray		Token(s) d’arrêt
presence_penalty	float		Décourage répétitions de sujets
frequency_penalty	float		Décourage répétitions de mots
user	string		Identifiant utilisateur
response_format	object		{ "type": "json_object"}, pour forcer une réponse bien formée.

Réponse de l'API

Tableau principal de la réponse

Champ	Type	Description
id	string	Identifiant unique de la requête (utile pour debug / logs).
object	string	Type d’objet retourné ("chat.completion").
created	int (timestamp)	Timestamp UNIX (en secondes).
model	string	Le modèle effectivement utilisé.
choices	array	Liste des complétions générées (une ou plusieurs).
usage	object	Compte des tokens utilisés.
system_fingerprint	string (optionnel)	Identifiant interne du modèle (utile pour déboguer).

Détail du champ choices

Champ	Type	Description
index	int	Numéro de la réponse (0 = première).
message	object	{ "role": "assistant", "content": "…" } – la vraie réponse du modèle.
finish_reason	string	Raison de l’arrêt de la génération (voir tableau 2.2.2).
provider_specific_fields	object	Métadonnées du backend (latence, modèle réel, etc.).

Valeurs de finish_reason

Valeur	Signification
stop	Réponse terminée naturellement (fin du texte ou fin logique).
length	Arrêté car la limite max_tokens a été atteinte.
content_filter	Arrêté par un filtre de sécurité / modération.
function_call	Appel d’une fonction / outil (API function calling).
tool_calls	Même chose mais au format tools.
null	En cours de streaming partiel ou erreur interne.

Détails du champ usage

Champ	Type	Description
prompt_tokens	int	Nombre de tokens utilisés pour la demande (messages envoyés).
completion_tokens	int	Nombre de tokens générés dans la réponse.
total_tokens	int	Somme des deux précédents.

Détails du sous‑objet message

Champ	Type	Description
role	string	Rôle du message : system, user, assistant, function, tool.
content	string	Texte du message (ce que dit le rôle).

À quoi sert le champ role ?

Valeur	Qui parle ?	Utilisation typique	Exemple
system	Le concepteur / le cadre de l’assistant	Donne le contexte, le ton et les règles de comportement du modèle.	"Tu es un assistant Clovis, toujours poli et concis."
user	L’utilisateur final	Message envoyé par l’humain (question, demande, instruction).	"Explique‑moi ce qu’est un blob Azure."
assistant	Le modèle	Représente la réponse précédente du modèle (utile pour garder l’historique).	"Un blob Azure est un objet de stockage de données..."
function	Résultat d’une fonction (ancienne syntaxe)	Sortie d’une fonction appelée par le modèle (remplacé par tool dans les versions récentes).	"Résultat de la recherche : 3 documents trouvés."
tool	Résultat d’un outil externe	Utilisé dans le cadre du function calling ou d’appels d’API externes.	{"title":"Rapport.pdf"}

Résumé rapide

Corps de requête

{
  "id": "string",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "ClovisLLM",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop",
      "provider_specific_fields": { /* … */ }
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "system_fingerprint": "optional‑string"
}

(Les champs peuvent varier légèrement selon le fournisseur d’API : OpenAI, Azure, Anthropic, etc.)

Exemples d’utilisation

cURL

curl https://llm-gateway.clovis-ai.fr/v1/chat/completions
    -H "Content-Type: application/json"
    -H "Authorization: Bearer sk-xxxxxxxx"
    -d '{
      "model": "ClovisLLM",
      "messages": [
        {"role": "system", "content": "Tu es un assistant utile."},
        {"role": "user", "content": "Explique-moi ce qu’est une API."}
      ],
      "temperature": 0.7
    }'

Python

from openai import OpenAI

client = OpenAI(
  base_url="https://llm-gateway.clovis-ai.fr/v1",
  api_key="sk-xxxx"
)

response = client.chat.completions.create(
  model="ClovisLLM",
  messages=[
    {"role": "system", "content": "Tu es un assistant utile."},
    {"role": "user", "content": "Explique-moi ce qu’est une API."}
  ]
)
print(response.choices[0].message.content)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-xxxx",
  baseURL: "https://llm-gateway.clovis-ai.fr/v1",
});

const response = await client.chat.completions.create({
  model: "ClovisLLM",
  messages: [
    { role: "system", content: "Tu es un assistant technique." },
    { role: "user", content: "Explique-moi ce qu’est une API." },
  ],
});

console.log(response.choices[0].message.content);