Responses

POST/v1/responses

La route /responses est une interface unifiée et moderne permettant de gérer des entrées complexes (texte, outils) et des sorties structurées. Elle offre davantage de flexibilité pour les scénarios avancés, notamment l’agentic AI et l’appel de tools. C’est la route recommandée pour les nouveaux développements compatibles OpenAI.

Structure

Chaque requête doit inclure un JSON similaire à :

Corps de requête

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

Description des champs

Corps de requête

Champ	Type	Obligatoire	Description
model	string	✔️	Nom du modèle à utiliser.
input	stringarray	✔️	Entrée du modèle : texte direct ou historique structuré.
temperature	float		Créativité (0 = déterministe).
max_output_tokens	int		Limite maximale de tokens générés.
top_p	float		Nucleus sampling.
stream	boolean		Active le streaming de la réponse.
stop	stringarray		Token(s) d’arrêt.
presence_penalty	float		Décourage la répétition de sujets.
frequency_penalty	float		Décourage la répétition de mots.
user	string		Identifiant utilisateur (tracking / abuse monitoring).
response_format	object		{ "type": "json_object" } pour forcer une sortie JSON valide.
tools	array		Déclaration d’outils (function calling).
tool_choice	stringobject		Choix de l’outil : auto, none ou outil spécifique.

Réponse de l’API

Tableau principal de la réponse

Champ	Type	Description
id	string	Identifiant unique de la requête (debug / logs).
object	string	Type d’objet retourné ("response").
created	int (timestamp)	Timestamp UNIX (en secondes).
model	string	Modèle effectivement utilisé.
output	array	Liste des sorties générées (messages, tool calls, etc.).
usage	object	Compte des tokens utilisés.

Détail du champ output

Chaque élément de output représente une action ou un message généré par le modèle.

Champ	Type	Description
type	string	Type de sortie (message, tool_call, …).
role	string	Rôle associé (assistant, tool).
content	array	Contenu structuré (texte, JSON, etc.).

Exemple typique d’un message

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

Valeurs de finish_reason (conceptuelles)

Dans /responses, la raison de fin peut apparaître dans des champs internes selon le fournisseur.

Valeur	Signification
stop	Réponse terminée naturellement.
length	Limite max_output_tokens atteinte.
content_filter	Arrêt par un filtre de sécurité / modération.
tool_calls	Appel d’un outil.
null	Streaming en cours ou erreur interne.

Détails du champ usage

Champ	Type	Description
input_tokens	int	Tokens utilisés pour l’entrée.
output_tokens	int	Tokens générés dans la réponse.
total_tokens	int	Somme des deux précédents.

Détails du sous-objet message (dans output)

Champ	Type	Description
role	string	system, user, assistant, tool.
content	array	Contenu structuré : input_text, output_text, etc.

À quoi sert le champ role ?

Valeur	Qui parle ?	Utilisation typique	Exemple
system	Cadre de l’assistant	Contexte, règles, ton	"Tu es un assistant Clovis..."
user	Utilisateur final	Question / instruction	"Explique-moi ce qu’est une API."
assistant	Le modèle	Réponse générée	"Une API est..."
tool	Outil externe	Résultat d’un tool call	{ "results": [...] }

Résumé rapide

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

---

Exemples d’utilisation

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": "Tu es un assistant utile." }]
      },
      {
        "role": "user",
        "content": [{ "type": "input_text", "text": "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.responses.create(
model="ClovisLLM",
input=[
  {
    "role": "system",
    "content": [{"type": "input_text", "text": "Tu es un assistant utile."}]
  },
  {
    "role": "user",
    "content": [{"type": "input_text", "text": "Explique-moi ce qu’est une API."}]
  }
]
)

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: "Tu es un assistant utile." }],
  },
  {
    role: "user",
    content: [{ type: "input_text", text: "Explique-moi ce qu’est une API." }],
  },
],
});

console.log(response.output_text);