Die Textmodelle von MiniMax bieten eine OpenAI-kompatible Schnittstelle. Bestehende OpenAI-SDK-Projekte müssen meist nur drei Stellen ändern: Base URL, API-Schlüssel und Modellname. In der Praxis scheitert die Integration jedoch häufig an regionalen Domains, Groß- und Kleinschreibung der Modellnamen, Reasoning-Inhalten und Token-Parametern. Dieser Beitrag folgt der Reihenfolge Adresse, Modell, Aufruf, Fehlersuche, Migration.

Das Ergebnis vorweg: Die offizielle OpenAI-kompatible Adresse endet auf /v1, der Chat-Endpunkt lautet /v1/chat/completions. Modellnamen müssen exakt der offiziellen Dokumentation entsprechen. Neuer Code sollte max_completion_tokens verwenden und für Reasoning-Inhalte Ausgabebudget einplanen.

Hinweis: MiniMax ist eine Marke des jeweiligen Inhabers; dieser Beitrag dient der technischen Erläuterung. Modellnamen, Schnittstellen, Kontextfenster und Limits richten sich nach der offiziellen MiniMax-Dokumentation und der Preisübersicht. Prüfen Sie Beispielnamen in der Konsole, bevor sie produktiv verwendet werden.

1. Base URL: zuerst Region und Protokoll wählen

MiniMax betreibt derzeit eine chinesische und eine internationale Seite sowie drei Einstiege: OpenAI-kompatibel, Anthropic-kompatibel und nativ. Die häufigste Wahl ist OpenAI-kompatibel: international https://api.minimax.io/v1, China https://api.minimax.cn/v1, Chat-Endpunkt POST /v1/chat/completions.

Wer das Anthropic SDK oder Werkzeuge wie Claude Code nutzt, verwendet den offiziell empfohlenen Anthropic-kompatiblen Einstieg: international https://api.minimax.io/anthropic, China https://api.minimax.cn/anthropic, Nachrichten-Endpunkt POST /anthropic/v1/messages. Die alte native Schnittstelle POST /v1/text/chatcompletion_v2 existiert weiterhin, doch neue Integrationen sollten die kompatiblen Einstiege nutzen, da Parameter und Ökosystem einheitlicher sind.

Szenario Base URL Typischer Endpunkt
Offiziell OpenAI-kompatibel (international) https://api.minimax.io/v1 POST /v1/chat/completions
Offiziell OpenAI-kompatibel (China) https://api.minimax.cn/v1 POST /v1/chat/completions
Offiziell Anthropic-kompatibel (international) https://api.minimax.io/anthropic POST /anthropic/v1/messages
Offiziell Anthropic-kompatibel (China) https://api.minimax.cn/anthropic POST /anthropic/v1/messages
Native Textschnittstelle https://api.minimax.io oder https://api.minimax.cn POST /v1/text/chatcompletion_v2
ZSQH Gateway https://ai.zhongshangqihang.com/v1 POST /v1/chat/completions

Adresse und Schlüssel müssen von derselben Plattform stammen. Ein Schlüssel der chinesischen Seite an der internationalen Adresse führt in der Regel direkt zu 401; ein Gateway-Schlüssel an der offiziellen Adresse ebenso. Ein weiterer häufiger Fehler: Die Base URL enthält bereits /v1, und der Anfragepfad setzt noch einmal /v1 davor, sodass /v1/v1/chat/completions entsteht.

2. Modellnamen: Groß-/Kleinschreibung und Version müssen passen

Stand Oktober 2026 nennt die offizielle Dokumentation als aktuelle Textmodelle MiniMax-M3.1-Flash und MiniMax-M3 mit einem Kontextfenster von 1.000.000 Token. MiniMax-M3.1-Flash erlaubt die Steuerung der Reasoning-Tiefe; MiniMax-M3 ist das multimodale Codemodell derselben Generation.

Die vorherige Generation steht weiterhin in der Dokumentation: MiniMax-M2.7, MiniMax-M2.7-highspeed, MiniMax-M2.5, MiniMax-M2.5-highspeed, MiniMax-M2.1, MiniMax-M2.1-highspeed und MiniMax-M2 mit 204.800 Token Kontext. Hinzu kommt MiniMax-M2-her mit 64K Kontext. Modellnamen unterscheiden Groß- und Kleinschreibung sowie Bindestriche; beim Kopieren nicht abtippen.

Beim ZSQH Gateway richten sich Modellnamen nach der Seite Preisübersicht und können von der offiziellen Benennung abweichen. Modellnamen nicht fest im Code verankern, sondern in Umgebungsvariablen oder einem Konfigurationsdienst ablegen, sodass ein Wechsel nur die Konfiguration betrifft.

3. curl: zuerst eine nicht gestreamte Anfrage

Legen Sie den Schlüssel in der Umgebungsvariable MINIMAX_API_KEY ab. Das Beispiel nutzt die OpenAI-kompatible Schnittstelle der chinesischen Seite; international die Domain auf api.minimax.io ändern, beim Gateway die Gateway-Adresse verwenden. Streaming zunächst deaktiviert lassen und erst nach Prüfung der Antwortstruktur ergänzen.

export MINIMAX_API_KEY="Ihr-Schluessel"

curl "https://api.minimax.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3.1-Flash",
    "messages": [
      {"role": "system", "content": "Du bist ein knapper deutscher Assistent."},
      {"role": "user", "content": "Erkläre in drei Sätzen, was eine Base URL ist."}
    ],
    "max_completion_tokens": 512,
    "stream": false
  }'

Im zurückgegebenen JSON enthält choices[0].message.content die endgültige Antwort. Bei der M3-Reihe stehen Reasoning-Inhalte üblicherweise im Feld reasoning_content, während content nur die endgültige Antwort enthält. Beides nicht vermischen, es sei denn, das Produkt soll den Denkprozess ausdrücklich anzeigen.

Beim Gateway Adresse, Schlüssel und Modellnamen gemeinsam ändern. Wird nur eine Stelle geändert, pendelt das Ergebnis meist zwischen 401 und model not found.

4. Python: Aufruf mit dem OpenAI SDK

Nach der Installation von openai mit base_url auf die kompatible MiniMax-Adresse zeigen. Das Beispiel legt Adresse und Modell in Umgebungsvariablen ab, damit sich offizieller Zugang und Gateway leicht wechseln lassen.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
)

stream = client.chat.completions.create(
    model=os.environ.get("MINIMAX_MODEL", "MiniMax-M3.1-Flash"),
    messages=[
        {"role": "system", "content": "Du bist ein knapper deutscher Assistent."},
        {"role": "user", "content": "Schreibe ein Python-Beispiel, das eine CSV liest und Zeilen zählt."},
    ],
    max_completion_tokens=1024,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if getattr(delta, "reasoning_content", None):
        print(delta.reasoning_content, end="")
    if delta.content:
        print(delta.content, end="")

In der Streaming-Antwort steht der Denkinhalt in delta.reasoning_content, der Text in delta.content. Mit stream_options.include_usage: true enthält der letzte Chunk die Usage-Daten. Je nach SDK-Version landen unbekannte Felder an unterschiedlichen Stellen; vor dem Auslesen die Rohantwort einmal in der Testumgebung ausgeben.

5. Token- und Sampling-Parameter: nicht nur max_tokens ändern

Neuer Code sollte max_completion_tokens zur Steuerung der Ausgabelänge verwenden. max_tokens ist in der offiziellen Dokumentation als alter Parameter markiert und kann weiterhin kompatibel sein, sollte aber nicht Grundlage neuer Implementierungen sein. Bei der M3-Reihe zählen Reasoning-Token zum Ausgabelimit; ist das Limit zu klein, erscheint finish_reason: "length" und content bleibt leer.

Wichtige Parameter:

  • temperature: steuert die Zufälligkeit; der zulässige Bereich steht in der aktuellen Dokumentation, Werte außerhalb führen zu 400.
  • top_p: Standard 0,95 bei M3, 0,9 bei M2.x; in der Regel nur einen der beiden Werte anpassen.
  • reasoning_effort: M3 unterstützt low, medium, high, xhigh und max, Standard max; niedrigere Werte senken Latenz und Ausgabe-Token.
  • thinking: Bei MiniMax-M3.1-Flash ist Reasoning immer aktiv; disabled führt zu 400. Die Unterstützung anderer Modelle steht in der Dokumentation.
  • n: Nur 1 wird unterstützt; presence_penalty, frequency_penalty und ähnliche Parameter können ignoriert werden.
  • Tool-Aufrufe: tools statt des alten function_call verwenden; bei mehrstufigen Tool-Aufrufen die vollständige Assistant-Nachricht einschließlich tool_calls und Reasoning-Inhalten in die Historie zurückgeben.

Bei hoher Latenz zuerst reasoning_effort senken, dann Eingabe und Ausgabelimit verkürzen, nicht sofort das Modell wechseln. Qualität und Latenz von Reasoning-Modellen ändern sich gemeinsam; mit passenden Parametern ist in vielen Szenarien kein kleineres Modell nötig.

6. Häufige Fehler: nach Statuscode eingrenzen

  • 401: Schlüssel fehlt, ist falsch formatiert oder passt nicht zu Seite/Gateway. Authorization: Bearer und Base URL prüfen.
  • 404: Pfad falsch oder /v1 fehlt bzw. ist doppelt. Die OpenAI-kompatible Adresse endet auf /v1; danach folgt /chat/completions.
  • model not found oder model_not_found: Modellname falsch geschrieben, Groß-/Kleinschreibung falsch oder das Konto hat keine Berechtigung. Namen aus Dokumentation oder Preisseite kopieren.
  • 400: Parameter außerhalb des Bereichs, etwa temperature, thinking: disabled bei M3.1-Flash oder ein nicht unterstützter reasoning_effort-Wert.
  • finish_reason: "length" bei leerem Inhalt: Das Ausgabelimit ist zu klein und wird von Reasoning-Token aufgebraucht. max_completion_tokens erhöhen.
  • 429: Rate-Limit erreicht. Die offizielle Dokumentation nennt als Referenz für M3 200 RPM und 10.000.000 TPM, für M2.x 500 RPM und 20.000.000 TPM; maßgeblich sind Konto und Konsole. Parallelität senken und Backoff ergänzen.
  • 5xx oder Timeout: Schwankung im Upstream oder Netzwerkproblem. Timeout, exponentielles Backoff und Ersatzmodell einrichten, nicht unbegrenzt wiederholen.

Die Limitwerte sind Referenzangaben der offiziellen Dokumentation vom Oktober 2026 und können je Konto, Modell und Schnittstelle abweichen. In der Produktion zählen Konsole und tatsächliche Beobachtung; die Parallelität nicht bis zu den Dokumentwerten ausreizen.

7. Migrationscheckliste

  1. Zielplattform festlegen: offizielle chinesische Seite, offizielle internationale Seite oder ZSQH Gateway. Schlüssel und Base URL müssen von derselben Plattform stammen.
  2. base_url ändern: OpenAI-kompatibel nutzt /v1, Anthropic-kompatibel /anthropic; nicht mischen.
  3. Modellnamen ändern: aus offizieller Dokumentation oder Preisübersicht kopieren; Groß-/Kleinschreibung, Bindestriche und Version beachten.
  4. Ausgabeparameter ändern: bevorzugt max_completion_tokens und ausreichend Budget für Reasoning-Token.
  5. Streaming-Parsing prüfen: Text aus delta.content, Reasoning aus delta.reasoning_content; nicht nur ein Feld annehmen.
  6. Tool-Aufrufe prüfen: tools verwenden und die vollständige Assistant-Nachricht samt Reasoning-Inhalten wie gefordert zurückgeben.
  7. Timeout, Wiederholung und Circuit Breaker ergänzen: exponentielle Backoff für 429 und 5xx, Zeitlimit pro Anfrage.
  8. Logging und Verbrauchsmonitoring ergänzen: Modellname, Dauer, Input-/Output-Token und Fehlercode erfassen; Schlüssel nicht loggen.
  9. Grau schalten: zuerst einen risikoarmen Geschäftsfall umstellen, Qualität und Kosten vergleichen, dann Verkehr ausweiten.
  10. Rückweg vorbereiten: alte Konfiguration und alten Schlüssel eine Zeit lang behalten und erst nach Stabilisierung entfernen.

Die Liste gilt auch für eine Migration von OpenAI zu MiniMax oder von der Direktverbindung zum Gateway. Im Kern geht es nicht um eine Zeile Base URL, sondern um die gemeinsame Prüfung von Authentifizierung, Modellen, Parametern, Streaming-Parsing und Monitoring.

8. Offizielle Direktverbindung oder Gateway

Wer ausschließlich MiniMax nutzt, einen stabilen Verbrauch hat und Registrierung sowie Abrechnung direkt erledigen kann, fährt mit der offiziellen Direktverbindung am kürzesten. Wer mehrere Modelle, eine einheitliche Abrechnung und einen einheitlichen Schlüssel benötigt oder im inländischen Netz weniger Konfigurationen pflegen möchte, ist mit einem Gateway besser bedient.

Bei der Gateway-Auswahl vier Punkte prüfen: welche MiniMax-Modelle unterstützt werden, ob die genutzte Schnittstelle (OpenAI oder Anthropic) kompatibel ist, ob die Abrechnungslogik klar ist und welche Supportkanäle bei Störungen bestehen. Zuerst klein testen, dann Produktionsverkehr senden. Modelle und Abrechnung stehen in der Preisübersicht, ein Testschlüssel lässt sich über die Registrierung anlegen.

Häufige Fragen

Welche Base URL hat die MiniMax API?

International OpenAI-kompatibel: https://api.minimax.io/v1, China: https://api.minimax.cn/v1. Anthropic-kompatibel sind es https://api.minimax.io/anthropic und https://api.minimax.cn/anthropic. Maßgeblich ist die Seite, auf der das Konto registriert wurde.

Ist die MiniMax API mit dem OpenAI SDK kompatibel?

Die üblichen Chat-Schnittstellen sind kompatibel. base_url auf die MiniMax-/v1-Adresse zeigen lassen und den Modellnamen durch einen MiniMax-Namen ersetzen. Kompatibilität bedeutet jedoch nicht vollständige Gleichheit: Reasoning-Felder, Token-Parameter und Tool-Details können abweichen.

Warum ist die Antwort leer und finish_reason lautet length?

Das Ausgabelimit wurde von Reasoning-Token aufgebraucht. Die M3-Reihe rechnet Reasoning in das Ausgabebudget ein. Zuerst max_completion_tokens erhöhen und dann prüfen, ob ein zu niedriges max_tokens gesetzt ist.

Lässt sich Reasoning abschalten?

MiniMax-M3.1-Flash erzwingt Reasoning; thinking: disabled führt zu 400. Ob andere Modelle es abschalten können, steht in der aktuellen offiziellen Dokumentation. Zur Latenzsenkung zuerst reasoning_effort verringern.

Was muss bei einer Migration von OpenAI geändert werden?

Mindestens Schlüssel, Base URL, Modellname und Ausgabeparameter; danach Streaming-Felder, Tool-Aufrufe, Timeouts, Wiederholungen und Logs prüfen. Zuerst einen nicht gestreamten curl-Aufruf, dann Python mit Streaming, schließlich die graue Umschaltung.

Nächster Schritt

Ein Modell wählen, per curl eine nicht gestreamte Anfrage durchführen und danach Python mit Streaming testen. Erst wenn content und reasoning_content korrekt ausgelesen werden, in das Geschäft integrieren. Für einen einheitlichen Einstieg lässt sich das ZSQH AI Gateway registrieren; verfügbare Modelle und Abrechnung stehen in der Preisübersicht.

Weiterlesen: