Comment Utiliser l'API Mistral Medium 3.5 ?

Mistral a lancé Medium 3.5 le 29 avril 2026. L'ID du modèle API est mistral-medium-3.5, le point de terminaison est https://api.mistral.ai/v1/chat/completions, et la forme de la requête est suffisamment proche de la norme OpenAI pour que l'échange d'URL de base d'un autre fournisseur ne nécessite qu'une seule ligne de code. Les chiffres phares sont une fenêtre contextuelle de 256K, une vision native, l'appel de fonctions, la prise en charge de 24 langues et un score de 77,6 % sur SWE-Bench Verified ; des chiffres qui le placent au même niveau que GPT-5.5 et DeepSeek V4 pour le type de travail agentique et fortement axé sur le code que la plupart des équipes mettent en place actuellement.

Ce guide couvre l'authentification, chaque paramètre important, des exemples en Python et Node, l'entrée visuelle, l'appel d'outils, le mode JSON, le streaming, la gestion des erreurs, et un flux de travail Apidog qui permet de garder les coûts visibles pendant que vous itérez sur les invites. Pour des guides de modèles comparables, voir comment utiliser l'API DeepSeek V4 et comment utiliser l'API GPT-5.5.

En bref

• Point de terminaison : POST https://api.mistral.ai/v1/chat/completions. L'authentification est un jeton porteur dans l'en-tête Authorization standard.
• ID du modèle : mistral-medium-3.5. Fenêtre contextuelle : 256K jetons. Tarification : 1,5 $ par million de jetons d'entrée, 7,5 $ par million de jetons de sortie.
• Modèle dense fusionné de 128 milliards de paramètres avec raisonnement, vision, appel de fonctions natif, sortie JSON structurée et couverture de 24 langues.
• Poids ouverts disponibles sur Hugging Face sous le nom mistralai/Mistral-Medium-3.5-128B sous une licence MIT modifiée avec une clause de forte redevance.
• SWE-Bench Verified : 77,6 %. τ³-Telecom : 91,4. Fort en codage, en suivi d'instructions et en utilisation d'outils.
• Téléchargez Apidog pour comparer Medium 3.5 avec votre modèle actuel, stockez la clé comme variable secrète et observez la différence de coût par appel.

Ce qui a changé dans Medium 3.5

Medium 3 a été livré plus tôt dans l'année en tant que modèle texte uniquement avec un contexte de 128K. Medium 3.5 est une bête différente. C'est le premier modèle fusionné phare de Mistral : le suivi des instructions, le raisonnement et le codage vivent dans un seul ensemble de poids, vous n'avez donc plus à choisir entre un point de contrôle de chat et un point de contrôle de raisonnement. La vision est native, le contexte double à 256K, et l'appel de fonctions est intégré au niveau du modèle au lieu d'être boulonné via une surface d'API séparée.

Trois chiffres ancrent la mise à niveau. Le score SWE-Bench Verified de 77,6 % le place dans la même fourchette que les meilleurs modèles frontaliers pour le patch de code. Le score τ³-Telecom de 91,4 le place devant la plupart des modèles généralistes en matière de dialogue agentique multi-tours. Le contexte de 256K couvre une base de code de taille moyenne complète ou une transcription de plusieurs heures sans troncature. Aucun de ces chiffres n'est une erreur d'arrondi marketing ; ils indiquent directement si le modèle peut accomplir votre tâche sans un deuxième passage.

Le changement de tarification est la partie à budgétiser. Medium 3 était à 0,40 $ par million de jetons d'entrée et 2,00 $ par million de jetons de sortie. Medium 3.5 passe à 1,5 $ en entrée et 7,5 $ en sortie, soit environ 4 fois plus. C'est le coût de l'approche par point de contrôle fusionné, plus la vision, plus le contexte plus long. Considérez l'ancien Medium 3 comme l'option de débit en vrac et Medium 3.5 comme le niveau "J'ai besoin de cette réponse tout de suite".

Prérequis

Avant le premier appel, alignez quatre choses.

• Un compte Mistral sur console.mistral.ai avec un mode de paiement enregistré. Sans solde, les appels renvoient 402 Payment Required.
• Une clé API délimitée au projet sur lequel vous facturerez. Les clés de projet sont plus sûres que les clés de compte pour tout ce qui est livré en production.
• Un SDK. Mistral publie un package officiel mistralai pour Python et JavaScript, et le SDK OpenAI fonctionne sur le même point de terminaison avec un échange d'URL de base.
• Un client API capable de rejouer les requêtes sans encombrer l'historique de votre terminal. curl fonctionne pour le premier appel. Après cela, utilisez Apidog pour garder la clé hors de votre historique de shell et les corps de requête sous contrôle de version.

Exportez la clé une fois :

export MISTRAL_API_KEY="..."

Point de terminaison et authentification

La Plateforme de Mistral expose tout via une seule URL de base.

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

L'authentification est un jeton porteur dans l'en-tête Authorization. La requête minimale viable ressemble à ceci :

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {"role": "user", "content": "Expliquez les points de contrôle denses fusionnés en deux phrases."}
    ]
  }'

Une réponse réussie renvoie un corps JSON avec un tableau choices, un bloc usage décomposé en prompt_tokens, completion_tokens et total_tokens, et un id que vous pouvez utiliser pour le traçage. Les échecs renvoient une enveloppe error avec code et message. La forme correspond suffisamment à l'enveloppe OpenAI pour que tout analyseur d'erreurs que vous possédez déjà fonctionne sans modification.

Paramètres de requête

Chaque champ correspond soit au coût, soit au comportement. Voici la carte pour mistral-medium-3.5.

Deux petites différences troublent les utilisateurs lors de la migration depuis OpenAI : tool_choice="any" signifie "forcer un appel d'outil" (OpenAI utilise required), et le paramètre seed est random_seed (OpenAI utilise seed). Tout le reste correspond.

Client Python

Mistral propose un SDK Python officiel qui correspond à l'API un-à-un.

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Répondez uniquement en code."},
        {"role": "user", "content": "Écrivez une fonction Rust qui dédoublonne les événements."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

print("Contenu :", response.choices[0].message.content)
print("Total de jetons :", response.usage.total_tokens)
print("Coût estimé (USD) :",
      response.usage.prompt_tokens * 1.5 / 1_000_000 +
      response.usage.completion_tokens * 7.5 / 1_000_000)

Si vous avez déjà une base de code de forme OpenAI, le SDK Python d'OpenAI fonctionne sur le point de terminaison Mistral avec deux changements : l'URL de base et l'ID du modèle.

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MISTRAL_API_KEY"],
    base_url="https://api.mistral.ai/v1",
)

response = client.chat.completions.create(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Bonjour, Mistral."}],
)

La voie du SDK OpenAI est la moins résistante pour les équipes exécutant du code agnostique au fournisseur ; le SDK natif mistralai est la voie qui expose clairement les fonctionnalités spécifiques à Mistral, alors choisissez en fonction de si vous prévoyez d'utiliser intensivement la vision et les sorties structurées.

Client Node

Même choix à deux voies sur Node. Le SDK natif :

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.chat.complete({
  model: "mistral-medium-3.5",
  messages: [
    { role: "user", content: "Expliquez les points de contrôle denses fusionnés en anglais simple." },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log("Utilisation :", response.usage);

La voie du SDK OpenAI, pour la parité avec le code existant :

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MISTRAL_API_KEY,
  baseURL: "https://api.mistral.ai/v1",
});

const response = await client.chat.completions.create({
  model: "mistral-medium-3.5",
  messages: [{ role: "user", content: "Bonjour, Mistral." }],
});

Réponses en streaming

Définissez stream: true et itérez sur les fragments SSE. La forme correspond exactement à celle d'OpenAI, et la trace de raisonnement cumulative est entrelacée dans choices[].delta.content au lieu d'être séparée dans un champ latéral.

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Diffuser un essai de 300 mots sur les points de contrôle fusionnés."}],
)

for chunk in stream:
    delta = chunk.data.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Pour la sortie de terminal, le rythme de streaming de Mistral est plus rapide que celui de DeepSeek V4-Pro sur la même longueur d'invite et à peu près équivalent à GPT-5.5, basé sur des exécutions côte à côte via la visionneuse de réponses Apidog.

Appel d'outils

Medium 3.5 est livré avec un appel de fonctions natif. Les fonctions définies dans le tableau tools deviennent appelables, et le modèle choisit quand les invoquer.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Retourne la météo actuelle pour une ville.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Météo à Lagos en Celsius ?"}],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

À partir de là, exécutez la fonction localement, ajoutez le résultat comme un message role: "tool", et rappelez l'API pour continuer la boucle. Le modèle est identique à la boucle d'utilisation d'outils d'OpenAI. La capacité agentique est démontrée par le score τ³-Telecom ; en pratique, cela se traduit par moins de pas gaspillés dans les workflows multi-tours où le modèle doit décider entre appeler un outil, interroger l'utilisateur et répondre directement.

Mode JSON et sortie structurée

Pour une sortie validée par schéma, passez un schéma JSON dans response_format.

schema = {
    "type": "json_schema",
    "json_schema": {
        "name": "release_note",
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "date": {"type": "string"},
                "bullets": {"type": "array", "items": {"type": "string"}},
            },
            "required": ["title", "date", "bullets"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Répondez avec un seul objet JSON correspondant au schéma."},
        {"role": "user", "content": "Résumez la publication de Mistral Medium 3.5 d'aujourd'hui."},
    ],
    response_format=schema,
)

Le mode strict applique le schéma au moment du décodage, vous n'avez donc pas besoin d'ajouter une étape d'analyse Pydantic ou Zod côté client ; la réponse correspond soit au schéma, soit l'appel échoue avec une erreur structurée. Pour les cas moins contraignants où vous n'avez besoin que d'un JSON valide de n'importe quelle forme, définissez response_format={"type": "json_object"} et validez côté client.

Entrée visuelle

L'encodeur visuel de Medium 3.5 a été entraîné à partir de zéro pour gérer des tailles et des rapports d'aspect d'image variables ; vous n'avez pas besoin de pré-redimensionner quoi que ce soit. Passez le contenu de l'image avec le texte dans le tableau messages.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Qu'y a-t-il dans cette image et qu'est-ce qui ne va pas ?"},
            {"type": "image_url", "image_url": "https://example.com/diagram.png"},
        ],
    }],
)

Les entrées d'image sont facturées comme des jetons d'entrée au même tarif de 1,5 $ par million ; le nombre exact de jetons par image varie en fonction de la résolution et est indiqué dans le champ usage.prompt_tokens. Pour les charges de travail d'images à volume élevé, enregistrez le coût en jetons par image dès le début et décidez de compresser, recadrer ou ignorer des cadres avant la mise à l'échelle.

Construire la collection dans Apidog

Rejouer des requêtes depuis le terminal brûle des crédits et masque la différence entre les exécutions. Le flux de travail qui survit à une utilisation réelle :

1. Téléchargez Apidog et créez un projet.
2. Ajoutez un environnement avec {{MISTRAL_API_KEY}} stocké comme variable secrète afin qu'il ne se retrouve jamais dans les exports partagés.
3. Enregistrez une requête POST vers {{BASE_URL}}/chat/completions avec l'en-tête Authorization: Bearer {{MISTRAL_API_KEY}}.
4. Paramétrez model, temperature et tool_choice afin de pouvoir faire des tests A/B entre les variantes sans dupliquer les requêtes.
5. Utilisez la visionneuse de réponses pour inspecter usage à chaque exécution. Ajoutez un petit script post-réponse qui multiplie prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000 afin que le coût par appel s'affiche à côté de chaque résultat.

Les équipes qui exécutent déjà la collection DeepSeek V4 API correspondante dans Apidog peuvent la dupliquer, échanger l'URL de base vers https://api.mistral.ai/v1, changer l'ID du modèle en mistral-medium-3.5 et exécuter des invites côte à côte sur les deux fournisseurs en quelques minutes. Le même modèle s'applique pour comparer avec GPT-5.5.

Gestion des erreurs

L'enveloppe d'erreur suit de près les conventions d'OpenAI. Les codes que vous rencontrerez en premier :

Enveloppez les appels dans une fonction d'aide de nouvelle tentative qui gère les erreurs 429 et 5xx avec un backoff exponentiel. Ne réessayez pas les erreurs 4xx automatiquement ; ce sont des bugs logiques, pas des échecs transitoires. La visionneuse de réponses d'Apidog permet de repérer facilement une charge utile tools mal formée car le champ incriminé est mis en évidence dans le corps de la requête à côté de l'erreur.

Modèles de contrôle des coûts

Le saut de prix de 4x de Medium 3 à Medium 3.5 pénalise le routage paresseux. Cinq modèles permettent de maintenir la facture prévisible.

1. Par défaut, utilisez Medium 3, puis passez à Medium 3.5. Effectuez un premier passage bon marché sur Medium 3 et ne dirigez les invites difficiles vers 3.5 que lorsque le passage bon marché renvoie une faible confiance ou échoue à un validateur.
2. Limitez max_tokens. La plupart des réponses tiennent en 2 000 jetons de sortie. La fenêtre contextuelle de 256K est destinée au volume d'entrée, pas au volume de sortie ; la sortie est le côté coûteux à 7,5 $ par million.
3. Gardez les invites système concises. Chaque jeton d'invite système est facturé à chaque appel ; réduire un préambule de 2K jetons à 500 jetons réduit votre facture d'entrée de 75 % sur un point de terminaison à volume élevé.
4. Enregistrez usage à chaque appel. Envoyez prompt_tokens, completion_tokens et l'estimation en USD par appel à votre pile d'observabilité. Une alerte sur un pic soudain de jetons de sortie détecte les invites qui ont dérivé vers la logique de « chaîne de pensée ».
5. Utilisez la vision de manière sélective. Les jetons d'image s'accumulent rapidement. Recadrez la région pertinente avant d'envoyer, et réduisez la taille à la résolution la plus basse qui répond toujours à la question.

Comparaison de Medium 3.5 aux autres niveaux Mistral

La gamme de Mistral à la fin avril 2026 :

Medium 3.5 est le seul niveau qui combine le long contexte, la vision et les capacités de raisonnement fusionnées. Le niveau Large offre une courbe de coût différente (sortie moins chère, entrée plus chère) et surpasse le 3.5 sur quelques benchmarks texte uniquement ; choisissez en fonction de la charge de travail, et non du nom du niveau.

Migration depuis un autre fournisseur

La migration est principalement un changement d'URL de base.

Depuis OpenAI :

- base_url="https://api.openai.com/v1"
- model="gpt-5.5"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Depuis DeepSeek :

- base_url="https://api.deepseek.com/v1"
- model="deepseek-v4-pro"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Deux pièges à surveiller :

• tool_choice="required" sur OpenAI devient tool_choice="any" sur Mistral.
• seed devient random_seed.

Exécutez la différence sur votre suite de tests existante avant de basculer le trafic de production. Mieux encore, dupliquez le trafic vers Mistral en mode fantôme pendant une journée, enregistrez les deux réponses et comparez-les dans Apidog avant de promouvoir.

Cas d'utilisation réels

Quelques modèles où Medium 3.5 s'amortit déjà :

• Assistants de révision de code. Le score SWE-Bench Verified de 77,6 % et le contexte de 256K le rendent puissant pour la révision au niveau de la PR où le modèle doit voir la différence complète plus les fichiers environnants.
• QA de documents sur de longs PDF. Le contexte de 256K couvre la plupart des contrats, RFP et documents de politique en un seul appel sans découpage.
• Extraction de données multimodales. L'extraction de champs structurés à partir de reçus, de captures d'écran ou de diagrammes en un seul appel est plus efficace que l'exécution d'OCR plus un modèle de texte séparé.
• Boucles d'agents avec appels d'outils. L'appel de fonctions natif et le score élevé τ³-Telecom réduisent le nombre de cycles "appel d'outil échoué, réessayer avec JSON corrigé" qui consomment des jetons.

FAQ

Quel est l'ID du modèle pour Mistral Medium 3.5 sur l'API ?mistral-medium-3.5. Le point de contrôle Hugging Face est publié sous le nom mistralai/Mistral-Medium-3.5-128B. Si vous utilisez vous-même les poids ouverts avec vLLM ou Unsloth, utilisez l'ID Hugging Face. Pour l'API hébergée, utilisez l'ID court.

Medium 3.5 est-il compatible avec OpenAI ?Proche, mais pas identique. La forme du point de terminaison, les en-têtes et la plupart des paramètres correspondent exactement à OpenAI, de sorte que les SDK Python et Node d'OpenAI fonctionnent avec une surcharge d'URL de base. Les deux divergences sont tool_choice="any" (par rapport au required d'OpenAI) et random_seed (par rapport au seed d'OpenAI).

Puis-je exécuter Medium 3.5 localement ?Oui. Les poids sont ouverts sous une licence MIT modifiée avec une clause de forte redevance. Le nombre de paramètres de 128 milliards signifie que vous avez besoin d'une mémoire GPU significative ; les builds GGUF quantifiés de unsloth/Mistral-Medium-3.5-128B-GGUF fonctionnent sur une seule carte grand public haut de gamme. Les modèles de comment exécuter DeepSeek V4 localement se traduisent directement.

Prend-il en charge le streaming avec les appels d'outils ?Oui. Le streaming renvoie des fragments d'arguments d'appel d'outils de manière incrémentielle sur delta.tool_calls, la même forme que le format d'appel d'outils en streaming d'OpenAI. Les fragments s'accumulent en un objet JSON complet une fois le flux fermé.

Comment compter les jetons d'entrée avant d'envoyer ?Utilisez le tokenizer du package Python mistral-common pour des comptages exacts. C'est le même tokenizer que l'API utilise, donc les comptages octet par octet correspondent à usage.prompt_tokens sur la réponse.

Quelle longueur de contexte dois-je prévoir en production ?La fenêtre de 256K est le plafond, mais la tarification évolue linéairement. Un appel de 200K jetons coûte 0,30 $ en entrée seule avant même que le modèle ne commence à générer. La plupart des charges de travail de production se situent confortablement en dessous de 32K ; n'utilisez le long contexte que lorsque la tâche le nécessite vraiment.

Existe-t-il un niveau gratuit ?Mistral ne propose pas de niveau gratuit permanent, mais les nouveaux comptes sont généralement accompagnés d'un petit crédit d'essai. Pour une expérimentation gratuite et soutenue sur des modèles de niveaux similaires, consultez comment utiliser l'API DeepSeek V4 gratuitement.