Responses

POST/v1/responses

The /responses route is a unified and modern interface for handling complex inputs (text, tools) and structured outputs. It provides greater flexibility for advanced use cases, especially agentic AI and tool calling. It is the recommended route for new OpenAI-compatible developments.

Structure

Each request must include a JSON similar to:

Request body

{
"model": "ClovisLLM",
"input": [
  {
    "role": "system",
    "content": [
      { "type": "input_text", "text": "You are a helpful assistant." }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "input_text", "text": "Explain what an API is." }
    ]
  }
],
"temperature": 0.7,
"max_output_tokens": 2000
}

Field description

Request body

Field	Type	Required	Description
model	string	✔️	Name of the model to use.
input	stringarray	✔️	Model input: raw text or structured history.
temperature	float		Creativity (0 = deterministic).
max_output_tokens	int		Maximum number of generated tokens.
top_p	float		Nucleus sampling.
stream	boolean		Enables response streaming.
stop	stringarray		Stop token(s).
presence_penalty	float		Discourages topic repetition.
frequency_penalty	float		Discourages word repetition.
user	string		User identifier (tracking / abuse monitoring).
response_format	object		{ "type": "json_object" } to enforce valid JSON output.
tools	array		Tool declaration (function calling).
tool_choice	stringobject		Tool selection: auto, none, or a specific tool.

API Response

Main response object

Field	Type	Description
id	string	Unique request identifier (debug / logs).
object	string	Returned object type ("response").
created	int (timestamp)	UNIX timestamp (in seconds).
model	string	Model actually used.
output	array	List of generated outputs (messages, tool calls, etc.).
usage	object	Token usage details.

Details of the output field

Each element in output represents an action or message generated by the model.

Field	Type	Description
type	string	Output type (message, tool_call, …).
role	string	Associated role (assistant, tool).
content	array	Structured content (text, JSON, etc.).

Typical message example

{
"type": "message",
"role": "assistant",
"content": [
  { "type": "output_text", "text": "An API is..." }
]
}

finish_reason values (conceptual)

In /responses, the finish reason may appear in internal fields depending on the provider.

Value	Meaning
stop	Response completed naturally.
length	max_output_tokens limit reached.
content_filter	Stopped by a safety / moderation filter.
tool_calls	Tool call triggered.
null	Streaming in progress or internal error.

Details of the usage field

Field	Type	Description
input_tokens	int	Tokens used for input.
output_tokens	int	Tokens generated in the response.
total_tokens	int	Sum of both.

Details of the message sub-object (in output)

Field	Type	Description
role	string	system, user, assistant, tool.
content	array	Structured content: input_text, output_text, etc.

What is the role field used for?

Value	Who is speaking?	Typical usage	Example
system	Assistant framework	Context, rules, tone	"You are a Clovis assistant..."
user	End user	Question / instruction	"Explain what an API is."
assistant	The model	Generated response	"An API is..."
tool	External tool	Tool call result	{ "results": [...] }

Quick summary

{
"id": "string",
"object": "response",
"created": 1700000000,
"model": "ClovisLLM",
"output": [
  {
    "type": "message",
    "role": "assistant",
    "content": [
      { "type": "output_text", "text": "…" }
    ]
  }
],
"usage": {
  "input_tokens": 123,
  "output_tokens": 456,
  "total_tokens": 579
}
}

---

Usage examples

cURL

curl https://llm-gateway.clovis-ai.fr/v1/responses   -H "Content-Type: application/json"   -H "Authorization: Bearer sk-xxxxxxxx"   -d '{
    "model": "ClovisLLM",
    "input": [
      {
        "role": "system",
        "content": [{ "type": "input_text", "text": "You are a helpful assistant." }]
      },
      {
        "role": "user",
        "content": [{ "type": "input_text", "text": "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.responses.create(
model="ClovisLLM",
input=[
  {
    "role": "system",
    "content": [{"type": "input_text", "text": "You are a helpful assistant."}]
  },
  {
    "role": "user",
    "content": [{"type": "input_text", "text": "Explain what an API is."}]
  }
]
)

print(response.output_text)

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.responses.create({
model: "ClovisLLM",
input: [
  {
    role: "system",
    content: [{ type: "input_text", text: "You are a helpful assistant." }],
  },
  {
    role: "user",
    content: [{ type: "input_text", text: "Explain what an API is." }],
  },
],
});

console.log(response.output_text);