L'intégration de l'API Mistral est courte : une URL de base, une clé et un nom de modèle suffisent pour le premier appel. Ce qui bloque vraiment n'est généralement pas le code, mais trois détails : l'adresse est-elle complète, le nom de modèle correspond-il à la version actuelle, la clé et le point d'entrée forment-ils bien une paire.
Cet article part de l'entrée officielle https://api.mistral.ai/v1, réalise successivement un premier appel en curl puis en Python, puis couvre le streaming, le mode JSON, les appels d'outils, les erreurs courantes et la liste de vérification pour migrer de la connexion directe officielle vers ZSQH AI Gateway.
Note : Mistral, Mistral AI et les noms de modèles associés sont des marques de Mistral AI. Cet article n'a aucune affiliation avec Mistral AI ; modèles, paramètres et quotas peuvent évoluer selon les versions. La documentation officielle et la page tarifs des modèles font foi.
1. Trois vérifications avant l'intégration
Premièrement, l'origine de la clé. Une clé officielle se crée sur https://console.mistral.ai et ne fonctionne qu'avec l'entrée officielle ; une clé de passerelle se crée dans la console ZSQH et ne fonctionne qu'avec l'entrée de la passerelle.
Deuxièmement, l'URL de base. L'entrée officielle est https://api.mistral.ai/v1 ; le chemin complet de la complétion de chat est https://api.mistral.ai/v1/chat/completions.
Troisièmement, le nom de modèle. Mistral propose à la fois des alias -latest et des noms de version fixe datés, qui n'ont pas le même sens. L'alias suit la version par défaut choisie par l'officiel ; une version fixe convient mieux aux tests de régression en production.
Une fois ces trois points confirmés, écrivez le code. Dans l'ordre inverse, on oscille vite entre 401 et 404.
2. URL de base et chemin de requête
L'adresse de base officielle de l'API est :
https://api.mistral.ai/v1
La complétion de chat utilise POST /v1/chat/completions. Deux en-têtes sont nécessaires :
Authorization: Bearer <MISTRAL_API_KEY>
Content-Type: application/json
Avec le SDK Python officiel, il suffit généralement de passer api_key ; le SDK assemble l'adresse. Avec le SDK OpenAI, réglez base_url sur https://api.mistral.ai/v1 ; le SDK ajoute ensuite /chat/completions.
L'erreur la plus fréquente ici est la double concaténation : base_url contient déjà /v1, le chemin de requête ajoute encore /v1/chat/completions, ce qui donne /v1/v1/chat/completions et un 404. Autre erreur courante : mélanger l'adresse officielle et celle de la passerelle, ce qui se manifeste par un 401.
L'entrée compatible OpenAI de ZSQH AI Gateway est https://ai.zhongshangqihang.com/v1, avec la même règle de chemin. Lors de la bascule, ne changez que base_url et api_key, sans les croiser.
3. Nom de modèle : alias ou version fixe
À octobre 2026, le démarrage rapide officiel utilise mistral-large-latest, et la documentation des appels de fonctions liste aussi mistral-medium-latest, mistral-small-latest et d'autres alias. La page de présentation des modèles donne des noms de version fixe, notamment mistral-large-4 (aperçu public), mistral-large-2512, mistral-medium-3-5, mistral-small-2603, ainsi que des modèles spécialisés comme ministral-14b-2512 et codestral-2508.
La différence entre les deux familles :
- un alias
-latestpointe vers la version par défaut actuelle de l'officiel ; il convient à la validation rapide et aux usages non critiques, mais son comportement peut changer avec la version par défaut ; - un nom de version fixe, daté ou numéroté par génération, pointe vers une version explicite ; il convient à la production pour verrouiller le comportement, comparer les versions et revenir en arrière.
Les pages officielles ne se mettent pas toutes à jour au même rythme ; la version exacte derrière un alias est celle que renvoient la console ou la liste des modèles au moment de l'appel. Avant l'intégration, utilisez client.models.list() du SDK ou la console pour confirmer les modèles disponibles, sans recopier un nom tiré d'un ancien article.
Avec ZSQH AI Gateway, le nom de modèle suit la page tarifs des modèles. La passerelle peut mapper les noms amont : reprendre tel quel un nom officiel ne signifie pas qu'il fonctionne.
4. Premier curl : valider la requête minimale
Définissez d'abord les variables d'environnement, puis envoyez la requête la plus courte. Mettez un max_tokens faible pour réduire l'attente et le bruit.
export MISTRAL_API_KEY="votre-clé"
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": "Réponds seulement OK"}
],
"max_tokens": 32
}'
Un retour 200 avec du contenu dans choices[0].message.content signifie que clé, URL de base et nom de modèle sont corrects. Un 401 invite à vérifier la clé et l'en-tête ; un 404, le chemin et le nom de modèle ; un 402, l'état de facturation.
5. Appel Python : SDK Mistral et SDK OpenAI
Le paquet du SDK Python officiel s'appelle mistralai :
pip install mistralai
Exemple d'appel minimal :
import os
from mistralai.client import Mistral
with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Tu es un assistant technique francophone, réponds de façon concise."},
{"role": "user", "content": "Explique en trois phrases ce qu'est une base de données vectorielle."},
],
max_tokens=256,
)
print(response.choices[0].message.content)
print(response.usage)
Attention au chemin d'import : la documentation actuelle du SDK utilise from mistralai.client import Mistral, certaines anciennes versions from mistralai import Mistral. Ne mélangez pas les deux ; en cas de ModuleNotFoundError, vérifiez la version installée et les notes de migration officielles.
Pour réutiliser du code existant basé sur le SDK OpenAI, pointez base_url vers https://api.mistral.ai/v1 et remplacez api_key par une clé Mistral. La forme des requêtes Mistral est proche d'OpenAI Chat Completions, et cet usage est courant dans la communauté ; toutefois la documentation officielle ne présente pas l'API Mistral comme un « produit compatible OpenAI », et la prise en charge des paramètres, la structure d'erreur et les champs d'extension restent celles de la référence officielle. Validez chaque point avec de vraies requêtes avant la production, sans supposer que tous les paramètres OpenAI fonctionnent.
6. Streaming
Une interface de chat a généralement besoin d'un retour token par token. Le SDK Mistral utilise client.chat.stream(...), qui renvoie un flux d'événements ; l'incrément de texte se trouve dans chunk.data.choices[0].delta.content :
with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
stream = client.chat.stream(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Écris un exemple Python de lecture d'un CSV"}],
)
for chunk in stream:
delta = chunk.data.choices[0].delta.content
if delta:
print(delta, end="", flush=True)
La réponse en streaming utilise des SSE data-only et se termine par data: [DONE]. Côté ingénierie, gérez trois choses : les incréments vides, la déconnexion du client et le retry sur timeout. N'écrivez pas en base à chaque incrément : concaténez le texte complet, puis enregistrez à la fin.
7. Mode JSON, sortie structurée et appels d'outils
Mode JSON : utilisez response_format={"type": "json_object"}. La documentation officielle indique que tous les modèles actuels sauf codestral-mamba le prennent en charge. Une fois activé, la sortie est contrainte à du JSON valide, mais content reste une chaîne JSON qu'il faut passer à json.loads(). Le prompt doit demander explicitement un « objet JSON » et les champs attendus ; ne dépendez pas du seul paramètre.
Sortie structurée : adaptée aux champs fixes. Le SDK officiel propose client.chat.parse(...), qui accepte un modèle Pydantic et renvoie un objet analysé ; avec un JSON Schema brut, réglez strict: true et additionalProperties: false sur l'objet. Plus les champs sont stricts, moins le modèle a de liberté et plus la validation ultérieure est simple.
Appels d'outils : utilisez le tableau tools ; tool_choice accepte auto, any ou none, et parallel_tool_calls contrôle le parallélisme. Le modèle ne fait que renvoyer le nom d'outil et les paramètres ; c'est votre backend qui exécute la fonction. Après réception des tool_calls, réinsérez le message assistant tel quel dans la liste, ajoutez un message tool avec le tool_call_id, puis rappelez le modèle jusqu'à la réponse finale. Les appels d'outils multi-tours doivent boucler, pas s'arrêter au premier tour.
8. Erreurs courantes et diagnostic
| Erreur | Cause fréquente | Traitement |
|---|---|---|
| 400 | Corps de requête JSON invalide, model ou messages manquant |
Valider d'abord le corps minimal avec curl |
| 401 | Clé absente, erronée, expirée ou incompatible avec l'entrée | Vérifier l'en-tête Bearer et l'origine de la clé |
| 402 | Problème de facturation : solde, plafond, échec de paiement | Vérifier facturation et quota dans la console |
| 403 | Le compte ou l'espace de travail n'a pas les droits sur ce modèle | Vérifier Workspace, permissions et forfait |
| 404 | Chemin erroné, ou modèle/ressource inexistant | Confirmer /v1/chat/completions et le nom de modèle |
| 422 | JSON valide mais valeur de paramètre invalide | Vérifier types, valeurs d'énumération et longueurs de tableau |
| 429 | Limite de débit, de tokens ou de concurrence dépassée | Backoff exponentiel, lire Retry-After |
| 500/503 | Anomalie serveur ou surcharge temporaire | Attendre brièvement puis réessayer ; consulter la page d'état si cela persiste |
Ne contournez pas un 429 en créant « plusieurs clés ». L'officiel compte les quotas par compte, Workspace ou forfait ; plusieurs clés partagent souvent la même limite. La bonne approche : réduire la concurrence, faire un backoff exponentiel, décaler les lots, puis envisager un forfait supérieur si nécessaire.
9. Liste de migration de l'officiel vers la passerelle
- Créer un compte sur ZSQH AI Gateway, générer une clé de passerelle et la conserver séparément de la clé officielle.
- Remplacer
base_urlparhttps://ai.zhongshangqihang.com/v1et changerapi_keyen même temps. - Reconfirmer les noms de modèles sur la page tarifs des modèles, sans reprendre directement les noms officiels.
- Conserver le corps de requête d'origine, retirer d'abord les paramètres d'extension non pris en charge, puis les rajouter un par un.
- Comparer sorties, durées et
usagesur le même lot de prompts réels, pendant trois à sept jours. - Garder la connexion directe officielle comme canal de secours et préparer un interrupteur de retour arrière.
- Surveiller 401, 429, 5xx et timeouts ; en cas d'anomalie, basculer d'abord, diagnostiquer ensuite.
Une migration n'est pas qu'un changement d'adresse. Mapping des modèles, prise en charge des paramètres, comportement du streaming et base de facturation peuvent différer : validez d'abord sur un faible trafic, puis basculez la production.
Questions fréquentes
L'URL de base doit-elle inclure /v1 ?
Oui pour l'entrée officielle : https://api.mistral.ai/v1. Le chemin complet de la complétion de chat est https://api.mistral.ai/v1/chat/completions. Avec le SDK OpenAI, écrivez base_url jusqu'à /v1 ; le SDK ajoute lui-même /chat/completions, ne le réécrivez pas.
Alias -latest ou version fixe ?
Pour une validation rapide, un alias comme mistral-large-latest évite de chercher le numéro de version. En production, préférez un nom de version fixe, daté ou numéroté : le comportement est reproductible et le retour arrière plus simple. Dans les deux cas, vérifiez la disponibilité actuelle dans la documentation ou la console avant la mise en ligne.
Peut-on utiliser directement le SDK OpenAI avec l'API Mistral ?
La forme des requêtes est proche : pointer base_url vers https://api.mistral.ai/v1 et utiliser une clé Mistral fonctionne généralement. Mais l'officiel ne présente pas son API comme un produit compatible OpenAI ; certains paramètres et structures d'erreur peuvent différer. Validez d'abord avec une requête minimale, puis vérifiez un par un les paramètres d'extension utilisés dans le projet.
Pourquoi le mode JSON ne renvoie-t-il pas un objet ?
Le mode JSON contraint la sortie à un JSON valide, mais content est une chaîne qu'il faut analyser. Faites json.loads(), puis validez le schéma ; un prompt demandant explicitement le JSON et la structure des champs réduit les champs vides et les dérives de format.
Une clé officielle peut-elle fonctionner avec l'adresse de la passerelle ZSQH ?
Non. La clé officielle correspond à https://api.mistral.ai/v1, la clé de passerelle à https://ai.zhongshangqihang.com/v1. Lors d'une migration, clé et URL de base doivent être changées ensemble ; un mélange renvoie généralement 401.
Lectures associées :
