Mistral Responses API: Large 4 einrichten und von OpenAI umsteigen

Verwende die Mistral Responses API mit mistral-large-4 und sende den Gesprächsverlauf bei jeder Anfrage in input. Entferne Parameter für die serverseitige Gesprächsfortsetzung, lasse die Speicherung deaktiviert und wähle eine vom Modell unterstützte Reasoning-Stufe. Stand 2026-11-01 ist Mistrals Responses API als öffentliche Vorschau verfügbar.

Eine minimale Anfrage an Mistral Large 4 senden

Verwende für die erste Anfrage das aktuelle Mistral Python SDK und einen Mistral-API-Schlüssel. Damit hast du einen dokumentierten Ausgangspunkt, bevor du einen bestehenden Responses-Client anpasst.

Du brauchst Python 3.10 oder neuer. Erstelle unter Studio → API keys einen Schlüssel und führe diese Befehle in Bash aus. Wenn read auf die Eingabe wartet, füge den Schlüssel ein und drücke Enter. Die Eingabe bleibt unsichtbar.

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

Speichere den folgenden Code als mistral_responses.py. Die Hilfsfunktion verwendet in den späteren Beispielen dieselben Anweisungen und Anfrageeinstellungen.

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

Starte das Skript in derselben Bash-Sitzung:

python3 mistral_responses.py

In diesem Beispiel erkennst du den Erfolg an completed, gefolgt von einer nicht leeren Erklärung. Der Wortlaut kann variieren. Der Code wählt den Antworttext aus, weil output auch Reasoning und Funktionsaufrufe enthalten kann.

Der HTTP-Endpunkt lautet https://api.mistral.ai/v1/responses. Direkte HTTP-Anfragen verwenden den Header Authorization: Bearer $MISTRAL_API_KEY. Hängt ein Client selbst /responses an, braucht er die Basis-URL https://api.mistral.ai/v1.

Die weiteren Python-Beispiele verwenden die Variablen und Hilfsfunktionen dieser Datei. Hänge die benötigten Beispiele an. Jeder erneute Skriptstart führt alle darin enthaltenen Generierungsaufrufe erneut aus.

Welche Parameter von OpenAI Responses musst du ändern?

Passe die JSON-Felder der HTTP-Anfrage an diese Anforderungen an, bevor du eine OpenAI-Responses-Anfrage wiederverwendest. Die Responses-API-Referenz von Mistral nennt mit Stand 2026-11-01 folgende zulässige Werte.

Parameter der Responses-Anfrage	Anforderung von Mistral	Änderung bei der Migration
`previous_response_id`	Weglassen oder `null` senden.	Frühere Ausgabeelemente erneut in `input` senden.
`conversation`	Weglassen oder `null` senden.	Den Gesprächsverlauf in der Anwendung speichern.
`store`	Weglassen oder `false` beziehungsweise `null` senden.	`true` entfernen; nicht auf gespeicherte Antworten bauen.
`background`	Muss `false` sein; das ist auch der Standardwert.	Hintergrundausführung und zugehöriges Polling entfernen.
`truncation`	Muss `"disabled"` sein; das ist auch der Standardwert.	Den Kontextumfang vor dem Senden begrenzen.
`prompt`	Weglassen oder `null` senden.	Den Prompt-Inhalt in `input` und `instructions` übergeben.
`moderation`	Weglassen oder `null` senden.	Einen gesetzten Wert aus diesem Kompatibilitätsfeld entfernen.
`top_logprobs`	Weglassen oder `0` beziehungsweise `null` senden.	Einen positiven Wert entfernen.
`max_tool_calls`	Wird akzeptiert, derzeit aber ignoriert.	Ausführungen in der Anwendung selbst begrenzen.
`reasoning.effort`	Das gewählte Modell muss den Wert unterstützen.	Die modellspezifischen Werte weiter unten verwenden.
`tools`	Vom Client ausgeführte Funktionen; sie können in Namensräumen gruppiert werden.	Abhängigkeiten von serverseitigen Tools des Anbieters ersetzen.
`max_output_tokens`	Umfasst Reasoning-Tokens und Antworttext zusammen.	Genügend Ausgabetokens für beide Teile einplanen.

Die Schlüsselwortargumente des Python SDK bilden nicht jedes HTTP-Feld direkt ab. Die aktuelle Responses-Implementierung nimmt store, background und truncation über additional_properties entgegen. Das erste Beispiel nutzt diesen Weg.

Berücksichtige diese Unterschiede in der Konfiguration des Anbieters. Ein geänderter Endpunkt bedeutet nicht, dass alle Tools, Fortsetzungsmethoden und Streaming-Handler kompatibel sind. Der Leitfaden zur Kompatibilität von Messages, Chat Completions und Responses erklärt, warum du den vollständigen Ablauf eines Funktionsaufrufs prüfen solltest.

Welche Modelle und Funktionen kannst du nutzen?

Verwende in diesen Beispielen mistral-large-4 und prüfe die Fähigkeiten erneut, wenn du das Modell wechselst. Laut Mistrals Ankündigung unterstützt die API alle dort gehosteten Chatmodelle, einschließlich Large 4.

Die Liste unterstützter Funktionen umfasst Texteingabe und Textausgabe, strukturierte Ausgabe, Streaming, Funktionen und modellabhängiges Reasoning. Bildeingaben brauchen ein Modell mit Bildverarbeitung und akzeptieren Bild-URLs oder Daten-URLs mit base64-Kodierung. Dateien lassen sich über HTTPS-URLs, Daten-URLs mit base64-Kodierung oder IDs hochgeladener Dateien übergeben; die Unterstützung hängt vom Modell ab.

Für strukturierte Ausgabe im JSON-Modus oder mit JSON Schema verwendest du text.format. Funktionen laufen in deiner Anwendung. Die veröffentlichte Implementierung unterstützt nur solche clientseitig ausgeführten Funktionen; übernimm ein serverseitiges web_search-Tool daher nicht unverändert.

Die Reasoning-Stufe setzt du in Responses über das verschachtelte Feld reasoning.effort. Die folgenden Werte stammen aus Mistrals Reasoning-Leitfaden, geprüft am 2026-11-01:

Modell	Unterstützte Werte	Praktische Wahl
`mistral-large-4` / `mistral-large-4-0`	`low`, `medium`, `high`	Starte für das Beispiel mit `high`. Vergleiche niedrigere Stufen, wenn Latenz oder Tokenverbrauch wichtig sind.
`mistral-small-2603`	`none`, `high`	Verwende `high`, wenn du den Reasoning-Modus brauchst.
`mistral-medium-3-5`	`none`, `high`	Für bestehende Integrationen relevant; das Modell ist als veraltet markiert.

Large 4 akzeptiert weder none noch minimal, xhigh oder max. Hast du Beispiele aus einer frühen Large-4-Vorschau übernommen, ersetze none durch low. Ein Wert in der gemeinsamen SDK-Aufzählung bedeutet nicht, dass jedes Modell ihn unterstützt.

Die Modellkarte von Large 4 führt das Modell ebenfalls als öffentliche Vorschau. Laut Modellkarte von Medium 3.5 gilt Medium 3.5 seit 2026-10-31 als veraltet. Für neue Integrationen empfiehlt Mistral Large 4.

Gesprächsverlauf aufbauen und Funktionsergebnisse zurückgeben

Bewahre den vollständigen Verlauf aller Elemente auf, einschließlich Reasoning und Funktionsaufrufen. Der Antworttext eignet sich zur Anzeige, bildet aber nicht das ganze Gespräch ab.

Ein Gespräch fortsetzen

Füge alle Elemente des vorherigen output an und danach die nächste Benutzernachricht. Ergänze diesen Code nach dem ersten Beispiel:

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)

Die zweite Anfrage enthält die erste Benutzernachricht, die vollständige erste Antwort und die Nachfrage. Die Hilfsfunktion sendet auch instructions erneut.

Das ist der dokumentierte Ersatz für previous_response_id. Nur eine Antwort-ID zu speichern reicht bei diesem zustandslosen Endpunkt nicht als Verlauf. Wenn du nur den ausgegebenen Antworttext speicherst, gehen andere zurückgegebene Elemente verloren.

Ein Funktionsergebnis zurückgeben

Führe die Funktion lokal aus und sende ihr Ergebnis mit der passenden call_id zurück. Mistrals Beispiel für Funktionsaufrufe setzt type, name, description und parameters in dasselbe Tool-Objekt. Das folgende Beispiel nutzt diese Struktur für eine lokale Addition mit einem eigenen Verlauf.

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)

Achte auf Local result: 42 und einen anschließenden Antworttext, der dieses Ergebnis verwendet. Der Wortlaut des Modells kann variieren.

Die erste Anfrage erzwingt add; die zweite deaktiviert weitere Aufrufe mit "none", wie in der API-Referenz beschrieben. Damit bleibt das Beispiel auf zwei Generierungsschritte und eine lokale Ausführung begrenzt. Bei einer Agentenschleife ohne feste Schrittzahl musst du Durchläufe und Ausführungen selbst begrenzen, weil max_tool_calls ignoriert wird.

Übernimm alle zurückgegebenen Ausgabeelemente, bevor du Funktionsergebnisse ergänzt. Ordne Ergebnisse mit call_id zu, nicht mit dem id-Feld des Ausgabeelements. Wenn du mehrere Funktionsaufrufe erlaubst, prüfe sie und übermittle jedes Ergebnis, bevor du die nächste Antwort anforderst.

Eingabe-Tokens zählen, bevor der Verlauf wächst

Zähle die Tokens der gesamten nächsten Anfrage, einschließlich Verlauf, Anweisungen und Tool-Definitionen. Zählst du nur die neueste Benutzernachricht, fehlen Inhalte, die deine Anwendung erneut senden wird.

Verwende nach dem Funktionsbeispiel diesen 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)

Dieser Code ruft POST /v1/responses/input_tokens auf und gibt input_tokens aus. Er zählt die Eingabe, ohne eine Antwort zu generieren. Verwende bei der späteren Generierung dasselbe Modell sowie dieselben Eingaben, Anweisungen und Tools.

Vergleiche die Tokenzahl mit dem Kontextfenster des gewählten Modells und lasse Platz für die Ausgabe. Da truncation auf "disabled" bleiben muss, entscheidet deine Anwendung, wann sie den Verlauf kürzt.

Bewahre beim Kürzen Funktionsaufrufe zusammen mit ihren zugehörigen Ergebnissen auf. Entferne keine beliebigen Elemente mitten aus einem Tool-Austausch.

Eine Tokenzahl ist noch keine Kostenschätzung. Prüfe die aktuellen API-Preise von Mistral, wenn du die Kosten wiederholter Anfragen und den Einfluss des Caches schätzt.

Fehler bei der Migration eingrenzen

Prüfe zuerst die Anfragekonfiguration, danach den Status und die Ausgabeelemente. Wähle die Prüfung, die zum Symptom passt.

Das SDK lehnt ein Schlüsselwortargument ab, bevor es die Anfrage sendet. Prüfe das installierte SDK und die Methodensignatur. Übergib bei der hier verwendeten Implementierung store, background und truncation innerhalb von additional_properties.
Die API lehnt die Anfrage ab. Kehre zum ersten Textbeispiel zurück. Prüfe Modell-ID, unterstützte Reasoning-Stufe und Parametertabelle. Ergänze optionale Felder einzeln, sobald die Anfrage funktioniert.
Das Modell verliert den bisherigen Kontext. Prüfe das nächste input-Array. Es muss frühere Nachrichten und vollständige Ausgabeelemente enthalten, nicht nur eine Antwort-ID.
Die Antwort enthält keinen Antworttext. Prüfe status, error und incomplete_details. Suche nach einem Funktionsaufruf, der noch auf Ausführung wartet. Ist das Ausgabebudget erschöpft, erhöhe es oder wähle eine niedrigere, vom Modell unterstützte Reasoning-Stufe.
Die Anfrage erreicht den falschen Pfad. Vergleiche die endgültige URL mit https://api.mistral.ai/v1/responses. Der Leitfaden zu Basis-URLs, Endpunkten und Verbindungsfehlern erklärt häufige Fehler beim Zusammensetzen des Pfads.

Für Streaming setzt du stream=True und verarbeitest Responses-Ereignisse. Das offizielle Python-Streaming-Beispiel liest jedes Ereignis über frame.data. Text kommt über response.output_text.delta; response.completed signalisiert den Abschluss.

Behandle auch response.failed, response.incomplete und error. Ein Textfragment allein belegt keinen erfolgreichen Abschluss. Die Hintergrundgenerierung ist deaktiviert, daher brauchst du hier keine Polling-Schleife.

Responses, Chat Completions oder Conversations wählen

Wähle Responses, wenn das Format mit einzelnen Elementen zu deiner Anwendung passt und du Verlauf sowie Funktionsausführung selbst steuern möchtest.

Was deine Anwendung braucht	Starte mit	Grund
Responses-Eingabe- und Ausgabeelemente sowie Responses-Streaming-Ereignisse	Responses API	Das Format bleibt erhalten; deine Anwendung verwaltet den Zustand und führt Funktionen aus.
Eine bestehende Integration auf Nachrichtenbasis	Chat Completions	Du kannst die nachrichtenbasierte Verarbeitung von Anfragen und Antworten beibehalten.
Gespeicherte Gespräche fortsetzen oder von Mistral ausgeführte Tools nutzen	Conversations API	Sie bietet Gesprächs-IDs und eine eigene Schnittstelle für serverseitige Tools.

Mistrals Chat-Completions-Leitfaden beschreibt das nachrichtenbasierte Format. Die Conversations-Referenz dokumentiert die Fortsetzung über conversation_id.

Für serverseitige Suche dokumentiert Mistral web_search und web_search_premium unter Conversations und Agents. Diese Funktion ist von den clientseitig ausgeführten Funktionen in Responses getrennt.

Wenn deine Anwendung gespeicherte Gespräche fortsetzen oder serverseitige Tools verwenden muss, prüfe Conversations, bevor du die Anfragen migrierst. Übernimmt deine Anwendung diese Aufgaben bereits selbst, prüfe zuerst Textanfrage, Folgerunde und den vollständigen Funktionsaufruf oben. Binde danach den gesamten Agenten an.