Documentation de l'endpoint /v1/chat/completions pour générer des réponses avec vos agents IA.
Endpoint : POST https://api.devana.ai/v1/chat/completions
Compatible : OpenAI Chat Completions API + extensions Devana.ai
L'endpoint /v1/chat/completions est compatible avec l'API OpenAI tout en offrant des fonctionnalités avancées :
Fonctionnalités principales :
Incluez votre clé API dans le header Authorization :
Authorization: Bearer VOTRE_TOKEN
Le système :
POST /v1/chat/completions
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
model | string | Oui | Un ID d'agent créé dans le système. |
messages | array | Oui | Tableau des messages composant la conversation (maximum 4 messages). |
temperature | float | Non | Contrôle l'aléatoire dans les réponses. Valeurs entre 0 et 1. Défaut: 0.8 ou valeur configurée pour l'agent. |
max_tokens | integer | Non | Nombre maximum de tokens à générer. |
top_p | float | Non | Contrôle la diversité via l'échantillonnage nucleus. |
n | integer | Non | Nombre de completions à générer. |
stop | string/array | Non | Séquences où l'API arrêtera la génération. |
stopSequences | array | Non | Séquences additionnelles où l'API arrêtera la génération. |
frequency_penalty | float | Non | Pénalité de fréquence pour réduire la répétition. |
presence_penalty | float | Non | Pénalité de présence pour encourager la nouveauté. |
stream | boolean | Non | Si vrai, les deltas de messages partiels seront envoyés. |
Le système effectue automatiquement plusieurs vérifications :
Les outils ajoutés via l'interface par l'utilisateur sont appelés automatiquement.
{
"x-user-id": string; // ID de l'utilisateur actuel Devana (si disponible)
"x-agent-id": string; // ID de l'agent actuel utilisé pour la réponse
// Autres headers personnalisés ajoutés lors de la requête
}
Le système prend en charge la confirmation d'exécution d'outils via un format spécial :
[tool:confirm:{"messageId":"ID_MESSAGE","confirm":true|false}]
{
role: "user" | "system" | "assistant",
content: string
}
curl -X POST https://api.devana.ai/v1/chat/completions \
-H "Authorization: Bearer VOTRE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "agent_id",
"messages": [
{"role": "user", "content": "Bonjour!"}
],
"temperature": 0.7,
"stream": false
}'
{
id: string; // ID du message
object: "chat.completion"; // Type d'objet
created: number; // Timestamp
model: string; // ID du modèle utilisé
conversation_id: string; // ID de conversation
rag_score: number; // Score de la réponse (qualité)
debug: {
tool_calls: any[]; // Outils appelés durant la génération
sources: any[]; // Sources utilisées pour la réponse
metadata: object; // Métadonnées additionnelles
};
choices: [{
index: number;
message: {
role: "assistant";
content: string;
tool_calls: null;
score: {
value: number; // Score de la réponse
};
};
finish_reason: string | null;
logprobs: null;
}];
: {
: ;
: ;
: ;
};
}
Quand stream: true, l'API renvoie un flux d'événements server-sent. Chaque événement contient un delta de la réponse :
{
id: string;
object: "chat.completion.chunk";
created: number;
model: string;
conversation_id: string;
rag_score: number | null; // Présent uniquement dans le dernier chunk
debug: object | null; // Présent uniquement dans le dernier chunk
choices: [{
index: number;
delta: {
content: string;
};
finish_reason: null | "stop";
logprobs: null;
}];
usage: { // Mis à jour dans chaque chunk
prompt_tokens: number;
completion_tokens: number;
total_tokens: number;
};
}
Le flux se termine par un chunk avec finish_reason: "stop" suivi d'un message [DONE].
L'API utilise les codes de réponse HTTP conventionnels :
400 - Mauvaise Requête (paramètres invalides, messages manquants, etc.)403 - Interdit (accès refusé ou limite d'utilisation atteinte)404 - Non Trouvé (modèle ou conversation non trouvé)500 - Erreur Interne du ServeurLe système implémente une stratégie de retry avec backoff exponentiel pour les erreurs temporaires :
{
error: string; // Message d'erreur détaillé
}
L'API inclut une limitation de débit basée sur l'utilisateur :
conversation_idtrue, la réponse est renvoyée immédiatement sans attendre le calcul du score RAG. Le score RAG sera calculé en arrière-plan. Les réponses n'incluront plus les sources, qui seront systématiquement un tableau vide ([]).curl -X POST https://api.devana.ai/v1/chat/completions \
-H "Authorization: Bearer VOTRE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "default-agent",
"messages": [
{
"role": "user",
"content": "Quelle est la capitale de la France?"
}
],
"temperature": 0.7
}'
{
"id": "msg_123abc",
"object": "chat.completion",
"created": 1698152365,
"model": "default-agent",
"conversation_id": "conv_456def",
"rag_score": 0.95,
"debug": {
"tool_calls": null,
"sources": null,
"metadata": null
},
"choices": [
{
"index": 0,
"message": {
"role"
curl -X POST https://api.devana.ai/v1/chat/completions \
-H "Authorization: Bearer VOTRE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "default-agent",
"conversation_id": "conv_456def",
"messages": [
{
"role": "user",
"content": "Et combien d'habitants y vivent?"
}
]
}'
curl -X POST https://api.devana.ai/v1/chat/completions \
-H "Authorization: Bearer VOTRE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "default-agent",
"messages": [
{
"role": "user",
"content": "Raconte moi une histoire"
}
],
"stream": true
}'
data: {"id":"msg_789ghi","object":"chat.completion.chunk","created":1698152366,"model":"default-agent","conversation_id":"conv_456def","choices":[{"index":0,"delta":{"content":"Il"},"finish_reason":null,"logprobs":null}],"usage":{"prompt_tokens":5,"completion_tokens":1,"total_tokens":6}}
data: {"id":"msg_789ghi","object":"chat.completion.chunk","created":1698152366,"model":"default-agent","conversation_id":"conv_456def","choices":[{"index":0,"delta":{"content":" était"},"finish_reason":null,"logprobs":null}],"usage":{"prompt_tokens":5,"completion_tokens":2,"total_tokens":7}}
data: {"id":"msg_789ghi","object":"chat.completion.chunk","created":1698152366,"model":"default-agent","conversation_id":"conv_456def","choices":[{"index":0,"delta":{"content":" une"},"finish_reason":null,"logprobs":null}],"usage":{"prompt_tokens":5,"completion_tokens":3,"total_tokens":8}}
...
data: {"id":"msg_789ghi","object":"chat.completion.chunk","created":1698152366,"model":"default-agent","conversation_id":"conv_456def","rag_score":0.87,"debug":{"tool_calls":[],"sources":null,"metadata":{}},"choices":[{"index":0,"delta":{"content":""},"finish_reason":"stop","logprobs":null}],"usage":{"prompt_tokens":5,"completion_tokens":150,"total_tokens":155}}
data: [DONE]
curl -X POST https://api.devana.ai/v1/chat/completions \
-H "Authorization: Bearer VOTRE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "default-agent",
"messages": [
{
"role": "user",
"content": "Analyse ce document"
}
],
"files": ["file_123abc"],
"temperature": 0.3
}'
curl -X POST https://api.devana.ai/v1/chat/completions \
-H "Authorization: Bearer VOTRE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "agent-specialise-juridique",
"messages": [
{
"role": "user",
"content": "Explique moi le concept de force majeure"
}
],
"lang": "fr",
"custom": {
"disableAutomaticIdentity": true
},
"identity": {
"name": "Conseiller Juridique",
"expertise": "Droit Civil"
},
"metadata": {
"sessionContext": "consultation",
"clientSector": "Assurance"
}
}'
curl -X POST https://api.devana.ai/v1/chat/completions \
-H "Authorization: Bearer VOTRE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "default-agent",
"conversation_id": "conv_456def",
"messages": [
{
"role": "user",
"content": "[tool:confirm:{\"messageId\":\"msg_123abc\",\"confirm\":true}]"
}
]
}'
{
"error": "Limit reached"
}
Gestion des Tokens
max_tokens selon vos besoins spécifiquesOptimisation des Réponses
frequency_penalty et presence_penalty pour contrôler la répétitionPerformance et Stabilité
Gestion du Contexte
conversation_id pour maintenir le contexte entre les sessionsDebugging
conversation_id | string | Non | ID de la conversation existante à continuer. |
response_format | string | Non | Format de réponse souhaité (par exemple, { type: "text" | "json_object"}). (compatible selon le LLM actif) |
lang | string | Non | Langue pour la réponse. Par défaut, locale de l'utilisateur ou 'fr'. |
files | array | Non | Tableau des IDs de fichiers à inclure dans le contexte. |
clientModel | string | Non | Modèle spécifique à utiliser avec la configuration Devana AI. Défaut: valeur de DEFAULT_MODEL. |
custom | object | Non | Options de configuration personnalisées, comme disableAutomaticIdentity. |
metadata | object | Non | Metadata pour les dashboards et logging via webhooks (Si configurés). |
headers | object | Non | Headers complémentaires pour l'authentification des tools calls. |
identity | object | Non | Informations d'identité de l'utilisateur pour personnaliser le comportement de l'agent. |
asyncRagScore | boolean | Non | Si vrai, on n'attend pas le calcul du score RAG. |
attachementsFastMode | boolean | Non | Si vrai, nous ignorons la vision sur les attachements |
hiddenMode | boolean | Non | Si vrai, la conversation ne sera pas visible dans l'interface utilisateur Devana. |