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 de type chatbot, avec un historique clair et un schéma proche des premières API OpenAI.

Cette route est utilisée par ClovisLLM pour les conversations texte et par ClovisOCR pour l'analyse visuelle et l'OCR.

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`	string	✔️	Nom du modèle (`ClovisLLM` ou `ClovisOCR`)
`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 ci-dessous).
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.)

Utilisation avec ClovisLLM

cURL
Python
Node.js

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
    }'

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)

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);

Utilisation avec ClovisOCR

Avec ClovisOCR, la route /v1/chat/completions est utilisée pour l'analyse visuelle et l'OCR. Le message utilisateur combine une instruction texte et une ou plusieurs images (URL ou base64).

Corps de requête (exemple OCR)

{
  "model": "ClovisOcr",
  "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "<image>\n<|grounding|> Convert the document to markdown."
          },
          {
            "type": "image_url",
            "image_url": {
                "url": "data:image/png;base64,AAAA..."
            }
          }
        ]
      }
  ],
  "temperature": 0,
  "max_tokens": 8000
}

OCR & Vision

Pour les détails complets sur les modes OCR, les tokens spéciaux et les exemples, consultez la section OCR & Vision.

Structure​

Description des champs​

Réponse de l'API​

Tableau principal de la réponse​

Détail du champ choices​

Valeurs de finish_reason​

Détails du champ usage​

Détails du sous‑objet message​

À quoi sert le champ role ?​

Résumé rapide​

Utilisation avec ClovisLLM​

Utilisation avec ClovisOCR​