L'endpoint /v1/chat/completions
In questa pagina
Mise à jour du 2 novembre 2026 — Modèles. Mistral Large 3 (
mistral-large-2512) et Mistral Medium 3.5 ont été dépréciés le 31 octobre 2026 et seront retirés le 30 avril 2027. Leur successeur désigné, Mistral Large 4 (mistral-large-4), est en aperçu public depuis le 6 octobre. Les exemples de ce cours utilisent l’aliasmistral-large-latest, qui pointe actuellement vers Mistral Large 3 selon sa spécification officielle (vérifié le 3 novembre 2026). De même,mistral-medium-latestpointe vers Mistral Medium 3.5. Ces alias resteront valides jusqu’au 30 avril 2027. Pour les nouveaux projets, testemistral-large-4, leur successeur désigné.
Ta passerelle vers les modèles Mistral
Tout ce que tu fais avec l’API Mistral passe par un seul chemin : /v1/chat/completions. C’est le hub central de la plateforme, gérant toutes tes interactions conversationnelles avec les modèles de langage. Que tu construises un chatbot de support interne, un extracteur qui transforme des factures PDF en lignes de base de données, ou un assistant d’écriture intégré à ton CMS, ces trois applications apparemment différentes appellent exactement le même endpoint avec des messages et des paramètres différents. Tu n’as pas besoin d’apprendre trois intégrations séparées ; tu dois seulement en maîtriser une.
Depuis avril 2026, cet endpoint traite des milliards de requêtes quotidiennes dans le monde entier. Comprendre sa structure est la première étape pour exploiter les 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
Tu envoies une requête POST avec un corps JSON contenant tes messages et tes paramètres, et l’API renvoie une réponse JSON structurée. Il n’y a aucune session à ouvrir ni aucun état côté serveur à maintenir : chaque appel est autonome.
Anatomie d’une requête
Le moyen le plus rapide de vérifier que ta clé fonctionne est d’envoyer une requête minimale en utilisant curl directement depuis ton 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": "Hello, how does your API work?"}
]
}'
Deux en-têtes sont obligatoires : Content-Type: application/json décrit le format du corps de la requête, et Authorization: Bearer <ta-clé> transmet ton authentification. Le corps lui-même doit contenir au moins deux champs : model, l’identifiant du modèle à utiliser, et messages, le tableau portant la conversation.
Équivalent Python avec le SDK
Une fois la phase de test passée, personne n’écrit de commandes curl brutes en production. Le SDK officiel effectue le même appel en quelques lignes seulement :
from mistralai.client 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": "Hello, how does your API work?"}
]
)
print(response.choices[0].message.content)
Le SDK gère pour toi les en-têtes, la sérialisation JSON et l’analyse de la réponse. Il gère également les nouvelles tentatives automatiques pour les erreurs temporaires, t’évitant d’écrire ta propre logique de retry lorsqu’un pic de trafic provoque une défaillance transitoire.
Structure de la réponse
Peu importe comment tu appelles 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": "Hello! The Mistral API works..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 15,
"completion_tokens": 87,
"total_tokens": 102
}
}
Trois champs méritent ton attention immédiate. choices est un tableau contenant la ou les réponses générées ; c’est là que tu trouves le texte à afficher à l’utilisateur. usage fournit le nombre de tokens pour l’entrée, la sortie et le total, te permettant de suivre le coût réel de chaque fonctionnalité plutôt que de découvrir la facture à la fin du mois. Enfin, finish_reason explique pourquoi le modèle s’est arrêté : stop pour une fin naturelle, length lorsque la limite de tokens a coupé la réponse, ou tool_calls lorsque le modèle demande l’exécution d’un outil. Un résumé qui s’arrête au milieu d’une phrase n’est presque jamais un problème de modèle ; c’est un finish_reason de type length que personne n’a lu.
Codes d’erreur courants
Lorsque 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 serveur (réessaie après quelques secondes)
En Python, le SDK lève des exceptions typées que tu peux attraper, te permettant de distinguer une clé expirée d’une saturation temporaire, et de réagir différemment dans chaque cas :
from mistralai.client import Mistral
from mistralai.client.errors 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"API Error: {e.status_code} — {e.message}")
Prends l’habitude d’envelopper chaque appel dans ce bloc dès ton tout premier script. Le jour où ton application s’exécutera sans surveillance, elle te dira ce qui a échoué au lieu de s’arrêter silencieusement.
Punti chiave
- L’endpoint
/v1/chat/completionsest le seul nécessaire pour les interactions conversationnelles - Chaque requête nécessite un
modelet un tableaumessages - La réponse contient toujours
choices,usageetfinish_reason - Le SDK Python simplifie considérablement les appels par rapport à
curl - Les tokens d’utilisation te permettent de calculer tes coûts avec précision