Rechercher la documentation ...Rechercher

CtrlK

Chat Completions API

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

📑 Table des matières

Vue d'ensemble
Authentification
Paramètres de la requête
Exemples d'utilisation
Streaming
RAG & Sources
Tools Calls
Gestion des erreurs
Paramètres avancés

Vue d'ensemble

L'endpoint /v1/chat/completions est compatible avec l'API OpenAI tout en offrant des fonctionnalités avancées :

Completions - devana.ai/docs

Authorization: Bearer VOTRE_TOKEN

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.
`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.

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

[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;
  }];
  usage: {
    prompt_tokens: number;     // Tokens dans le prompt
    completion_tokens: number; // Tokens dans la completion
    total_tokens: number;      // Total des tokens utilisés
  };
}

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

{
  error: string; // Message d'erreur détaillé
}

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": "assistant",
        "content": "La capitale de la France est Paris.",
        "tool_calls": null,
        "score": {
          "value": 0.95
        }
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 8,
    "total_tokens": 17
  }
}

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

Chat Completions API

📑 Table des matières

Vue d'ensemble

Chat Completions API

📑 Table des matières

Vue d'ensemble

Authentification

Effectuer des requêtes

Endpoint

Corps de la Requête

Vérifications et limites

Tool Calls

Headers envoyés aux outils

Support de confirmation des tool calls

Objet Message

Exemple de Requête

Réponses

Réponse Standard

Réponse en Streaming

Gestion des Erreurs

Format de Réponse d'Erreur

Limitation de Débit

Fonctionnalités Spéciales

Contexte de Conversation

Support des Fichiers

Configuration Agent/Modèle

Surveillance et Analytique

Particularités

Paramètre asyncRagScore

Exemples d'Utilisation

Conversation Simple

Requête

Réponse

Conversation avec Historique

Requête

Utilisation du Streaming

Requête

Réponse (flux d'événements)

Conversation avec Fichiers

Requête

Utilisation d'un Agent Personnalisé avec Debug et Identité

Requête

Confirmation d'Exécution d'Outil

Requête

Gestion d'Erreur et Retry

Exemple de Réponse d'Erreur

Conseils d'Utilisation Avancés