Chat completion

POST/v1/chat/completions

The /chat/completions route allows you to generate a response from a conversational exchange structured as messages (system, user, assistant). It is suited for simple chatbot use cases, with a clear history and a schema similar to early OpenAI APIs.

Warning

This route is gradually being replaced by /responses, which is more flexible and more complete.

Structure

Each request must include a JSON similar to:

Request body

{
  "model": "ClovisLLM",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Explain what an API is." }
  ],
  "temperature": 0.7,
  "max_tokens": 2000
}

Field description

Field	Type	Required	Description
model	int	✔️	Model name
messages	array	✔️	Message history
temperature	float		Creativity (0 = deterministic)
max_tokens	int		Maximum number of generated tokens
top_p	float		Nucleus sampling
n	int		Number of responses
stream	boolean		Enable response streaming
stop	stringarray		Stop token(s)
presence_penalty	float		Discourages topic repetition
frequency_penalty	float		Discourages word repetition
user	string		User identifier
response_format	object		{ "type": "json_object"}, to enforce a well-formed response.

API Response

Main response object

Field	Type	Description
id	string	Unique request identifier (useful for debugging / logs).
object	string	Returned object type ("chat.completion").
created	int (timestamp)	UNIX timestamp (in seconds).
model	string	The model actually used.
choices	array	List of generated completions (one or more).
usage	object	Token usage details.
system_fingerprint	string (optional)	Internal model identifier (useful for debugging).

Details of the choices field

Field	Type	Description
index	int	Response index (0 = first).
message	object	{ "role": "assistant", "content": "…" } – the actual model response.
finish_reason	string	Reason why generation stopped (see table below).
provider_specific_fields	object	Backend metadata (latency, actual model, etc.).

Values of finish_reason

Value	Meaning
stop	Response completed naturally (end of text or logical completion).
length	Stopped because the max_tokens limit was reached.
content_filter	Stopped due to a safety / moderation filter.
function_call	Function/tool call (function calling API).
tool_calls	Same but using the tools format.
null	Partial streaming or internal error.

Details of the usage field

Field	Type	Description
prompt_tokens	int	Number of tokens used for the request (input messages).
completion_tokens	int	Number of tokens generated in the response.
total_tokens	int	Sum of the two above.

Details of the message object

Field	Type	Description
role	string	Message role: system, user, assistant, function, tool.
content	string	Message content (what the role says).

What is the role field used for?

Value	Speaker	Typical usage	Example
system	The designer / assistant framework	Sets the context, tone, and behavior rules of the model.	"You are a Clovis assistant, always polite and concise."
user	The end user	Message sent by the human (question, request, instruction).	"Explain what an Azure blob is."
assistant	The model	Represents the model’s previous response (used to maintain history).	"An Azure blob is a data storage object..."
function	Function result (legacy syntax)	Output of a function called by the model (replaced by tool in newer versions).	"Search result: 3 documents found."
tool	External tool result	Used in function calling or external API calls.	{"title":"Report.pdf"}

Quick summary

Response body

{
  "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"
}

(Fields may vary slightly depending on the API provider: OpenAI, Azure, Anthropic, etc.)

Usage examples

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": "You are a helpful assistant."},
        {"role": "user", "content": "Explain what an API is."}
      ],
      "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": "You are a helpful assistant."},
    {"role": "user", "content": "Explain what an API is."}
  ]
)
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: "You are a technical assistant." },
    { role: "user", content: "Explain what an API is." },
  ],
});

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