Die Anbindung der Mistral API ist kurz: eine Base URL, ein Key und ein Modellname genügen für den ersten Aufruf. Wirklich aufgehalten werden die meisten nicht vom Code, sondern von drei Details – ist die Adresse vollständig, ist der Modellname die aktuelle Version, und passen Key und Zugang zusammen?

Dieser Artikel beginnt beim offiziellen Zugang https://api.mistral.ai/v1, führt durch den ersten curl- und Python-Aufruf und ergänzt Streaming, JSON-Modus, Tool-Aufrufe, häufige Fehler sowie eine Checkliste für die Migration von der Direktverbindung zu ZSQH AI Gateway.

Hinweis: Mistral, Mistral AI und die zugehörigen Modellnamen sind Marken von Mistral AI. Dieser Artikel steht in keiner Zugehörigkeit zum Unternehmen Mistral AI; Modelle, Parameter und Kontingente können sich mit Versionen ändern. Maßgeblich sind die offizielle Dokumentation und die Seite Modellpreise.

1. Vor der Anbindung drei Dinge klären

Erstens die Herkunft des Keys. Ein offizieller Key wird unter https://console.mistral.ai erstellt und passt nur zum offiziellen Zugang; ein Gateway-Key wird in der ZSQH-Konsole erstellt und passt nur zum Gateway-Zugang.

Zweitens die Base URL. Der offizielle Zugang lautet https://api.mistral.ai/v1, der vollständige Pfad für Chat Completions ist https://api.mistral.ai/v1/chat/completions.

Drittens der Modellname. Mistral bietet sowohl -latest-Aliase als auch feste Versionsnamen mit Datum; beide bedeuten etwas anderes. Der Alias folgt der aktuellen Standardversion, während ein fester Versionsname für Regressionstests in der Produktion besser geeignet ist.

Diese drei Punkte zuerst klären, dann Code schreiben. In umgekehrter Reihenfolge pendelt man leicht zwischen 401 und 404 hin und her.

2. Base URL und Anfragepfad

Die Basisadresse der offiziellen API lautet:

https://api.mistral.ai/v1

Chat Completions nutzt POST /v1/chat/completions. Zwei Header sind erforderlich:

Authorization: Bearer <MISTRAL_API_KEY>
Content-Type: application/json

Mit dem offiziellen Python SDK genügt meist die Angabe von api_key; das SDK setzt die Adresse selbst zusammen. Mit dem OpenAI SDK wird base_url auf https://api.mistral.ai/v1 gesetzt, und das SDK hängt /chat/completions an.

Der häufigste Fehler hier ist doppeltes Anhängen: base_url enthält bereits /v1, der Pfad schreibt noch einmal /v1/chat/completions, und am Ende steht /v1/v1/chat/completions, was 404 liefert. Ein weiterer häufiger Fehler ist die Mischung von offizieller Adresse und Gateway-Adresse, die sich als 401 zeigt.

Der OpenAI-kompatible Zugang von ZSQH AI Gateway lautet https://ai.zhongshangqihang.com/v1 und folgt denselben Pfadregeln. Beim Wechsel nur base_url und api_key ändern und die beiden nicht kreuzen.

3. Modellnamen: Alias oder feste Version?

Stand Oktober 2026 verwendet der offizielle Schnellstart mistral-large-latest; die Dokumentation für Funktionsaufrufe nennt außerdem Aliase wie mistral-medium-latest und mistral-small-latest. Die Modellübersicht führt feste Versionsnamen wie mistral-large-4 (öffentliche Vorschau), mistral-large-2512, mistral-medium-3-5, mistral-small-2603 sowie Spezialmodelle wie ministral-14b-2512 und codestral-2508.

Der Unterschied:

  • Der -latest-Alias zeigt auf die aktuelle Standardversion und eignet sich für schnelle Validierung und unkritische Anwendungen; ändert sich die Standardversion, kann sich das Verhalten mitändern.
  • Ein fester Versionsname mit Datum oder Generation bezeichnet eine eindeutige Version, eignet sich für stabile Produktionsabläufe und erleichtert Release-Vergleiche sowie Rollbacks.

Die offiziellen Seiten werden nicht vollständig synchron aktualisiert; welche konkrete Version hinter einem Alias liegt, zeigt die Konsole oder die Modellliste zum Zeitpunkt des Aufrufs. Vor der Anbindung mit client.models.list() des SDK oder in der Konsole die aktuell verfügbaren Modelle prüfen und Modellnamen nicht aus alten Artikeln übernehmen.

Bei Nutzung von ZSQH AI Gateway richten sich die Modellnamen nach der Seite Modellpreise. Das Gateway kann Namen der Vorleistung abbilden; offizielle Modellnamen sind nicht automatisch unverändert nutzbar.

4. Erster curl-Aufruf: zuerst die minimale Anfrage

Zuerst Umgebungsvariablen setzen, dann eine kurze Anfrage senden. max_tokens klein halten, um Wartezeit und Störungen zu reduzieren.

export MISTRAL_API_KEY="dein-schluessel"

curl https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "model": "mistral-large-latest",
    "messages": [
      {"role": "user", "content": "Antworte nur mit OK"}
    ],
    "max_tokens": 32
  }'

Kommt 200 zurück und enthält choices[0].message.content Inhalt, stimmen Key, Base URL und Modellname. Bei 401 zuerst Key und Header prüfen; bei 404 zuerst Pfad und Modellname; bei 402 zuerst den Rechnungsstatus.

5. Python-Aufruf: Mistral SDK und OpenAI SDK

Das offizielle Python SDK heißt mistralai:

pip install mistralai

Minimales Beispiel:

import os
from mistralai.client import Mistral

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Du bist ein technischer Assistent und antwortest knapp."},
            {"role": "user", "content": "Erkläre in drei Sätzen, was eine Vektordatenbank ist."},
        ],
        max_tokens=256,
    )

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

Auf den Importpfad achten: Die aktuelle SDK-Dokumentation verwendet from mistralai.client import Mistral, manche älteren Versionen schreiben from mistralai import Mistral. Nicht beides mischen; bei ModuleNotFoundError zuerst installierte SDK-Version und offizielle Migrationshinweise prüfen.

Wer bestehenden OpenAI-SDK-Code wiederverwenden möchte, kann base_url auf https://api.mistral.ai/v1 und api_key auf den Mistral-Key setzen. Die Anfrageform der Mistral API ähnelt OpenAI Chat Completions stark, und diese Nutzung ist in der Community verbreitet. Die offizielle Dokumentation bewirbt die Mistral API jedoch nicht als „OpenAI-kompatibles Produkt“; Parameterumfang, Fehlerstruktur und Erweiterungsfelder richten sich nach der offiziellen API-Referenz. Vor dem Start mit echten Anfragen Punkt für Punkt prüfen und nicht annehmen, dass alle OpenAI-Parameter wirken.

6. Streaming

Chat-Oberflächen benötigen meist eine Ausgabe Zeichen für Zeichen. Das Mistral SDK nutzt client.chat.stream(...) und liefert einen Ereignisstrom; das Textinkrement steht in chunk.data.choices[0].delta.content:

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    stream = client.chat.stream(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": "Schreibe ein Python-Beispiel zum Einlesen einer CSV-Datei"}],
    )
    for chunk in stream:
        delta = chunk.data.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

Streaming-Antworten nutzen data-only SSE und enden mit data: [DONE]. Technisch sind drei Dinge zu behandeln: leere Inkremente, Verbindungsabbruch des Clients und Timeout-Wiederholungen. Nicht bei jedem Inkrement in die Datenbank schreiben; zuerst den vollständigen Text zusammensetzen und am Ende speichern.

7. JSON-Modus, strukturierte Ausgaben und Tool-Aufrufe

JSON-Modus verwendet response_format={"type": "json_object"}. Laut offizieller Dokumentation unterstützen alle aktuellen Modelle außer codestral-mamba diese Option. Die Ausgabe wird auf gültiges JSON beschränkt, content enthält jedoch JSON als Zeichenkette und muss weiterhin mit json.loads() geparst werden. Im Prompt ausdrücklich „JSON-Objekt zurückgeben“ und die erwarteten Felder nennen; nicht nur auf den Parameter verlassen.

Strukturierte Ausgaben eignen sich für feste Feldschemata. Das offizielle SDK bietet client.chat.parse(...), dem ein Pydantic-Modell übergeben werden kann und das ein geparstes Objekt zurückliefert. Bei rohem JSON Schema muss strict: true gesetzt und am Objekt additionalProperties: false angegeben werden. Je strenger das Schema, desto kleiner der Spielraum des Modells und desto einfacher die spätere Validierung.

Tool-Aufrufe nutzen das Array tools; tool_choice erlaubt auto, any und none, parallel_tool_calls steuert parallele Aufrufe. Das Modell liefert nur Toolnamen und Parameter; die Funktion führt das eigene Backend aus. Nach Erhalt der tool_calls die Assistant-Nachricht unverändert an die Nachrichtenliste anhängen, dann eine tool-Nachricht mit tool_call_id ergänzen und das Modell erneut aufrufen, bis die endgültige Antwort vorliegt. Mehrere Tool-Runden müssen in einer Schleife verarbeitet werden, nicht nur einmal.

8. Häufige Fehler und Fehlersuche

Fehler Häufige Ursache Behandlung
400 Request-Body ist kein gültiges JSON, model oder messages fehlt Zuerst den minimalen Body mit curl prüfen
401 Key fehlt, ist falsch oder abgelaufen oder passt nicht zum Zugang Bearer-Header und Key-Herkunft prüfen
402 Abrechnungsproblem: Guthaben, Ausgabenlimit, fehlgeschlagene Zahlung In der Konsole Abrechnung und Kontingent prüfen
403 Konto oder Workspace hat keine Rechte für das Modell Workspace, Modellrechte und Tarif prüfen
404 Falscher Pfad oder Modell/Ressource existiert nicht /v1/chat/completions und Modellnamen prüfen
422 JSON gültig, aber Parameterwerte ungültig Typen, Enum-Werte und Array-Längen prüfen
429 Rate-, Token- oder Parallelitätslimit überschritten Exponentieller Backoff, Retry-After lesen
500/503 Serverseitige Störung oder temporäre Überlast Kurz warten und wiederholen; bei Dauerstörung Statusseite prüfen

429 lässt sich nicht durch „mehr Keys anlegen“ umgehen. Offizielle Kontingente werden pro Konto, Workspace oder Tarif gezählt; mehrere Keys teilen meist dieselbe Grenze. Richtig sind weniger Parallelität, exponentieller Backoff, zeitliche Entzerrung von Stapelaufgaben und gegebenenfalls ein höherer Tarif.

9. Checkliste für die Migration vom offiziellen Zugang zum Gateway

  1. Bei ZSQH AI Gateway ein Konto anlegen, einen Gateway-Key erzeugen und getrennt vom offiziellen Key speichern.
  2. base_url auf https://ai.zhongshangqihang.com/v1 ändern und zugleich api_key austauschen.
  3. Anhand der Seite Modellpreise die Modellnamen neu prüfen und nicht unverändert die offiziellen Namen übernehmen.
  4. Den ursprünglichen Request-Body behalten, zuerst nicht unterstützte Erweiterungsparameter entfernen und dann einzeln wieder ergänzen.
  5. Mit derselben Sammlung echter Prompts Ausgabe, Dauer und usage vergleichen und drei bis sieben Tage beobachten.
  6. Die offizielle Direktverbindung als Ersatzkanal behalten und einen Rollback-Schalter vorbereiten.
  7. 401, 429, 5xx und Timeouts überwachen; bei Auffälligkeiten zuerst den Kanal wechseln, dann untersuchen.

Eine Migration ist nicht mit dem Ändern einer Adresse erledigt. Modellzuordnung, Parameterunterstützung, Streaming-Verhalten und Abrechnungslogik können abweichen; zuerst mit wenig Verkehr validieren, dann die Produktion umstellen.

Häufige Fragen

Gehört /v1 zur Base URL?

Der offizielle Zugang benötigt /v1, also https://api.mistral.ai/v1. Der vollständige Pfad für Chat Completions lautet https://api.mistral.ai/v1/chat/completions. Beim OpenAI SDK genügt base_url bis /v1; das SDK hängt /chat/completions selbst an, nicht noch einmal manuell schreiben.

-latest oder feste Version als Modellname?

Für schnelle Validierung eignet sich ein Alias wie mistral-large-latest, weil die Versionssuche entfällt. In der Produktion sind feste Versionsnamen mit Datum oder Generation besser: Das Verhalten ist reproduzierbar, und ein Rollback ist leichter. In beiden Fällen vor dem Start die aktuelle Verfügbarkeit in Dokumentation oder Konsole prüfen.

Lässt sich die Mistral API direkt mit dem OpenAI SDK nutzen?

Die Anfrageform ist ähnlich; mit base_url auf https://api.mistral.ai/v1 und einem Mistral-Key funktioniert sie üblicherweise. Die offizielle Seite bewirbt dies jedoch nicht als OpenAI-kompatibles Produkt, einzelne Parameter und Fehlerstrukturen können abweichen. Zuerst mit einer minimalen Anfrage validieren, dann die im Projekt verwendeten Erweiterungsparameter einzeln prüfen.

Warum liefert der JSON-Modus kein Objekt?

Der JSON-Modus liefert gültiges JSON, content ist aber eine Zeichenkette und muss selbst geparst werden. Zuerst json.loads(), dann Schema-Validierung. Ein Prompt, der JSON und Feldstruktur ausdrücklich verlangt, reduziert leere Felder und Formatabweichungen.

Passt ein offizieller Key zur ZSQH-Gateway-Adresse?

Nein. Der offizielle Key gehört zu https://api.mistral.ai/v1, der Gateway-Key zu https://ai.zhongshangqihang.com/v1. Bei einer Migration müssen Key und Base URL gemeinsam getauscht werden; eine Mischung liefert üblicherweise 401.

Weiterlesen: