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 le format de requête reste très proche de celui d’OpenAI. En pratique, migrer depuis un autre fournisseur peut se limiter à changer l’URL de base et l’ID du modèle. Les points clés : fenêtre de contexte de 256K, vision native, appel de fonctions, prise en charge de 24 langues et score de 77,6 % sur SWE-Bench Verified.

Essayez Apidog aujourd’hui

Ce guide montre comment appeler Medium 3.5 en production : authentification, paramètres importants, exemples Python et Node.js, streaming, vision, appels d’outils, mode JSON, gestion des erreurs et suivi des coûts avec Apidog. Pour comparer avec d’autres modèles, voir aussi 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
• Authentification : jeton porteur dans l’en-tête Authorization
• Modèle : mistral-medium-3.5
• Contexte : 256K jetons
• Tarification : 1,5 $ / million de jetons d’entrée, 7,5 $ / million de jetons de sortie
• Fonctionnalités : raisonnement, vision native, appel de fonctions, JSON structuré, 24 langues
• Poids ouverts : mistralai/Mistral-Medium-3.5-128B sur Hugging Face sous licence MIT modifiée avec clause de forte redevance
• Benchmarks cités : 77,6 % sur SWE-Bench Verified, 91,4 sur τ³-Telecom
• Pour tester et suivre les coûts par appel : téléchargez Apidog

Ce qui change avec Medium 3.5

Medium 3 était un modèle texte uniquement avec un contexte de 128K. Medium 3.5 ajoute une architecture de modèle dense fusionné : le suivi d’instructions, le raisonnement et le codage sont réunis dans un seul ensemble de poids.

Conséquences pratiques :

• vous n’avez plus à choisir entre un modèle de chat et un modèle de raisonnement ;
• la vision est native ;
• la fenêtre de contexte passe à 256K ;
• l’appel de fonctions est intégré au modèle ;
• les sorties structurées sont utilisables directement via l’API.

Trois chiffres résument l’intérêt du modèle pour les développeurs :

Le point à surveiller est le coût. Medium 3 était facturé 0,40 $ / million de jetons d’entrée et 2,00 $ / million de jetons de sortie. Medium 3.5 passe à 1,5 $ en entrée et 7,5 $ en sortie. Utilisez-le donc pour les tâches qui justifient la vision, le raisonnement ou le long contexte.

Prérequis

Avant votre premier appel, préparez :

1. un compte Mistral sur console.mistral.ai ;
2. un moyen de paiement actif, sinon l’API peut renvoyer 402 Payment Required ;
3. une clé API limitée au projet à facturer ;
4. un SDK Python ou JavaScript ;
5. un client API pour rejouer et versionner les requêtes, par exemple Apidog.

Exportez la clé côté terminal :

export MISTRAL_API_KEY="..."

Point de terminaison et authentification

L’URL de l’API chat completions est :

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

L’authentification passe par l’en-tête standard :

Authorization: Bearer <MISTRAL_API_KEY>

Exemple minimal avec curl :

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 contient notamment :

• choices[] : les réponses candidates ;
• usage.prompt_tokens ;
• usage.completion_tokens ;
• usage.total_tokens ;
• id : utile pour le traçage.

Les erreurs utilisent une enveloppe error avec code et message, proche du format OpenAI.

Paramètres de requête importants

Deux différences à retenir si vous migrez depuis OpenAI :

OpenAI:  tool_choice="required"
Mistral: tool_choice="any"

OpenAI:  seed
Mistral: random_seed

Appeler Medium 3.5 avec Python

Installez le SDK Mistral :

pip install mistralai

Exemple de requête :

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)

cost = (
    response.usage.prompt_tokens * 1.5 / 1_000_000
    + response.usage.completion_tokens * 7.5 / 1_000_000
)

print("Coût estimé USD :", cost)

Si votre code utilise déjà le SDK OpenAI, vous pouvez seulement changer base_url et model :

import os
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."
        }
    ],
)

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

Utilisez le SDK OpenAI si vous voulez rester agnostique au fournisseur. Utilisez le SDK mistralai si vous voulez exposer explicitement les fonctionnalités Mistral dans votre code.

Appeler Medium 3.5 avec Node.js

Installez le SDK officiel :

npm install @mistralai/mistralai

Exemple avec le SDK Mistral :

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);

Avec le SDK OpenAI :

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.",
    },
  ],
});

console.log(response.choices[0].message.content);

Streaming des réponses

Activez stream: true pour recevoir les fragments au fil de l’eau.

Exemple Python :

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Diffusez 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)

Le format des fragments est proche de celui d’OpenAI. Le contenu arrive dans :

choices[].delta.content

Pour comparer le streaming entre fournisseurs, vous pouvez rejouer la même requête dans la visionneuse de réponses Apidog.

Appel d’outils

Medium 3.5 prend en charge l’appel de fonctions natif. Déclarez vos outils dans tools, puis laissez le modèle décider quand les appeler.

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)
print(tool_call.function.arguments)

Ensuite :

1. exécutez la fonction côté application ;
2. ajoutez le résultat comme message role: "tool" ;
3. rappelez l’API pour continuer la conversation.

Schéma général :

messages = [
    {"role": "user", "content": "Météo à Lagos en Celsius ?"},
    response.choices[0].message,
    {
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": '{"city":"Lagos","temperature":31,"unit":"c"}',
    },
]

final_response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=messages,
    tools=tools,
)

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

Mode JSON et sortie structurée

Pour obtenir un JSON valide, utilisez :

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Retournez un objet JSON avec title, date et bullets."
        }
    ],
    response_format={"type": "json_object"},
)

Pour une sortie validée par schéma :

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,
)

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

En mode strict, la sortie doit correspondre au schéma. Pour des cas moins contraints, utilisez {"type": "json_object"} et validez côté client avec Pydantic, Zod ou votre validateur habituel.

Entrée visuelle

Medium 3.5 accepte du texte et des images dans le même message.

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"
                },
            ],
        }
    ],
)

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

Les images sont facturées comme jetons d’entrée au tarif de 1,5 $ / million. Le coût dépend de la résolution et apparaît dans usage.prompt_tokens.

Pour réduire la facture :

• recadrez la zone utile ;
• évitez d’envoyer plusieurs captures presque identiques ;
• compressez les images lorsque la précision visuelle reste suffisante ;
• loguez le coût par image dès les premiers tests.

Construire une collection dans Apidog

Rejouer les requêtes depuis le terminal devient vite difficile à maintenir. Un workflow plus robuste consiste à créer une collection API.

Étapes :

1. Téléchargez Apidog et créez un projet.
2. Créez un environnement avec :
   • BASE_URL=https://api.mistral.ai/v1
   • MISTRAL_API_KEY=<votre clé>
3. Stockez MISTRAL_API_KEY comme variable secrète.
4. Ajoutez une requête POST vers :

   {{BASE_URL}}/chat/completions

1. Ajoutez les en-têtes :

   Authorization: Bearer {{MISTRAL_API_KEY}}
   Content-Type: application/json

1. Paramétrez le corps :

   {
     "model": "mistral-medium-3.5",
     "temperature": 0.3,
     "max_tokens": 2048,
     "messages": [
       {
         "role": "user",
         "content": "Analysez ce diff et proposez une correction."
       }
     ]
   }

1. Inspectez usage à chaque exécution.
2. Ajoutez un calcul de coût par appel :

   const usage = response.json().usage;

   const cost =
     usage.prompt_tokens * 1.5 / 1_000_000 +
     usage.completion_tokens * 7.5 / 1_000_000;

   console.log(`Coût estimé : $${cost}`);

Si vous utilisez déjà une collection DeepSeek V4 API, dupliquez-la, remplacez l’URL de base par https://api.mistral.ai/v1, puis changez le modèle en mistral-medium-3.5. Le même principe s’applique pour comparer avec GPT-5.5.

Gestion des erreurs

Exemple de wrapper Python avec retry simple :

import time
import random

def call_with_retry(fn, max_attempts=4):
    for attempt in range(max_attempts):
        try:
            return fn()
        except Exception as exc:
            status = getattr(exc, "status_code", None)

            if status not in [429, 500, 502, 503, 504]:
                raise

            if attempt == max_attempts - 1:
                raise

            delay = (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)

N’appliquez pas de retry automatique sur les erreurs 4xx hors 429. Elles signalent généralement un bug de requête, pas un incident transitoire.

Contrôler les coûts

Medium 3.5 coûte environ 4x plus cher que Medium 3. Pour éviter les surprises, appliquez ces règles.

1. Router par difficulté

Utilisez Medium 3 par défaut, puis escaladez vers Medium 3.5 si :

• le validateur échoue ;
• la confiance est faible ;
• la tâche nécessite la vision ;
• le contexte dépasse ce que Medium 3 gère confortablement ;
• la tâche est agentique ou fortement orientée code.

2. Limiter max_tokens

La sortie coûte plus cher que l’entrée. Définissez toujours une limite :

{
  "max_tokens": 2048
}

N’utilisez pas la fenêtre de 256K comme excuse pour produire des réponses très longues.

3. Réduire les prompts système

Un prompt système de 2 000 jetons est refacturé à chaque appel. Si vous le réduisez à 500 jetons, vous baissez fortement le coût d’entrée sur les endpoints à fort volume.

4. Logger usage

À chaque appel, stockez :

{
  "prompt_tokens": 1234,
  "completion_tokens": 567,
  "total_tokens": 1801,
  "estimated_cost_usd": 0.0061
}

Calculez le coût :

cost = (
    prompt_tokens * 1.5 / 1_000_000
    + completion_tokens * 7.5 / 1_000_000
)

5. Utiliser la vision uniquement si nécessaire

Pour les images :

• recadrez avant l’envoi ;
• évitez les frames vidéo redondantes ;
• réduisez la résolution quand c’est acceptable ;
• mesurez prompt_tokens par type d’image.

Comparaison avec les autres niveaux Mistral

Gamme Mistral à la fin avril 2026 :

Medium 3.5 est le choix pertinent si vous avez besoin à la fois de long contexte, de vision et de raisonnement fusionné. Pour du texte uniquement, comparez aussi le coût de sortie avec mistral-large.

Migrer depuis OpenAI ou DeepSeek

La migration est principalement un changement d’URL de base et d’ID de modèle.

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"

Points à adapter :

- tool_choice="required"
+ tool_choice="any"

- seed=42
+ random_seed=42

Avant de basculer la production :

1. exécutez vos tests existants ;
2. comparez les réponses sur un échantillon réel ;
3. mesurez le coût par tâche ;
4. envoyez du trafic en miroir si possible ;
5. validez les sorties structurées et appels d’outils.

Cas d’utilisation pertinents

Medium 3.5 est particulièrement utile pour :

• assistants de revue de code : contexte de 256K et score SWE-Bench Verified de 77,6 % ;
• QA sur documents longs : contrats, RFP, politiques internes, transcriptions ;
• extraction multimodale : reçus, captures d’écran, diagrammes ;
• agents avec outils : appels de fonctions natifs et workflows multi-tours ;
• migration multi-fournisseur : format proche d’OpenAI avec faible friction côté client.

FAQ

Quel est l’ID du modèle API ?

L’ID est :

mistral-medium-3.5

Le point de contrôle Hugging Face est :

mistralai/Mistral-Medium-3.5-128B

Utilisez l’ID court pour l’API hébergée. Utilisez l’ID Hugging Face si vous exécutez les poids vous-même.

Medium 3.5 est-il compatible OpenAI ?

Il est proche du format OpenAI, mais pas strictement identique. Les SDK OpenAI Python et Node.js peuvent fonctionner en changeant base_url, mais attention à :

• tool_choice="any" au lieu de required ;
• random_seed au lieu de seed.

Puis-je exécuter Medium 3.5 localement ?

Oui. Les poids sont ouverts sous licence MIT modifiée avec clause de forte redevance. Le modèle compte 128 milliards de paramètres, donc il nécessite une mémoire GPU importante. Des builds GGUF quantifiés comme unsloth/Mistral-Medium-3.5-128B-GGUF existent pour certains scénarios. Les principes décrits dans comment exécuter DeepSeek V4 localement se transposent.

Le streaming fonctionne-t-il avec les appels d’outils ?

Oui. Les fragments d’arguments d’appel d’outils arrivent progressivement via delta.tool_calls, dans un format proche de celui d’OpenAI. Reconstituez les fragments jusqu’à obtenir un JSON complet.

Comment compter les jetons avant l’envoi ?

Utilisez le tokenizer du package Python mistral-common. Il correspond au tokenizer utilisé par l’API, donc les estimations sont alignées avec usage.prompt_tokens.

Faut-il utiliser toute la fenêtre de contexte de 256K ?

Non. La fenêtre de 256K est un plafond, pas une cible. Un appel de 200K jetons coûte déjà 0,30 $ en entrée avant génération. Réservez le long contexte aux tâches qui le nécessitent réellement.

Existe-t-il un niveau gratuit ?

Mistral ne propose pas de niveau gratuit permanent, mais les nouveaux comptes peuvent recevoir un petit crédit d’essai. Pour tester gratuitement des modèles de niveau comparable, consultez comment utiliser l’API DeepSeek V4 gratuitement.