Mistral Medium 3.5 API: Anleitung zur Nutzung

Mistral veröffentlichte Medium 3.5 am 29. April 2026. Die API-Modell-ID ist mistral-medium-3.5, der Endpunkt ist https://api.mistral.ai/v1/chat/completions, und die Anfragestruktur ist dem OpenAI-Standard ähnlich genug, dass der Austausch von Basis-URLs von einem anderen Anbieter nur eine Codezeile erfordert. Die wichtigsten Zahlen sind ein 256K Kontextfenster, native Bilderkennung, Funktionsaufrufe, Unterstützung für 24 Sprachen und 77,6 % bei SWE-Bench Verified; Zahlen, die es in denselben Gesprächskontext wie GPT-5.5 und DeepSeek V4 für die Art von agentischen, codeintensiven Aufgaben stellen, die die meisten Teams derzeit implementieren.

Dieser Leitfaden behandelt die Authentifizierung, jeden wichtigen Parameter, Python- und Node-Beispiele, Bildereingabe, Tool-Aufrufe, JSON-Modus, Streaming, Fehlerbehandlung und einen Apidog-Workflow, der die Kosten sichtbar hält, während Sie Prompts iterieren. Vergleichbare Modellleitfäden finden Sie unter wie man die DeepSeek V4 API verwendet und wie man die GPT-5.5 API verwendet.

TL;DR

• Endpunkt: POST https://api.mistral.ai/v1/chat/completions. Die Authentifizierung erfolgt über ein Bearer-Token im standardmäßigen Authorization-Header.
• Modell-ID: mistral-medium-3.5. Kontextfenster: 256K Tokens. Preise: 1,5 $ pro Million Eingabe-Tokens, 7,5 $ pro Million Ausgabe-Tokens.
• 128B dichtes, zusammengeführtes Modell mit Argumentation, Bilderkennung, nativen Funktionsaufrufen, strukturierter JSON-Ausgabe und Unterstützung für 24 Sprachen.
• Offene Gewichte sind auf Hugging Face als mistralai/Mistral-Medium-3.5-128B unter einer Modified MIT License mit einer Klausel für hohe Einnahmen verfügbar.
• SWE-Bench Verified: 77,6 %. τ³-Telecom: 91,4. Stark bei der Codierung, Befolgung von Anweisungen und der Nutzung von Tools.
• Laden Sie Apidog herunter, um Medium 3.5 gegen Ihr aktuelles Modell zu testen, speichern Sie den Schlüssel als geheime Variable und verfolgen Sie die Kostenunterschiede pro Aufruf.

Was hat sich in Medium 3.5 geändert

Medium 3 wurde Anfang des Jahres als reines Textmodell mit einem 128K Kontext ausgeliefert. Medium 3.5 ist ein völlig anderes Kaliber. Es ist Mistrals erstes Flaggschiff-Merged-Modell: Anweisungsbefolgung, Argumentation und Codierung leben in einem einzigen Satz von Gewichten, sodass Sie nicht mehr zwischen einem Chat-Checkpoint und einem Argumentations-Checkpoint wählen müssen. Bilderkennung ist nativ, der Kontext verdoppelt sich auf 256K, und Funktionsaufrufe sind auf Modellebene integriert, anstatt über eine separate API-Oberfläche angeflanscht zu werden.

Drei Zahlen untermauern das Upgrade. SWE-Bench Verified mit 77,6 % liegt im selben Bereich wie die führenden Frontier-Modelle für Code-Patching. τ³-Telecom mit 91,4 platziert es vor den meisten Generalistenmodellen bei mehrstufigen agentischen Dialogen. Der 256K Kontext deckt eine vollständige mittelgroße Codebasis oder ein mehrstündiges Transkript ohne Kürzung ab. Keine davon sind Marketing-Rundungsfehler; sie zeigen direkt auf, ob das Modell Ihre Aufgabe ohne einen zweiten Durchlauf erledigen kann.

Die Preisverschiebung ist der Teil, den man budgetieren muss. Medium 3 lag bei 0,40 $ pro Million Eingabe-Tokens und 2,00 $ pro Million Ausgabe-Tokens. Medium 3.5 springt auf 1,5 $ für die Eingabe und 7,5 $ für die Ausgabe, etwa um das Vierfache. Das sind die Kosten des Merged-Checkpoint-Ansatzes plus Bilderkennung plus des längeren Kontexts. Betrachten Sie das ältere Medium 3 als die Option für hohen Durchsatz und Medium 3.5 als die „Ich brauche diese Antwort sofort richtig“-Stufe.

Voraussetzungen

Vor dem ersten Aufruf sind vier Dinge zu beachten.

• Ein Mistral-Konto unter console.mistral.ai mit hinterlegter Zahlungsmethode. Ohne Guthaben geben Aufrufe 402 Payment Required zurück.
• Ein API-Schlüssel, der auf das Projekt beschränkt ist, für das Sie Rechnungen erhalten. Projektschlüssel sind sicherer als Kontoschlüssel für alles, was in Produktion geht.
• Ein SDK. Mistral veröffentlicht ein offizielles mistralai-Paket für Python und JavaScript, und das OpenAI SDK funktioniert mit demselben Endpunkt durch einen Basis-URL-Austausch.
• Ein API-Client, der Anfragen wiedergeben kann, ohne Ihre Terminalhistorie zu überfluten. Curl funktioniert für den ersten Aufruf. Danach verwenden Sie Apidog, um den Schlüssel aus Ihrer Shell-Historie und die Anforderungs-Bodies unter Versionskontrolle zu halten.

Exportieren Sie den Schlüssel einmal:

export MISTRAL_API_KEY="..."

Endpunkt und Authentifizierung

Mistrals La Plateforme legt alles über eine Basis-URL offen.

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

Die Authentifizierung erfolgt über ein Bearer-Token im Authorization-Header. Die minimal funktionierende Anfrage sieht so aus:

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": "Explain dense merged checkpoints in two sentences."}
    ]
  }'

Eine erfolgreiche Antwort gibt einen JSON-Body mit einem choices-Array, einem usage-Block, aufgeschlüsselt in prompt_tokens, completion_tokens und total_tokens, und einer id zurück, die Sie zur Nachverfolgung weiterleiten können. Fehler geben eine error-Hülle mit code und message zurück. Die Struktur entspricht der OpenAI-Struktur genau genug, dass jeder Fehler-Parser, den Sie bereits besitzen, ohne Modifikation funktioniert.

Anforderungsparameter

Jedes Feld bezieht sich entweder auf Kosten oder Verhalten. Hier ist die Zuordnung für mistral-medium-3.5.

Zwei kleine Unterschiede verwirren die Leute bei der Migration von OpenAI: tool_choice="any" bedeutet „einen Tool-Aufruf erzwingen“ (OpenAI verwendet required), und der Seed-Parameter ist random_seed (OpenAI verwendet seed). Alles andere stimmt überein.

Python-Client

Mistral liefert ein offizielles Python-SDK aus, das der API eins zu eins entspricht.

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": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

print("Content:", response.choices[0].message.content)
print("Total tokens:", response.usage.total_tokens)
print("Cost estimate (USD):",
      response.usage.prompt_tokens * 1.5 / 1_000_000 +
      response.usage.completion_tokens * 7.5 / 1_000_000)

Wenn Sie bereits eine OpenAI-ähnliche Codebasis haben, funktioniert das OpenAI Python SDK mit dem Mistral-Endpunkt mit zwei Änderungen: der Basis-URL und der Modell-ID.

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": "Hello, Mistral."}],
)

Der OpenAI-SDK-Weg ist der Weg des geringsten Widerstands für Teams, die anbieterunabhängigen Code ausführen; das native mistralai-SDK ist der Weg, der Mistral-spezifische Funktionen sauber offenlegt, wählen Sie also danach, ob Sie Bilderkennung und strukturierte Ausgaben stark nutzen möchten.

Node-Client

Gleiche zweigleisige Wahl bei Node. Das native SDK:

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: "Explain dense merged checkpoints in plain English." },
  ],
  temperature: 0.7,
});

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

Der OpenAI-SDK-Weg, zur Parität mit bestehendem Code:

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

Streaming-Antworten

Setzen Sie stream: true und iterieren Sie die SSE-Chunks. Die Struktur entspricht der von OpenAI genau, und die kumulative Reasoning-Trace ist in choices[].delta.content verschachtelt, anstatt in ein separates Sidecar-Feld aufgeteilt zu werden.

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Stream a 300-word essay on merged checkpoints."}],
)

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

Für die Terminalausgabe ist die Mistral-Stream-Geschwindigkeit schneller als DeepSeek V4-Pro bei gleicher Prompt-Länge und ungefähr gleichauf mit GPT-5.5, basierend auf Side-by-Side-Läufen durch den Apidog-Antwort-Viewer.

Tool-Aufrufe

Medium 3.5 wird mit nativen Funktionsaufrufen ausgeliefert. Funktionen, die im tools-Array definiert sind, werden aufrufbar, und das Modell entscheidet, wann sie aufgerufen werden sollen.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Return the current weather for a city.",
        "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": "Weather in Lagos in Celsius?"}],
    tools=tools,
    tool_choice="auto",
)

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

Von dort aus führen Sie die Funktion lokal aus, fügen das Ergebnis als role: "tool"-Nachricht an und rufen die API erneut auf, um die Schleife fortzusetzen. Das Muster ist identisch mit der OpenAI-Tool-Nutzungsschleife. Die agentische Fähigkeit zeigt sich im τ³-Telecom-Score; in der Praxis führt dies zu weniger verschwendeten Schritten bei mehrstufigen Workflows, bei denen das Modell entscheiden muss, ob es ein Tool aufruft, den Benutzer fragt oder direkt antwortet.

JSON-Modus und strukturierte Ausgabe

Für schemavalidierte Ausgabe übergeben Sie ein JSON-Schema im 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": "Reply with a single JSON object matching the schema."},
        {"role": "user", "content": "Summarize today's Mistral Medium 3.5 release."},
    ],
    response_format=schema,
)

Der strikte Modus erzwingt das Schema zur Dekodierungszeit, sodass Sie keinen Pydantic- oder Zod-Parseschritt auf Clientseite hinzufügen müssen; die Antwort entspricht entweder dem Schema oder der Aufruf schlägt mit einem strukturierten Fehler fehl. Für Fälle mit geringerem Reibungsverlust, in denen Sie nur gültiges JSON beliebiger Form benötigen, setzen Sie response_format={"type": "json_object"} und validieren Sie auf Clientseite.

Bildereingabe

Der Bilderkennungs-Encoder von Medium 3.5 wurde von Grund auf trainiert, um variable Bildgrößen und Seitenverhältnisse zu verarbeiten; Sie müssen nichts vorab skalieren. Übergeben Sie Bildinhalte zusammen mit Text im messages-Array.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What is in this image and what is it doing wrong?"},
            {"type": "image_url", "image_url": "https://example.com/diagram.png"},
        ],
    }],
)

Bildeingaben werden als Eingabe-Tokens zum gleichen Tarif von 1,5 $ pro Million abgerechnet; die genaue Token-Anzahl pro Bild variiert mit der Auflösung und wird im Feld usage.prompt_tokens angegeben. Für Bild-Workloads mit hohem Volumen protokollieren Sie frühzeitig die Token-Kosten pro Bild und entscheiden Sie, ob Sie vor der Skalierung komprimieren, zuschneiden oder Frames überspringen möchten.

Die Sammlung in Apidog erstellen

Anfragen vom Terminal wiederzugeben verbraucht Credits und verbirgt die Unterschiede zwischen den Läufen. Der Workflow, der den echten Einsatz übersteht:

1. Laden Sie Apidog herunter und erstellen Sie ein Projekt.
2. Fügen Sie eine Umgebung hinzu, in der {{MISTRAL_API_KEY}} als geheime Variable gespeichert ist, damit sie niemals in gemeinsamen Exporten landet.
3. Speichern Sie eine POST-Anfrage an {{BASE_URL}}/chat/completions mit dem Header Authorization: Bearer {{MISTRAL_API_KEY}}.
4. Parametrisieren Sie model, temperature und tool_choice, damit Sie A/B-Tests über Varianten hinweg durchführen können, ohne Anfragen zu duplizieren.
5. Verwenden Sie den Antwort-Viewer, um usage bei jedem Lauf zu überprüfen. Fügen Sie ein kleines Post-Response-Skript hinzu, das prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000 multipliziert, damit die Kosten pro Aufruf neben jedem Ergebnis angezeigt werden.

Teams, die bereits die passende DeepSeek V4 API-Sammlung in Apidog ausführen, können diese duplizieren, die Basis-URL auf https://api.mistral.ai/v1 ändern, die Modell-ID auf mistral-medium-3.5 anpassen und in wenigen Minuten direkte Prompts über beide Anbieter hinweg ausführen. Das gleiche Muster gilt für den Vergleich mit GPT-5.5.

Fehlerbehandlung

Die Fehlerhülle folgt den OpenAI-Konventionen sehr genau. Die Codes, auf die Sie zuerst stoßen werden:

Umschließen Sie Aufrufe in einen Wiederholungs-Helfer, der 429 und 5xx mit exponentiellem Backoff behandelt. Wiederholen Sie 4xx-Fehler nicht automatisch; das sind Logikfehler, keine vorübergehenden Ausfälle. Apidogs Antwort-Viewer macht es trivial, eine fehlerhafte tools-Payload zu erkennen, da das beanstandete Feld im Anforderungs-Body neben dem Fehler hervorgehoben wird.

Muster zur Kostenkontrolle

Der 4-fache Preissprung von Medium 3 auf Medium 3.5 bestraft faules Routing. Fünf Muster halten die Rechnung vorhersehbar.

1. Standardmäßig Medium 3, bei Bedarf auf Medium 3.5 eskalieren. Führen Sie einen günstigen ersten Durchlauf mit Medium 3 aus und leiten Sie schwierige Prompts nur dann an 3.5 weiter, wenn der günstige Durchlauf geringes Vertrauen zurückgibt oder einen Validator nicht besteht.
2. max_tokens begrenzen. Die meisten Antworten passen in 2.000 Ausgabe-Tokens. Das 256K Kontextfenster ist für große Eingabemengen, nicht für große Ausgabemengen; die Ausgabe ist mit 7,5 $ pro Million die teure Seite.
3. System-Prompts schlank halten. Jeder System-Prompt-Token wird bei jedem Aufruf abgerechnet; das Kürzen einer 2K-Token-Präambel auf 500 Tokens senkt Ihre Eingaberechnung um 75 % bei einem Endpunkt mit hohem Volumen.
4. usage bei jedem Aufruf protokollieren. Senden Sie prompt_tokens, completion_tokens und die geschätzten USD-Kosten pro Aufruf an Ihren Observability-Stack. Ein Alarm bei einem plötzlichen Anstieg der Ausgabe-Tokens fängt Prompts ab, die in den Bereich des Chain-of-Thought abgedriftet sind.
5. Bilderkennung selektiv einsetzen. Bild-Tokens summieren sich schnell. Schneiden Sie vor dem Senden auf die relevante Region zu und skalieren Sie auf die niedrigste Auflösung herunter, die die Frage noch beantwortet.

Vergleich von Medium 3.5 mit anderen Mistral-Stufen

Mistrals Angebot Ende April 2026:

Medium 3.5 ist die einzige Stufe, die den langen Kontext, die Bilderkennung und die zusammengeführten Argumentationsfähigkeiten kombiniert. Die Large-Stufe bietet eine andere Kostenkurve (günstigere Ausgabe, teurere Eingabe) und übertrifft 3.5 bei einigen reinen Text-Benchmarks; wählen Sie nach Workload, nicht nach Stufenname.

Migration von einem anderen Anbieter

Die Migration ist hauptsächlich eine Änderung der Basis-URL.

Von OpenAI:

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

Von DeepSeek:

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

Zwei Fallstricke, auf die man achten sollte:

• tool_choice="required" bei OpenAI wird zu tool_choice="any" bei Mistral.
• seed wird zu random_seed.

Führen Sie den Diff durch Ihre bestehende Testsuite, bevor Sie den Produktions-Traffic umschalten. Besser noch, spiegeln Sie den Traffic einen Tag lang im Shadow-Modus zu Mistral, protokollieren Sie beide Antworten und vergleichen Sie sie in Apidog, bevor Sie sie übernehmen.

Anwendungsfälle in der Praxis

Einige Muster, bei denen sich Medium 3.5 bereits bezahlt macht:

• Code-Review-Assistenten. Der SWE-Bench Verified Score von 77,6 % und der 256K-Kontext machen es stark bei PR-Reviews, wo das Modell den vollständigen Diff plus umgebende Dateien sehen muss.
• Dokumenten-Q&A über lange PDFs. Der 256K-Kontext deckt die meisten Verträge, Ausschreibungen (RFPs) und Richtliniendokumente in einem Aufruf ohne Chunking ab.
• Multimodale Datenextraktion. Strukturierte Felder aus Belegen, Screenshots oder Diagrammen in einem Aufruf zu extrahieren, ist besser als OCR plus ein separates Textmodell auszuführen.
• Agenten-Schleifen mit Tool-Aufrufen. Die nativen Funktionsaufrufe und der hohe τ³-Telecom-Score reduzieren die Anzahl der „Tool-Aufruf fehlgeschlagen, mit korrigiertem JSON erneut versuchen“-Zyklen, die Tokens verbrauchen.

FAQ

Was ist die Modell-ID für Mistral Medium 3.5 in der API?mistral-medium-3.5. Der Hugging Face Checkpoint wird als mistralai/Mistral-Medium-3.5-128B veröffentlicht. Wenn Sie die offenen Gewichte selbst mit vLLM oder Unsloth bereitstellen, verwenden Sie die Hugging Face ID. Für die gehostete API verwenden Sie die kurze ID.

Ist Medium 3.5 OpenAI-kompatibel?Nah, aber nicht identisch. Die Endpunktstruktur, Header und die meisten Parameter stimmen genau mit OpenAI überein, sodass die OpenAI Python und Node SDKs mit einer Basis-URL-Überschreibung funktionieren. Die beiden Abweichungen sind tool_choice="any" (vs. OpenAI’s required) und random_seed (vs. OpenAI’s seed).

Kann ich Medium 3.5 lokal ausführen?Ja. Die Gewichte sind offen unter einer Modified MIT License mit einer Klausel für hohe Einnahmen. Die 128B-Parameteranzahl bedeutet, dass Sie erheblichen GPU-Speicher benötigen; quantisierte GGUF-Builds von unsloth/Mistral-Medium-3.5-128B-GGUF laufen auf einer einzigen High-End-Verbraucherkarte. Die Muster aus wie man DeepSeek V4 lokal ausführt lassen sich direkt übertragen.

Unterstützt es Streaming mit Tool-Aufrufen?Ja. Streaming gibt Tool-Aufruf-Argument-Fragmente inkrementell unter delta.tool_calls zurück, im gleichen Format wie OpenAIs gestreamtes Tool-Aufruf-Format. Die Fragmente sammeln sich zu einem vollständigen JSON-Objekt an, sobald der Stream schließt.

Wie zähle ich Eingabe-Tokens vor dem Senden?Verwenden Sie den Tokenizer des Python-Pakets mistral-common für genaue Zählungen. Es ist derselbe Tokenizer, den die API verwendet, sodass Byte-für-Byte-Zählungen mit usage.prompt_tokens in der Antwort übereinstimmen.

Welche Kontextlänge sollte ich für die Produktion einplanen?Das 256K-Fenster ist die Obergrenze, aber die Preise skalieren linear. Ein 200K-Token-Aufruf kostet allein 0,30 $ für die Eingabe, bevor das Modell überhaupt mit der Generierung beginnt. Die meisten Produktions-Workloads passen bequem unter 32K; greifen Sie nur dann zum langen Kontext, wenn die Aufgabe ihn wirklich benötigt.

Gibt es eine kostenlose Stufe?Mistral bewirbt keine permanente kostenlose Stufe, aber neue Konten kommen typischerweise mit einem kleinen Testguthaben. Für anhaltende kostenlose Experimente mit ähnlichen Stufenmodellen siehe wie man die DeepSeek V4 API kostenlos nutzt.