L'endpoint /v1/chat/completions

Votre porte d’entrée vers les modèles Mistral

Tout ce que vous ferez avec l’API Mistral passera par un seul chemin : /v1/chat/completions. C’est le point central de la plateforme, celui par lequel transitent toutes vos interactions conversationnelles avec les modèles de langage. Un chatbot d’assistance interne, un extracteur qui transforme des factures PDF en lignes de base de données, un assistant de rédaction intégré à votre CMS : ces trois applications, en apparence très différentes, appellent exactement le même endpoint avec des messages et des paramètres différents. Vous n’avez donc pas trois intégrations à apprendre, mais une seule à bien maîtriser.

En avril 2026, cet endpoint gère des milliards de requêtes quotidiennes à travers le monde. Comprendre sa structure est la première étape pour exploiter la puissance des modèles Mistral en production.

L’URL de base

Toutes les requêtes vers l’API Mistral partent de la même base :

https://api.mistral.ai/v1/chat/completions

Vous envoyez une requête POST avec un corps JSON contenant vos messages et paramètres, et l’API vous renvoie une réponse JSON structurée. Aucune session à ouvrir, aucun état à maintenir côté serveur : chaque appel est autonome.

Anatomie d’une requête

La manière la plus rapide de vérifier que votre clé fonctionne est d’envoyer une requête minimale avec curl, directement depuis votre terminal :

curl https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "model": "mistral-large-latest",
    "messages": [
      {"role": "user", "content": "Bonjour, comment fonctionne votre API ?"}
    ]
  }'

Deux headers sont obligatoires : Content-Type: application/json décrit le format du corps de la requête, et Authorization: Bearer <votre-clé> porte votre authentification. Le corps, lui, contient au minimum deux champs — model, l’identifiant du modèle à utiliser, et messages, le tableau qui porte la conversation.

Équivalent Python avec le SDK

Passé la phase de test, personne n’écrit du curl en production. Le SDK officiel fait le même appel en quelques lignes :

from mistralai import Mistral
import os

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

response = client.chat.complete(
    model="mistral-large-latest",
    messages=[
        {"role": "user", "content": "Bonjour, comment fonctionne votre API ?"}
    ]
)

print(response.choices[0].message.content)

Le SDK gère pour vous les headers, la sérialisation JSON et le parsing de la réponse. Il gère également les retries automatiques en cas d’erreur temporaire — ce qui vous évite d’écrire vous-même la logique de reprise quand un pic de trafic provoque une erreur passagère.

Structure de la réponse

Quelle que soit la manière dont vous appelez l’API, elle renvoie toujours le même objet JSON :

{
  "id": "cmpl-abc123",
  "object": "chat.completion",
  "created": 1712150400,
  "model": "mistral-large-latest",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Bonjour ! L'API Mistral fonctionne..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 87,
    "total_tokens": 102
  }
}

Trois champs méritent votre attention dès maintenant. choices est un tableau contenant la ou les réponses générées : c’est là que se trouve le texte que vous afficherez à l’utilisateur. usage donne le décompte de tokens en entrée, en sortie et au total, ce qui vous permet de suivre le coût réel de chaque fonctionnalité plutôt que de découvrir la facture en fin de mois. Enfin, finish_reason explique pourquoi le modèle s’est arrêté — stop pour une fin naturelle, length quand la limite de tokens a coupé la réponse, tool_calls quand le modèle réclame l’exécution d’un outil. Un résumé qui se termine au milieu d’une phrase n’est presque jamais un problème de modèle : c’est un finish_reason à length que personne n’a lu.

Codes d’erreur courants

Quand quelque chose ne va pas, l’API renvoie des codes HTTP standards :

• 400 — Requête mal formée (JSON invalide, paramètre manquant)
• 401 — Clé API invalide ou manquante
• 429 — Limite de débit atteinte (trop de requêtes)
• 500 — Erreur côté serveur (retentez après quelques secondes)

En Python, le SDK lève des exceptions typées que vous pouvez intercepter, ce qui vous permet de distinguer une clé expirée d’une saturation temporaire et de réagir différemment dans chaque cas :

from mistralai import Mistral
from mistralai.models import SDKError

client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))

try:
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": "Test"}]
    )
except SDKError as e:
    print(f"Erreur API : {e.status_code} — {e.message}")

Prenez l’habitude, dès votre premier script, d’entourer chaque appel de ce bloc : le jour où votre application tournera sans surveillance, elle vous dira ce qui a échoué au lieu de s’arrêter en silence.

Points clés à retenir

• L’endpoint /v1/chat/completions est le seul nécessaire pour les interactions conversationnelles
• Chaque requête nécessite un model et un tableau de messages
• La réponse contient toujours choices, usage et finish_reason
• Le SDK Python simplifie considérablement les appels par rapport à curl
• Les tokens d’usage permettent de calculer précisément vos coûts