Référence API

import { Tabs, TabItem } from “@astrojs/starlight/components”;

Paramètres de complétion

Endpoint : POST https://api.miraca.fr/v1/chat/completions

Paramètre	Type	Défaut	Description
model	string	—	mistral-small (défaut) — voir Modèles & tarifs
messages	array	—	Tableau [{role, content}] — rôles : system, user, assistant. Le content peut être une chaîne ou un tableau de parties (texte + fichiers joints — voir Fichiers dans le chat)
max_tokens	integer	—	Recommandé ≥ 300. Tokens alloués à la réponse (raisonnement inclus)
temperature	float	0.7	0 = déterministe, 1 = créatif
top_p	float	1.0	Nucleus sampling (alternative à temperature)
stream	boolean	false	Réponse en streaming SSE
response_format	object	—	Voir Sortie structurée
stop	string/array	—	Séquences d’arrêt
reasoning_effort	string	—	none, low, medium, high — combien le modèle réfléchit avant de répondre. Les niveaux acceptés dépendent du modèle (reasoning_efforts dans /v1/pricing) ; sur un modèle qui n’en propose pas, ou pour un niveau inconnu, la réponse est un 400 explicite

Tool calling

Les modèles mistral-* supportent le tool calling (tools / tool_choice). Pour contraindre la réponse à un format précis, voir aussi la sortie structurée (json_schema).

Date courante

Un modèle de langage n’a pas d’horloge : sans information il situe « aujourd’hui » à sa date de fin d’entraînement. La plateforme ajoute donc automatiquement, en tête de chaque requête, un court message system indiquant la date et l’heure courantes (fuseau Europe/Paris). Le modèle dispose ainsi d’une référence temporelle fiable (échéances, calculs de dates, « le mois dernier »…). Vos propres messages system sont conservés tels quels.

---

Taille de contexte

262 144 tokens (entrée + sortie cumulés) — capacité de mistral-small (Mistral Small 4).

Repère	Tokens approximatifs
1 mot français	~1,3 token
1 page A4 (~400 mots)	~520 tokens
262 144 tokens	~200 000 mots / ~640 pages

---

Structure de réponse

mistral-small (Mistral Small 4) est un modèle avec raisonnement interne. La réponse inclut deux champs :

{
  "id": "chatcmpl-…",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "La réponse finale à utiliser.",
      "reasoning_content": "…réflexion interne du modèle (null si le modèle n'a pas raisonné)…"
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 318,
    "total_tokens": 360
  }
}

• content — la réponse finale, directement exploitable.
• reasoning_content — la chaîne de pensée interne du modèle (null si le modèle n’a pas généré de raisonnement). Non-standard OpenAI — ignoré par les SDK qui ne le supportent pas.

Sortie structurée (json_schema / json_object)

Quand response_format est actif, le raisonnement interne est désactivé : le modèle génère directement le JSON contraint, sans phase de réflexion préalable. reasoning_content est toujours null dans ce cas.

---

Raisonnement

mistral-small est un modèle avec raisonnement interne (chain-of-thought) : il réfléchit avant de formuler sa réponse sur les tâches complexes. Quand ce raisonnement a lieu, il est exposé dans le champ reasoning_content du message.

Quand le raisonnement est visible

Mode	reasoning_content	content
Chat libre (sans response_format)	Présent si le modèle a raisonné, null sinon	Réponse finale
json_object ou json_schema	Toujours null (raisonnement désactivé)	JSON contraint

Par défaut, le modèle décide lui-même s’il a besoin de raisonner : les tâches simples (reformulation, réponse directe) n’en déclenchent pas toujours.

Le régler explicitement

Le paramètre reasoning_effort prend la main sur cette décision :

{ "model": "mistral-medium", "reasoning_effort": "none", "messages": [...] }

Les niveaux acceptés dépendent du modèle et sont donnés par reasoning_efforts dans /v1/pricing : none et high sur mistral-small et mistral-medium ; les quatre niveaux sur qwen-small, qwen-large et gemma ; low, medium et high sur gpt-oss. Les autres modèles n’ont pas de réglage, et leur envoyer le paramètre vaut une erreur explicite plutôt qu’un silence.

L’écart n’est pas anecdotique : sur mistral-medium, la même question produit 601 tokens de sortie en none contre 3 000 en high. Sur une automatisation répétée, c’est la différence entre payer une réflexion utile et la payer pour rien.

Impact sur max_tokens

Les tokens de raisonnement sont comptabilisés dans completion_tokens. Avec max_tokens trop bas, le quota peut être épuisé avant la réponse finale → content vide ou tronqué.

Règle pratique :

• Sortie structurée (json_schema / json_object) : max_tokens ≥ 200 suffit (pas de raisonnement)
• Chat court (classification, extraction) : max_tokens ≥ 300
• Chat long (rédaction, analyse) : max_tokens 1000–2000

---

Streaming

Avec stream: true, la réponse arrive en Server-Sent Events (même format qu’OpenAI). Les chunks de raisonnement arrivent dans delta.reasoning_content, les chunks de réponse finale dans delta.content.

Pas de streaming en mode agent

Le streaming n’est pas disponible quand la requête active des outils (tools_enabled : bases de connaissance en mode agent, recherche web, connecteurs, exécution de code). Ces requêtes enchaînent plusieurs tours côté serveur avant de pouvoir répondre : elles renvoient donc leur résultat en une fois, avec les sources et les étapes. Une requête agentique envoyée avec stream: true est refusée par un 400 explicite plutôt que de renvoyer une réponse incomplète.

Le RAG classique (knowledge_base sans outils) se streame normalement.

stream = client.chat.completions.create(
    model="mistral-small",
    messages=[{"role": "user", "content": "Résume ce compte-rendu en 3 points."}],
    max_tokens=600,
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

n8n / Make

La plupart des nœuds OpenAI activent le streaming automatiquement. Le champ reasoning_content est non-standard et ignoré par ces nœuds — seul content est exploité dans la réponse finale.

---

Rate limits

Code HTTP	Cause	À faire
429 Too Many Requests	Trop de requêtes simultanées	Attendre et réessayer — les SDK OpenAI gèrent le retry avec backoff automatiquement
503 Service Unavailable	Backend temporairement indisponible	Réessayer après 30 s
401 Unauthorized	Clé invalide ou budget épuisé	Vérifier la clé dans le portail / recharger les crédits
400 Bad Request	Paramètre invalide, contexte dépassé, ou règle de conformité violée	Vérifier max_tokens + taille du prompt ; lire le message d’erreur (les refus de conformité y sont explicites)

Limite de concurrence actuelle : ~28 requêtes simultanées (Phase 1, infrastructure DEV1-L). Au-delà, vous recevez un 429 propre — votre client SDK retente automatiquement. Pour une capacité supérieure, contactez-nous.