DEV Community

Cover image for Mistral Medium 3.5 API: Anleitung zur Nutzung
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Mistral Medium 3.5 API: Anleitung zur Nutzung

Mistral hat Medium 3.5 am 29. April 2026 veröffentlicht. Für die gehostete API verwenden Sie die Modell-ID mistral-medium-3.5 und den Endpunkt POST https://api.mistral.ai/v1/chat/completions. Das Request-Format ist nah genug am OpenAI-Standard, dass Sie in vielen Codebasen nur base_url und model austauschen müssen. Relevant für Implementierungen sind vor allem: 256K Kontextfenster, native Bilderkennung, Funktionsaufrufe, JSON-Ausgabe, 24 Sprachen und 77,6 % auf SWE-Bench Verified.

Probieren Sie Apidog heute aus

Dieser Leitfaden zeigt den praktischen Einstieg: Authentifizierung, Parameter, Python- und Node-Beispiele, Streaming, Tool-Aufrufe, JSON-Modus, Bildereingabe, Fehlerbehandlung und ein Apidog-Setup, mit dem Sie Requests wiederholbar testen und Token-Kosten sichtbar machen. Weitere Modell-Guides: DeepSeek V4 API verwenden und GPT-5.5 API verwenden.

TL;DR

  • Endpunkt: POST https://api.mistral.ai/v1/chat/completions
  • Authentifizierung: Bearer-Token im Authorization-Header
  • Modell-ID: mistral-medium-3.5
  • Kontextfenster: 256K Tokens
  • Preise: 1,5 $ pro Million Eingabe-Tokens, 7,5 $ pro Million Ausgabe-Tokens
  • Features: Reasoning, Bilderkennung, Funktionsaufrufe, strukturierte JSON-Ausgabe, 24 Sprachen
  • Offene Gewichte: mistralai/Mistral-Medium-3.5-128B auf Hugging Face unter Modified MIT License mit Klausel für hohe Einnahmen
  • Benchmark: 77,6 % auf SWE-Bench Verified, 91,4 auf τ³-Telecom
  • Für wiederholbare Tests: Apidog herunterladen, API-Key als Secret speichern und usage pro Aufruf auswerten

Was sich in Medium 3.5 geändert hat

Medium 3 war ein reines Textmodell mit 128K Kontext. Medium 3.5 ist ein zusammengeführtes Flaggschiff-Modell: Instruction Following, Reasoning und Coding laufen über denselben Gewichtssatz. Sie müssen also nicht mehr zwischen Chat- und Reasoning-Checkpoint wechseln.

Neu oder relevant für die Implementierung:

  • 256K Kontext statt 128K
  • native Bilderkennung
  • native Funktionsaufrufe
  • strukturierte Ausgabe über JSON-Modus oder JSON-Schema
  • bessere Eignung für agentische Workflows und Code-Patching

Die wichtigsten Leistungsdaten:

  • SWE-Bench Verified: 77,6 %
  • τ³-Telecom: 91,4
  • Kontextfenster: 256K Tokens

Die Kosten sind deutlich höher als bei Medium 3. Medium 3 lag bei 0,40 $ pro Million Eingabe-Tokens und 2,00 $ pro Million Ausgabe-Tokens. Medium 3.5 kostet 1,5 $ pro Million Eingabe-Tokens und 7,5 $ pro Million Ausgabe-Tokens. Nutzen Sie Medium 3.5 deshalb gezielt für Aufgaben, bei denen Reasoning, Codequalität, Bilderkennung oder langer Kontext den Aufpreis rechtfertigen.

Voraussetzungen

Sie benötigen:

  1. Ein Mistral-Konto unter console.mistral.ai mit Zahlungsmethode oder Guthaben.
  2. Einen API-Key, idealerweise projektbezogen statt kontoweit.
  3. Ein SDK:
    • Python: mistralai oder OpenAI-kompatibles SDK
    • Node.js: @mistralai/mistralai oder OpenAI-kompatibles SDK
  4. Einen API-Client für wiederholbare Tests, z. B. Apidog, damit API-Keys nicht in Shell-Historien oder geteilten Requests landen.

API-Key lokal setzen:

export MISTRAL_API_KEY="..."
Enter fullscreen mode Exit fullscreen mode

Endpunkt und Authentifizierung

Der Chat-Completions-Endpunkt lautet:

POST https://api.mistral.ai/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

Minimaler curl-Request:

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Eine erfolgreiche Antwort enthält typischerweise:

  • id
  • choices
  • usage.prompt_tokens
  • usage.completion_tokens
  • usage.total_tokens

Fehler kommen in einer error-Hülle mit code und message. Die Struktur ist OpenAI-ähnlich genug, dass bestehende Error-Parser oft weiterverwendet werden können.

Wichtige Request-Parameter

Parameter Typ Werte Hinweis
model string mistral-medium-3.5 Erforderlich
messages array Rolle/Inhalt-Paare Erforderlich
temperature float 0 bis 1.5 0.7 allgemein, 0.3 für Code
top_p float 0 bis 1 Standard: 1.0
max_tokens int bis Kontextlimit Begrenzt Ausgabelänge
stream bool true, false Aktiviert SSE-Streaming
tools array OpenAI-Tool-Spezifikation Native Funktionsaufrufe
tool_choice string/object auto, any, none, spezifisches Tool any erzwingt Tool-Nutzung
response_format object JSON-Modus oder JSON-Schema Strukturierte Ausgabe
random_seed int beliebige ganze Zahl Reproduzierbarkeit
safe_prompt bool true, false Fügt Mistrals Safety-Prompt hinzu
presence_penalty float -2 bis 2 Bestraft wiederholte Themen
frequency_penalty float -2 bis 2 Bestraft wiederholte Tokens

Zwei Migrationsdetails sind wichtig:

  • OpenAI tool_choice="required" entspricht bei Mistral tool_choice="any".
  • OpenAI seed heißt bei Mistral random_seed.

Python-Client mit offiziellem Mistral-SDK

Installation:

pip install mistralai
Enter fullscreen mode Exit fullscreen mode

Beispiel:

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

content = response.choices[0].message.content
usage = response.usage

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

print(content)
print("Prompt tokens:", usage.prompt_tokens)
print("Completion tokens:", usage.completion_tokens)
print("Total tokens:", usage.total_tokens)
print("Estimated cost USD:", estimated_cost_usd)
Enter fullscreen mode Exit fullscreen mode

Python mit OpenAI-kompatiblem SDK

Wenn Ihre Codebasis bereits das OpenAI-SDK verwendet, reichen meistens base_url und 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": "Hello, Mistral."}
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Nutzen Sie diesen Weg, wenn Sie anbieterunabhängigen Code behalten wollen. Nutzen Sie das native mistralai-SDK, wenn Sie Mistral-spezifische Features sauber abbilden möchten.

Node.js mit offiziellem Mistral-SDK

Installation:

npm install @mistralai/mistralai
Enter fullscreen mode Exit fullscreen mode

Beispiel:

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);
Enter fullscreen mode Exit fullscreen mode

Node.js mit OpenAI-kompatiblem SDK 

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

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

Streaming-Antworten

Setzen Sie stream: true bzw. nutzen Sie die Streaming-Methode des SDK. Die Chunks folgen dem OpenAI-ähnlichen SSE-Format.

Python-Beispiel:

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)
Enter fullscreen mode Exit fullscreen mode

Für CLI-Tools, Chat-UIs und längere Antworten sollten Sie Streaming standardmäßig aktivieren, damit Nutzer nicht auf die vollständige Antwort warten müssen.

Tool-Aufrufe

Medium 3.5 unterstützt native Funktionsaufrufe. Sie definieren verfügbare Funktionen im tools-Array. Das Modell entscheidet dann, ob und mit welchen Argumenten ein Tool aufgerufen wird.

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)
print(tool_call.function.arguments)
Enter fullscreen mode Exit fullscreen mode

Typischer Ablauf:

  1. Request mit tools senden.
  2. Tool-Call aus response.choices[0].message.tool_calls lesen.
  3. Funktion lokal ausführen.
  4. Ergebnis als role: "tool"-Message anhängen.
  5. API erneut aufrufen, damit das Modell mit dem Tool-Ergebnis antwortet.

Das Muster ist praktisch identisch mit OpenAI-Tool-Loops. Der Unterschied: Wenn Sie einen Tool-Aufruf erzwingen wollen, verwenden Sie bei Mistral tool_choice="any".

JSON-Modus und strukturierte Ausgabe

Für beliebiges gültiges JSON:

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {
            "role": "user",
            "content": "Return a JSON object with title and summary.",
        }
    ],
    response_format={"type": "json_object"},
)
Enter fullscreen mode Exit fullscreen mode

Für schema-validierte Ausgabe übergeben Sie ein JSON-Schema:

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

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Verwenden Sie JSON-Schema, wenn downstream Code harte Struktur erwartet. Verwenden Sie json_object, wenn Sie nur gültiges JSON brauchen und selbst mit Pydantic, Zod oder ähnlichen Tools validieren.

Bildereingabe

Medium 3.5 kann Bildinhalte zusammen mit Text im messages-Array verarbeiten.

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

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Bildeingaben werden als Eingabe-Tokens abgerechnet. Der konkrete Token-Verbrauch hängt von der Auflösung ab und erscheint in usage.prompt_tokens.

Für produktive Bild-Workloads:

  • relevante Bereiche vorher zuschneiden
  • unnötig hohe Auflösungen vermeiden
  • Token-Verbrauch pro Bild loggen
  • bei Videos nur relevante Frames senden

Apidog-Sammlung für wiederholbare Tests erstellen

Für manuelle Iteration mit curl verlieren Sie schnell Überblick über Prompts, Header, Varianten und Kosten. Ein stabiler Workflow in Apidog:

  1. Apidog herunterladen und ein Projekt erstellen.
  2. Eine Umgebung anlegen.
  3. MISTRAL_API_KEY als geheime Variable speichern.
  4. BASE_URL auf https://api.mistral.ai/v1 setzen.
  5. Eine POST-Anfrage an {{BASE_URL}}/chat/completions erstellen.
  6. Header setzen: 
Authorization: Bearer {{MISTRAL_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. Body als Vorlage speichern: 
{
  "model": "mistral-medium-3.5",
  "messages": [
    {
      "role": "user",
      "content": "Explain dense merged checkpoints in two sentences."
    }
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}
Enter fullscreen mode Exit fullscreen mode
  1. model, temperature, max_tokens und tool_choice parametrisieren.
  2. In jedem Response den usage-Block prüfen.
  3. Kosten pro Request berechnen: 
prompt_tokens * 1.5 / 1_000_000
+ completion_tokens * 7.5 / 1_000_000
Enter fullscreen mode Exit fullscreen mode

Wenn Sie bereits eine DeepSeek V4 API-Sammlung in Apidog verwenden, können Sie sie duplizieren, BASE_URL auf https://api.mistral.ai/v1 setzen und model auf mistral-medium-3.5 ändern. Dasselbe Muster funktioniert für den Vergleich mit GPT-5.5.

Fehlerbehandlung

Häufige Fehlercodes:

Code Bedeutung Behebung
400 Ungültige Anfrage JSON, messages und tools validieren
401 Ungültiger Schlüssel Key unter console.mistral.ai neu generieren
402 Zahlung erforderlich Konto aufladen oder Zahlungsmethode hinzufügen
403 Modell nicht erlaubt Projektumfang und Modell-ID prüfen
422 Parameter außerhalb des Bereichs max_tokens, tool_choice oder Schema prüfen
429 Ratenbegrenzung Exponentielles Backoff mit Jitter
500 Serverfehler Einmal wiederholen, dann Status prüfen
503 Überlastet Warten oder auf Mistral Medium 3 zurückfallen

Ein einfacher Retry-Wrapper sollte nur temporäre Fehler automatisch wiederholen:

import time
import random

def retryable_status(status_code: int) -> bool:
    return status_code == 429 or 500 <= status_code < 600

def backoff_sleep(attempt: int) -> None:
    base = min(30, 2 ** attempt)
    jitter = random.uniform(0, 1)
    time.sleep(base + jitter)
Enter fullscreen mode Exit fullscreen mode

Wiederholen Sie 4xx-Fehler nicht blind. Sie weisen meistens auf ungültige Parameter, fehlende Berechtigungen oder fehlerhafte Tool-Schemas hin.

Kostenkontrolle in der Praxis

Medium 3.5 ist deutlich teurer als Medium 3. Deshalb sollten Sie Routing und Token-Budgets bewusst implementieren.

1. Standardmäßig günstiger routen

Nutzen Sie Medium 3 für einfache oder hochvolumige Aufgaben. Eskalieren Sie nur zu Medium 3.5, wenn:

  • ein Validator fehlschlägt
  • der günstige Durchlauf unsicher ist
  • Bilderkennung benötigt wird
  • langer Kontext wirklich erforderlich ist
  • Code- oder Agentenqualität wichtiger als Kosten ist

2. max_tokens begrenzen

Die Ausgabe ist mit 7,5 $ pro Million Tokens die teurere Seite.

{
  "max_tokens": 2048
}
Enter fullscreen mode Exit fullscreen mode

Das 256K-Fenster ist primär für große Eingaben gedacht, nicht für unbegrenzte Ausgaben.

3. System-Prompts kürzen

Jeder System-Prompt wird bei jedem Request erneut abgerechnet. Wenn Sie eine 2K-Token-Präambel auf 500 Tokens kürzen, sparen Sie bei hohem Volumen 75 % dieses Eingabeanteils.

4. usage loggen

Speichern Sie pro Request:

  • prompt_tokens
  • completion_tokens
  • total_tokens
  • geschätzte USD-Kosten
  • Modell-ID
  • Request-Typ oder Feature-Name

So erkennen Sie Prompts, die plötzlich sehr lange Antworten erzeugen.

5. Bilder selektiv senden

Bild-Tokens können schnell teuer werden. Schneiden Sie irrelevante Bereiche weg und senden Sie nur die niedrigste Auflösung, die für die Aufgabe noch reicht.

Vergleich mit anderen Mistral-Stufen

Mistrals Angebot Ende April 2026:

Modell Kontext Eingabe $/Mio. Ausgabe $/Mio. Bilderkennung Am besten für
mistral-small 32K $0.10 $0.30 Nein Klassifizierung, leichter Chat
mistral-medium-3 128K $0.40 $2.00 Nein Hoher Durchsatz, längere Chats
mistral-medium-3.5 256K $1.5 $7.5 Ja Reasoning, Code, Bilderkennung, Agenten
mistral-large 128K $2.00 $6.00 Begrenzt Frontier-Tier Text-Reasoning

Medium 3.5 kombiniert langen Kontext, Bilderkennung und zusammengeführte Reasoning-Fähigkeiten. Wählen Sie es nach Workload, nicht nach Modellrang.

Migration von OpenAI oder DeepSeek

Die Migration ist meistens eine Änderung der Basis-URL und Modell-ID.

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Achten Sie auf diese Unterschiede:

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

- seed=123
+ random_seed=123
Enter fullscreen mode Exit fullscreen mode

Vor dem Umschalten in Produktion:

  1. Bestehende Testsuite gegen Mistral laufen lassen.
  2. Kritische Prompts in Apidog speichern.
  3. Antworten verschiedener Anbieter nebeneinander vergleichen.
  4. Einen Shadow-Traffic-Test durchführen, bevor Live-Traffic umgeleitet wird.

Praktische Anwendungsfälle

Medium 3.5 lohnt sich besonders für Aufgaben, bei denen ein günstigeres Modell häufiger Nacharbeit erzeugt.

Code-Review-Assistenten

Der SWE-Bench Verified Score von 77,6 % und das 256K-Kontextfenster passen gut zu PR-Reviews, bei denen Diff, Tests und umgebende Dateien gemeinsam betrachtet werden müssen.

Dokumenten-Q&A

Das 256K-Fenster kann viele Verträge, RFPs und Richtliniendokumente ohne Chunking abdecken. Trotzdem sollten Sie lange Dokumente nur dann vollständig senden, wenn Retrieval oder Zusammenfassungen nicht reichen.

Multimodale Extraktion

Für Belege, Screenshots oder Diagramme können Sie Bildinhalt und strukturierte Ausgabe in einem Request kombinieren, statt OCR und Textmodell getrennt auszuführen.

Agenten mit Tool-Aufrufen

Native Funktionsaufrufe und der τ³-Telecom-Score helfen bei mehrstufigen Workflows, in denen das Modell entscheiden muss, ob es direkt antwortet, ein Tool nutzt oder Rückfragen stellt.

FAQ

Was ist die Modell-ID für Mistral Medium 3.5?

Für die gehostete API:

mistral-medium-3.5
Enter fullscreen mode Exit fullscreen mode

Für offene Gewichte auf Hugging Face:

mistralai/Mistral-Medium-3.5-128B
Enter fullscreen mode Exit fullscreen mode

Wenn Sie selbst mit vLLM oder Unsloth hosten, verwenden Sie die Hugging-Face-ID. Für die Mistral-API verwenden Sie die kurze Modell-ID.

Ist Medium 3.5 OpenAI-kompatibel?

Nahezu, aber nicht vollständig. Endpunktstruktur, Header und viele Parameter sind kompatibel genug, dass OpenAI-SDKs mit base_url="https://api.mistral.ai/v1" funktionieren.

Die wichtigsten Unterschiede:

  • tool_choice="any" statt OpenAI required
  • random_seed statt OpenAI seed

Kann ich Medium 3.5 lokal ausführen?

Ja. Die Gewichte sind unter einer Modified MIT License mit Klausel für hohe Einnahmen verfügbar. Wegen der 128B Parameter benötigen Sie erheblichen GPU-Speicher. Quantisierte GGUF-Builds wie unsloth/Mistral-Medium-3.5-128B-GGUF laufen auf einer einzelnen High-End-Verbraucherkarte. Die Muster aus DeepSeek V4 lokal ausführen lassen sich übertragen.

Unterstützt Medium 3.5 Streaming mit Tool-Aufrufen?

Ja. Tool-Call-Argumente werden beim Streaming inkrementell unter delta.tool_calls zurückgegeben. Die Fragmente ergeben am Ende des Streams ein vollständiges JSON-Objekt.

Wie zähle ich Eingabe-Tokens vor dem Senden?

Verwenden Sie den Tokenizer aus dem Python-Paket mistral-common. Das ist derselbe Tokenizer, den die API verwendet, sodass die Zählung mit usage.prompt_tokens übereinstimmen sollte.

Welche Kontextlänge sollte ich in Produktion einplanen?

256K ist die Obergrenze, aber Kosten skalieren linear. Ein 200K-Token-Request kostet bereits 0,30 $ nur für die Eingabe. Viele Produktions-Workloads sollten unter 32K bleiben und langen Kontext nur bei echtem Bedarf nutzen.

Gibt es eine kostenlose Stufe?

Mistral bewirbt keine permanente kostenlose Stufe. Neue Konten haben typischerweise ein kleines Testguthaben. Für kostenlose Experimente mit ähnlichen Modellstufen siehe DeepSeek V4 API kostenlos nutzen.

Top comments (0)