Mistral Responses API : configurer Large 4 et migrer depuis OpenAI

Utilisez Mistral Responses API avec mistral-large-4 et envoyez l’historique de conversation dans input à chaque requête. Supprimez les paramètres de continuation côté serveur, laissez le stockage désactivé et choisissez un effort de raisonnement accepté par le modèle. Au 2026-11-01, l’API Responses de Mistral est en préversion publique.

Envoyer une requête minimale à Mistral Large 4

Utilisez le SDK Python actuel de Mistral et une clé API Mistral pour la première requête. Vous disposez ainsi d’un point de départ documenté avant d’adapter un client Responses existant.

Il vous faut Python 3.10 ou une version ultérieure. Créez une clé dans Studio → API keys, puis exécutez ces commandes dans Bash. Quand read attend une entrée, collez la clé et appuyez sur Entrée. Elle ne s’affiche pas à l’écran.

python3 -m pip install -U mistralai
read -rs MISTRAL_API_KEY && export MISTRAL_API_KEY

Enregistrez le code suivant dans mistral_responses.py. La fonction auxiliaire conserve les mêmes instructions et paramètres de requête dans les exemples suivants.

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
MODEL = "mistral-large-4"
INSTRUCTIONS = "Answer concisely."

def create_response(history, **options):
    result = client.responses.create(
        model=MODEL,
        input=history,
        instructions=INSTRUCTIONS,
        reasoning={"effort": "high"},
        max_output_tokens=4096,
        additional_properties={
            "store": False,
            "background": False,
            "truncation": "disabled",
        },
        **options,
    )
    if result.status != "completed":
        raise RuntimeError(
            f"{result.status}: {result.error or result.incomplete_details}"
        )
    return result

def answer_text(result):
    return "".join(
        part.text
        for item in result.output if item.type == "message"
        for part in item.content if part.type == "output_text"
    )

history = [{"role": "user", "content": "Explain a stateless API in one sentence."}]
response = create_response(history)
print(response.status)
print(answer_text(response))

Exécutez le fichier depuis la même session Bash :

python3 mistral_responses.py

Pour cet exemple, le résultat attendu est completed, suivi d’une explication non vide. La formulation peut varier. Le code extrait le texte de la réponse, car output peut aussi contenir du raisonnement et des appels de fonctions.

Le point de terminaison HTTP est https://api.mistral.ai/v1/responses. Les requêtes HTTP directes utilisent l’en-tête Authorization: Bearer $MISTRAL_API_KEY. Si le client ajoute /responses, utilisez l’URL de base https://api.mistral.ai/v1.

Les autres exemples Python réutilisent les variables et les fonctions auxiliaires de ce fichier. Ajoutez les exemples nécessaires à la fin. Chaque nouvelle exécution du fichier relance tous les appels de génération qu’il contient.

Quels paramètres OpenAI Responses faut-il modifier ?

Appliquez ces règles aux champs JSON de la requête HTTP avant de réutiliser une requête OpenAI Responses. La référence de l’API Responses de Mistral définit ces valeurs acceptées au 2026-11-01.

Paramètre de la requête Responses	Exigence de Mistral	Modification à effectuer
`previous_response_id`	Omettez-le ou envoyez `null`.	Renvoyez les éléments des réponses précédentes dans `input`.
`conversation`	Omettez-le ou envoyez `null`.	Conservez l’historique de conversation dans votre application.
`store`	Omettez-le, ou envoyez `false` ou `null`.	Supprimez `true` ; ne dépendez pas de réponses stockées.
`background`	Doit valoir `false`, également sa valeur par défaut.	Supprimez l’exécution en arrière-plan et les interrogations périodiques de son état.
`truncation`	Doit valoir `"disabled"`, également sa valeur par défaut.	Gérez la taille du contexte avant d’envoyer la requête.
`prompt`	Omettez-le ou envoyez `null`.	Placez le contenu du prompt dans `input` et `instructions`.
`moderation`	Omettez-le ou envoyez `null`.	Supprimez la valeur renseignée dans ce champ de compatibilité.
`top_logprobs`	Omettez-le, ou envoyez `0` ou `null`.	Supprimez toute valeur positive.
`max_tool_calls`	Accepté, mais actuellement ignoré.	Appliquez les limites d’exécution dans votre application.
`reasoning.effort`	Le modèle sélectionné doit accepter la valeur.	Utilisez les valeurs propres à chaque modèle indiquées ci-dessous.
`tools`	Fonctions exécutées par le client, éventuellement regroupées dans des espaces de noms.	Remplacez les dépendances aux outils hébergés par le fournisseur.
`max_output_tokens`	Inclut les tokens de raisonnement et le texte de la réponse.	Prévoyez un budget de sortie suffisant pour les deux.

Les arguments nommés du SDK Python ne correspondent pas à tous les champs HTTP. Son implémentation actuelle de Responses accepte store, background et truncation via additional_properties. Le premier exemple utilise ce mécanisme.

Tenez compte de ces différences dans la configuration de chaque fournisseur. Changer le point de terminaison ne confirme pas la compatibilité de tous les outils, modes de continuation ou traitements du streaming. Le guide de compatibilité entre Messages, Chat Completions et Responses explique pourquoi vérifier le cycle complet d’un appel de fonction.

Quels modèles et quelles fonctionnalités sont disponibles ?

Utilisez mistral-large-4 pour ces exemples et vérifiez à nouveau les capacités lorsque vous changez de modèle. L’annonce de lancement de Mistral indique que l’API accepte tous les modèles de chat hébergés par Mistral, dont Large 4.

La liste des fonctionnalités disponibles comprend le texte en entrée et en sortie, les sorties structurées, le streaming et les fonctions. Le raisonnement dépend du modèle. Les images nécessitent un modèle capable de les interpréter ; vous pouvez fournir des URL d’images ou des URL de données en base64.

Les fichiers peuvent provenir d’URL HTTPS, d’URL de données en base64 ou d’identifiants de fichiers téléversés. Leur prise en charge dépend du modèle.

Les sorties structurées utilisent text.format pour le mode JSON ou JSON Schema. Les fonctions s’exécutent dans votre application. L’implémentation publiée accepte uniquement les fonctions exécutées par le client : ne transférez donc pas un outil hébergé web_search sans l’adapter.

Pour le raisonnement, utilisez le champ imbriqué reasoning.effort de Responses. Ces valeurs suivent le guide du raisonnement de Mistral, consulté le 2026-11-01 :

Modèle	Valeurs acceptées	Choix pratique
`mistral-large-4` / `mistral-large-4-0`	`low`, `medium`, `high`	Commencez par `high` pour cet exemple. Comparez les niveaux inférieurs si la latence ou la consommation de tokens est prioritaire.
`mistral-small-2603`	`none`, `high`	Utilisez `high` si vous avez besoin de son mode de raisonnement.
`mistral-medium-3-5`	`none`, `high`	Pour les intégrations existantes ; le modèle est marqué comme déprécié.

Large 4 n’accepte pas none, minimal, xhigh ou max. Si vous avez repris des exemples des premières préversions de Large 4, remplacez none par low. La présence d’une valeur dans une énumération commune du SDK ne signifie pas que tous les modèles l’acceptent.

La fiche de Large 4 indique également que le modèle est en préversion publique. La fiche de Medium 3.5 donne le 2026-10-31 comme date de dépréciation et recommande Large 4 pour les nouvelles intégrations.

Construire l’historique et renvoyer les résultats des fonctions

Conservez l’historique complet des éléments, y compris le raisonnement et les appels de fonctions. Le texte de la réponse convient à l’affichage, mais ne représente pas l’intégralité de la conversation.

Continuer une conversation

Ajoutez tous les éléments du output précédent, puis le prochain message de l’utilisateur. Placez ce code après le premier exemple :

history.extend(response.output)
history.append({"role": "user", "content": "What must the client send next time?"})
response = create_response(history)
print(answer_text(response))
history.extend(response.output)

La deuxième requête contient le premier message de l’utilisateur, la première réponse complète et la question suivante. La fonction auxiliaire transmet à nouveau instructions.

C’est la méthode documentée pour remplacer previous_response_id. Conserver uniquement un identifiant de réponse ne fournit aucun historique à ce point de terminaison sans état. Conserver seulement le texte affiché écarte les autres éléments renvoyés.

Renvoyer le résultat d’une fonction

Exécutez la fonction localement, puis renvoyez son résultat avec le call_id correspondant. L’exemple d’appel de fonction de Mistral place type, name, description et parameters dans un même objet outil. L’exemple suivant reprend cette structure pour effectuer une addition locale avec un historique distinct.

import json

TOOLS = [{
    "type": "function",
    "name": "add",
    "description": "Add two integers.",
    "parameters": {
        "type": "object",
        "properties": {
            "a": {"type": "integer"},
            "b": {"type": "integer"},
        },
        "required": ["a", "b"],
        "additionalProperties": False,
    },
}]
tool_history = [{"role": "user", "content": "Use add to calculate 19 + 23."}]
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice={"type": "function", "name": "add"},
    parallel_tool_calls=False,
)
tool_history.extend(response.output)

calls = [item for item in response.output if item.type == "function_call"]
if len(calls) != 1 or calls[0].name != "add":
    raise RuntimeError("Expected exactly one add call.")

call = calls[0]
args = json.loads(call.arguments)
if (
    not isinstance(args, dict)
    or set(args) != {"a", "b"}
    or any(type(args[name]) is not int for name in ("a", "b"))
):
    raise ValueError("Expected two integer arguments.")

result = args["a"] + args["b"]
print("Local result:", result)
tool_history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps({"result": result}),
})
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice="none",
    parallel_tool_calls=False,
)
print(answer_text(response))
tool_history.extend(response.output)

Vérifiez que Local result: 42 s’affiche, suivi d’une réponse qui utilise ce résultat. La formulation du modèle peut varier.

La première requête impose l’appel à add. La seconde utilise "none" pour désactiver les appels suivants, comme l’indique la référence de l’API. L’exemple se limite ainsi à deux étapes de génération et une exécution locale.

Dans une boucle d’agent sans nombre fixe d’étapes, appliquez vos propres limites d’itérations et d’exécutions. Le paramètre max_tool_calls est ignoré.

Conservez tous les éléments de sortie avant d’ajouter les résultats des fonctions. Associez les résultats à call_id, et non à l’id de l’élément de sortie. Si vous autorisez plusieurs appels de fonctions, validez et renvoyez chaque résultat avant de demander la réponse suivante.

Compter les tokens d’entrée avant que l’historique s’allonge

Comptez la prochaine requête complète, y compris l’historique, les instructions et les définitions des outils. Compter uniquement le dernier message oublie du contenu que votre application renverra.

Après l’exemple de fonction, utilisez ce code :

next_input = tool_history + [
    {"role": "user", "content": "Explain that calculation in one sentence."}
]
count = client.responses.count_input_tokens(
    model=MODEL,
    input=next_input,
    instructions=INSTRUCTIONS,
    tools=TOOLS,
    reasoning={"effort": "high"},
    parallel_tool_calls=False,
    tool_choice="auto",
)
print(count.input_tokens)

Ce code appelle POST /v1/responses/input_tokens et affiche input_tokens. Il compte l’entrée sans générer de réponse. Utilisez le même modèle, la même entrée, les mêmes instructions et les mêmes outils lors de la génération suivante.

Comparez ce nombre à la fenêtre de contexte du modèle sélectionné et réservez de la place pour la sortie. Comme truncation doit rester à "disabled", votre application doit décider quand réduire l’historique.

Lorsque vous gérez l’historique, conservez les appels de fonctions avec leurs résultats correspondants. Évitez de supprimer arbitrairement des éléments au milieu d’un échange avec un outil.

Le nombre de tokens n’est pas une estimation monétaire. Consultez les tarifs actuels de l’API Mistral pour estimer le coût des tours successifs et les effets du cache.

Diagnostiquer les erreurs de migration

Vérifiez d’abord la configuration de la requête, puis son statut et ses éléments de sortie. Choisissez la vérification qui correspond au symptôme.

Le SDK rejette un argument nommé avant d’envoyer la requête. Vérifiez le SDK installé et la signature de la méthode. Dans l’implémentation utilisée ici, placez store, background et truncation dans additional_properties.
L’API rejette la requête. Revenez au premier exemple de texte. Vérifiez l’identifiant du modèle, l’effort de raisonnement accepté et le tableau de compatibilité. Une fois la requête réussie, réintroduisez les champs facultatifs un par un.
Le modèle perd le contexte précédent. Examinez le prochain tableau input. Il doit contenir les messages précédents et les éléments de sortie complets, pas seulement un identifiant de réponse.
La réponse ne contient aucun texte. Examinez status, error et incomplete_details. Vérifiez si un appel de fonction attend son exécution. Si la génération a épuisé son budget de sortie, augmentez-le ou réduisez l’effort de raisonnement à une valeur acceptée par le modèle.
La requête arrive au mauvais chemin. Comparez l’URL finale à https://api.mistral.ai/v1/responses. Le guide sur l’URL de base, les points de terminaison et les erreurs de connexion explique les erreurs courantes de construction du chemin.

Pour le streaming, définissez stream=True et traitez les événements Responses. L’exemple officiel de streaming en Python lit chaque événement via frame.data. Le texte arrive dans response.output_text.delta ; response.completed signale la fin de la réponse.

Gérez aussi les événements response.failed, response.incomplete et error. Recevoir un fragment de texte ne confirme pas que la génération s’est terminée correctement. La génération en arrière-plan est désactivée : cette configuration n’a donc pas besoin d’une boucle d’interrogation périodique.

Choisir Responses, Chat Completions ou Conversations

Choisissez Responses si son format d’éléments convient à votre application et si vous souhaitez contrôler l’historique et l’exécution des fonctions.

Besoin de votre application	API à essayer en premier	Pourquoi
Éléments d’entrée et de sortie Responses, avec ses événements de streaming	Responses API	Le format reste le même tandis que votre application gère l’état et les fonctions.
Conserver une intégration existante fondée sur des messages	Chat Completions	Vous pouvez garder le traitement des requêtes et des réponses sous forme de messages.
Reprendre des conversations enregistrées ou utiliser des outils hébergés par Mistral	Conversations API	Elle fournit des identifiants de conversation et une interface distincte pour les outils hébergés.

Le guide Chat Completions de Mistral décrit le format fondé sur les messages. La référence de Conversations explique comment continuer avec conversation_id.

Pour la recherche hébergée, Mistral documente web_search et web_search_premium dans Conversations et Agents. Cette fonctionnalité est distincte des fonctions Responses exécutées par le client.

Si votre application dépend de conversations enregistrées ou d’outils hébergés, évaluez Conversations avant de migrer le contenu de ses requêtes. Si elle gère déjà ces responsabilités, vérifiez la requête de texte, le tour suivant et le cycle complet de fonction présentés ici. Connectez ensuite l’agent complet.