MiniMax API in Python: Verwende das OpenAI SDK
Du benötigst keinen speziellen Client, um diese API aus Python aufzurufen. Das Standard-openai-Paket funktioniert, sobald du die Base URL und den Schlüssel festlegst. Diese Anleitung behandelt Chat, Streaming, JSON, Tools, Wiederholungen und Kostenberechnung.
Aktualisiert

Wichtige Punkte
- Installiere openai und übergebe base_url https://api.minimaxapikey.com/v1 sowie deinen Schlüssel an den Client.
- Verwende die Modell-ID uncensored für Chat, Streaming, JSON-Modus und Tool Calling.
- Behandle HTTP 429 mit Backoff und begrenze Threads auf 8 für einen Voll-Key bzw. 2 für einen Trial-Key.
- Lies die Nutzung aus jeder Antwort und multipliziere sie mit $0,15 bzw. $0,50 pro 1M Token, um die Ausgaben zu verfolgen.
Installation und erster Aufruf
Für minimax api python ist der schnellste Weg das offizielle openai-Paket von PyPI. Der Dienst hinter dieser Website ist eine gehostete, OpenAI-kompatible API eines unabhängigen Anbieters, sodass kein separates SDK erlernt werden muss. Es ist nicht die Plattform des Herstellers; die einzigen Änderungen gegenüber einem Standard-OpenAI-Skript sind die Base URL, der Schlüssel und der Modellname.
pip install --upgrade openai
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.minimaxapikey.com/v1",
api_key=os.environ["UNCENSORED_KEY"],
)
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "Answer in plain English, briefly."},
{"role": "user", "content": "What does a context window limit?"},
],
)
print(resp.choices[0].message.content)
print(resp.usage)
Hole den Schlüssel von der API-Schlüssel-Seite. Neue Konten können dort mit einem Klick $0,50 an Testguthaben beanspruchen, keine Karte erforderlich, gültig für 7 Tage. Speichere den Schlüssel in einer Umgebungsvariable, wie gezeigt, statt ihn in Quelldateien einzufügen.
Sampling-Parameter und max_tokens
Die üblichen Einstellungen werden durchgereicht: temperature, top_p, stop, seed sowie die Frequency- und Presence-Penalties. Ein fester seed bei niedriger Temperatur liefert reproduzierbarere Ergebnisse für Tests, betrachte ihn jedoch nicht als Garantie für identischen Text.
resp = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "List five verbs for a changelog."}],
temperature=0.3,
top_p=0.9,
stop=["\n\n"],
seed=42,
max_tokens=120,
)
max_tokens ist optional. Ohne ihn kann die Completion den verbleibenden Rest des 100.000-Token-Kontextfensters nach deinem Prompt nutzen. Das ist nützlich für lange Dokumente, setze aber in Produktionscode eine Obergrenze. Eine unkontrollierte Generierung kostet echte Output-Token zu $0,50 pro 1M, und eine Obergrenze begrenzt den Schaden durch einen schlechten Prompt.
Streaming-Antworten
Übergebe stream=True und iteriere. Die Antwort wird als Server-Sent Events geliefert, und das SDK wandelt sie in Chunk-Objekte um. Gib den Delta-Text bei Ankunft aus, um eine responsive Chat-Schnittstelle zu erhalten.
stream = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write a short product description for a notebook."}],
stream=True,
)
parts = []
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
piece = chunk.choices[0].delta.content
parts.append(piece)
print(piece, end="", flush=True)
print()
text = "".join(parts)
Nutzungsdaten werden am Ende des Streams gesendet. Wenn deine SDK-Version ein usage-Attribut im letzten Chunk bereitstellt, lies es dort; zähle andernfalls Tokens auf deiner Seite für die Budgetplanung. Ein praktischer Punkt: Eine gestreamte Anfrage belegt ihren Concurrency-Slot, bis der Stream endet. Wenn du acht lange Streams mit einem Voll-Key öffnest, erhält eine neunte Anfrage einen 429-Fehler mit dem Code concurrency, bis einer abgeschlossen ist. Schließe oder verbrauche einen Stream immer vollständig, damit der Slot freigegeben wird.
JSON-Modus für strukturierte Ausgaben
Wenn du maschinenlesbare Ausgaben benötigst, setze response_format auf ein JSON-Objekt. Erwähne JSON auch im Prompt und beschreibe die gewünschten Schlüssel, da das Format-Flag gültige JSON-Syntax garantiert, aber nicht dein Schema.
import json
resp = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "Reply only with JSON using keys: title, tags (list of strings)."},
{"role": "user", "content": "Summarise: a tutorial on caching HTTP responses in Python."},
],
response_format={"type": "json_object"},
)
data = json.loads(resp.choices[0].message.content)
print(data["title"], data["tags"])
Validiere das Ergebnis weiterhin. Prüfe, ob erforderliche Schlüssel vorhanden sind und die richtigen Typen haben, bevor du sie verwendest, und entscheide, was dein Code tut, wenn dies nicht der Fall ist, z. B. einmaliges Wiederholen mit einer klareren Anweisung. Eine dünne Validierungsschicht, sogar einige isinstance-Prüfungen, spart viel Debugging in der Produktion.
Tool Calling
Tool Calling folgt der OpenAI-Struktur. Du beschreibst Funktionen in tools, erzwingst optional eine Auswahl mit tool_choice, und das Modell gibt tool_calls mit JSON-Argumenten zurück. Du führst die Funktion aus und sendest das Ergebnis als Nachricht mit role: "tool" zurück.
import json
def get_rate(currency):
rates = {"EUR": 0.92, "GBP": 0.79}
return json.dumps({"currency": currency, "per_usd": rates.get(currency)})
tools = [{
"type": "function",
"function": {
"name": "get_rate",
"description": "Exchange rate per 1 USD for a currency code.",
"parameters": {
"type": "object",
"properties": {"currency": {"type": "string"}},
"required": ["currency"],
},
},
}]
messages = [{"role": "user", "content": "How many EUR is 50 USD?"}]
first = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
msg = first.choices[0].message
messages.append(msg)
for call in msg.tool_calls or []:
args = json.loads(call.function.arguments)
messages.append({"role": "tool", "tool_call_id": call.id, "content": get_rate(args["currency"])})
final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
print(final.choices[0].message.content)
Die Raten in diesem Beispiel sind fiktiv für die Demo. In echtem Code würde die Funktion deinen eigenen Dienst aufrufen. Analysiere Argumente defensiv mit json.loads innerhalb eines try-Blocks, da ein Modell gelegentlich fehlerhafte Argumente ausgibt.
Ratenlimits, Wiederholungen und parallele Arbeit
Ein Voll-Key erlaubt 8 gleichzeitige Anfragen und 300 pro Minute; ein Trial-Key erlaubt 2 gleichzeitige und 60 pro Minute. Das Überschreiten liefert HTTP 429. Der Fehlercode ist rate_limited für die pro-Minute-Begrenzung und concurrency für zu viele gleichzeitige Aufrufe. Temporäre Überlastung ergibt ebenfalls einen 429 mit einem Retry-After: 5-Header. Das OpenAI SDK wiederholt einige Fehler automatisch, und du kannst dies mit max_retries erhöhen. Füge für Batch-Jobs deine eigene Begrenzung für Threads hinzu, um durch Design unter der Obergrenze zu bleiben, statt durch Wiederholungen.
from concurrent.futures import ThreadPoolExecutor
from openai import OpenAI, RateLimitError
import os, time
client = OpenAI(
base_url="https://api.minimaxapikey.com/v1",
api_key=os.environ["UNCENSORED_KEY"],
max_retries=2,
)
def ask(prompt):
for attempt in range(4):
try:
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": prompt}],
max_tokens=200,
)
return r.choices[0].message.content
except RateLimitError:
time.sleep(5 * (attempt + 1))
return None
prompts = [f"Write one tagline for product {i}." for i in range(20)]
with ThreadPoolExecutor(max_workers=8) as pool:
results = list(pool.map(ask, prompts))
Verwende max_workers=2 mit einem Trial-Key. Der Async-Client AsyncOpenAI verwendet dieselben Argumente; kombiniere ihn mit einem asyncio.Semaphore(8), um dieselbe Obergrenze durchzusetzen. Die Dokumentation listet die Antwort-Header auf, die du für Limits inspizieren kannst.
Gesprächsverlauf speichern
Die API ist zustandslos. Sie erinnert sich nicht an die vorherige Anfrage, daher funktioniert ein Multi-Turn-Chat durch Senden der gesamten Konversation bei jedem Aufruf. Halte eine Liste von Nachrichten, hänge den User-Turn an, rufe die API auf und hänge die Assistant-Antwort an, bevor die nächste Runde beginnt.
history = [{"role": "system", "content": "You are a patient Python tutor."}]
def chat(user_text):
history.append({"role": "user", "content": user_text})
r = client.chat.completions.create(model="uncensored", messages=history)
reply = r.choices[0].message.content
history.append({"role": "assistant", "content": reply})
return reply
print(chat("What is a list comprehension?"))
print(chat("Show me one with a filter."))
Dieses Muster hat einen Aufwand, der mit jedem Turn wächst: Jede Anfrage bezahlt für alle vorherigen Turns erneut als Input-Token. Mit einem 100.000-Token-Kontextfenster hast du viel Spielraum, aber lange Sitzungen werden teuer und langsam. Eine einfache Richtlinie ist, die Systemnachricht und die letzten N Turns zu behalten oder das Modell um eine kurze Zusammenfassung älterer Turns zu bitten und diese damit zu ersetzen. Entscheide dich früh für eine Richtlinie, da das nachträgliche Einfügen von Kürzungen in eine Chat-App umständlicher ist, als es von Anfang an einzubauen.
Fehlerbehandlung über 429 hinaus
Das SDK löst typisierte Ausnahmen aus, und das Sortieren dieser lohnt einige Zeilen. Authentifizierungsprobleme und schlechte Anfragen beheben sich bei einer Wiederholung nicht von selbst, während Netzwerkfehler und Überlastung dies meist tun. Behandle sie unterschiedlich.
import openai
try:
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Hello"}],
timeout=60,
)
except openai.AuthenticationError:
print("Check the API key and the Bearer header.")
except openai.RateLimitError as e:
print("Slow down:", e.response.headers.get("Retry-After"))
except openai.APIConnectionError:
print("Network problem, retry with backoff.")
except openai.APIStatusError as e:
print("Server said", e.status_code, e.response.headers.get("X-Request-Id"))
Wenn du den Support kontaktierst, füge den Wert von X-Request-Id aus der fehlgeschlagenen Anfrage hinzu. Sie identifiziert genau diese Anfrage. Lege ein explizites timeout fest, da das Standard-Timeout lang ist, und eine hängende Anfrage, die einen Concurrency-Slot belegt, reduziert deine Durchsatzrate. Fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet, daher verdoppelt sich die Rechnung nicht durch das Wiederholen einer fehlgeschlagenen Anfrage.
Eine kleine Projektstruktur, die skaliert
Skripte werden zu Diensten. Eine kleine Struktur am Anfang hält die API-Details an einem Ort, sodass eine spätere Änderung des Modellnamens, des Timeouts oder der Limits nur eine Datei betrifft statt zwanzig.
# llm.py
import os
from openai import OpenAI
BASE_URL = "https://api.minimaxapikey.com/v1"
MODEL = "uncensored"
_client = OpenAI(base_url=BASE_URL, api_key=os.environ["UNCENSORED_KEY"], timeout=60, max_retries=2)
def complete(messages, **kwargs):
r = _client.chat.completions.create(model=MODEL, messages=messages, **kwargs)
return r.choices[0].message.content, r.usage
Jedes andere Modul importiert complete und erstellt nie einen Client. Diese eine Schnittstelle ist der Ort, an dem du später Logging, einen Ausgaben-Zähler oder einen Semaphore hinzufügst. Für mehr Referenzmaterial zeigt die Dokumentationsseite dieselben Endpunkte in curl-Form, was praktisch ist, um eine fehlerhafte Python-Anfrage mit einer bekannten gültigen Anfrage zu vergleichen.
Das Festlegen einer Version hilft ebenfalls. Fixiere das openai-Paket in deiner requirements-Datei und führe Updates gezielt durch, lies zuerst die Release Notes, da SDK-Änderungen Ausnahme-Namen oder Standard-Wiederholungsverhalten ändern können. Kombiniere dies mit einer kurzen README-Anmerkung, die angibt, welche Base URL und Modell-ID das Projekt erwartet, damit ein neues Teammitglied es am ersten Tag ohne Fragen ausführen kann.
Ein letzter Punkt zum Testen. Schreibe mindestens einen Test, der gegen einen Fake-Client läuft, damit deine Suite kein Guthaben verbraucht oder vom Netzwerk abhängt. Halte einen einzigen Live-Smoke-Test, manuell oder in einem nächtlichen Job ausgeführt, um Änderungen in der echten API früh zu erkennen.
Guthaben und Kosten im Code verfolgen
Jede Antwort enthält X-Balance-USD, und das SDK ermöglicht das Lesen von Headern über with_raw_response. Das Protokollieren nach jeder Anfrage ist eine günstige Methode, um ein leeres Guthaben zu erkennen, bevor es deine Nutzer tun.
raw = client.chat.completions.with_raw_response.create(
model="uncensored",
messages=[{"role": "user", "content": "Say hello in French."}],
)
print("balance:", raw.headers.get("X-Balance-USD"))
print("request id:", raw.headers.get("X-Request-Id"))
resp = raw.parse()
def cost_usd(usage):
return usage.prompt_tokens * 0.15 / 1_000_000 + usage.completion_tokens * 0.50 / 1_000_000
print(cost_usd(resp.usage))
Eine durchgerechnete Überprüfung der Formel: Eine Anfrage mit 2.000 Input-Token und 500 Output-Token kostet 2.000 x 0,15 / 1.000.000 = $0,0003 für Input, plus 500 x 0,50 / 1.000.000 = $0,00025 für Output, also $0,00055. Tausend solcher Anfragen ergeben $0,55. Fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet, sodass ein Protokoll, das aus erfolgreichen usage-Objekten besteht, der Rechnung sehr nahe kommt.
Abrechnung: Pay as you go vom Prepaid-Guthaben, kein Abo. Aufladungen von $20 bis $500 in beliebigen ganzen Beträgen, mit Boni ab $50; das Guthaben verfällt nie. Details auf der Preisseite. Prompts werden nicht zum Training verwendet.
Weitere Anleitungen
Fragen und Antworten
Gibt es ein separates MiniMax Python-Paket?
Du brauchst hier keines. Dieser Dienst ist OpenAI-kompatibel, daher funktioniert das reguläre openai-Paket mit einer benutzerdefinierten base_url. Es ist ein unabhängiger Dienst, kein offizielles SDK des Anbieters.
Funktioniert der Async-Client?
Ja. AsyncOpenAI verwendet dieselben base_url- und api_key-Argumente. Halte die Anzahl der laufenden Anfragen unter oder gleich deinem Concurrency-Limit.
Wie erhalte ich Token-Anzahlen?
Jede nicht-gestreamte Antwort enthält ein usage-Objekt mit prompt_tokens und completion_tokens. Bei Streams wird usage am Ende gesendet; lies es aus dem letzten Chunk, falls dein Client dies bereitstellt.
Welche Kontextlänge kann ich verwenden?
Das Kontextfenster umfasst 100.000 Token, geteilt zwischen Prompt und Completion. max_tokens ist optional.
Dein Schlüssel ist nur ein Formular entfernt
Erstelle ein Konto, kopiere den Schlüssel, ändere die Basis-URL. Das ist die gesamte Einrichtung.