MiniMax API in Python: gebruik de OpenAI SDK
Je hebt geen speciale client nodig om deze API aan te roepen vanuit Python. Het standaard openai-pakket werkt zodra je de base URL en key instelt; deze gids behandelt chat, streaming, JSON, tools, retries en kostenberekening.
Bijgewerkt

Belangrijkste punten
- Installeer openai en geef base_url https://api.minimaxapikey.com/v1 en je key mee aan de client.
- Gebruik model ID uncensored voor chat, streaming, JSON-modus en tool calling.
- Verwerk HTTP 429 met backoff en beperk threads tot 8 voor een full key, 2 voor een trial key.
- Lees usage van elk response en vermenigvuldig met $0,15 en $0,50 per 1M tokens om je uitgaven bij te houden.
Installeer en maak de eerste aanroep
Voor minimax api python werk is de snelste route het officiële openai pakket van PyPI. De service achter deze site is een gehoste, OpenAI-compatible API die wordt gerund door een onafhankelijke provider, dus er is geen aparte SDK om te leren. Het is niet het eigen platform van de leverancier, en de enige wijzigingen ten opzichte van een standaard OpenAI-script zijn de base URL, de sleutel en de modelnaam.
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)
Haal de sleutel van de API-sleutelpagina. Nieuwe accounts kunnen daar met één klik $0,50 aan proeftegoed claimen, zonder kaart, en het blijft 7 dagen geldig. Bewaar de sleutel in een omgevingsvariabele zoals getoond, in plaats van deze in bronbestanden te plakken.
Sampling parameters en max_tokens
De gebruikelijke instellingen worden doorgegeven: temperature, top_p, stop, seed, en de frequentie- en presence penalties. Een vaste seed met een lage temperature geeft je meer herhaalbare outputs voor tests, maar beschouw het niet als een garantie op identieke tekst.
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 is optioneel. Zonder deze parameter kan de completie gebruikmaken van wat er overblijft van het 100.000-token contextvenster na je prompt. Dat is handig voor lange documenten, maar stel een plafond in in productiecode. Een op hol geslagen generatie kost echte output tokens bij $0,50 per 1M, en een plafond beperkt de schade bij een slechte prompt.
Streaming-antwoorden
Voeg stream=True toe en itereer. De response wordt geleverd als server-verzonden gebeurtenissen, en de SDK zet deze om in chunk objecten. Print de delta tekst naarmate deze aankomt voor een chatinterface die responsief aanvoelt.
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)
Gebruikscijfers worden aan het einde van de stream verzonden. Als je SDK-versie een usage attribuut exposeert op het laatste chunk, lees het daar; tel anders tokens aan je eigen kant voor budgettering. Een praktisch punt: een gestreamd verzoek houdt zijn concurrentieslot vast totdat de stream klaar is. Als je acht lange streams opent met een volledige sleutel, krijgt een negende verzoek een 429 met de foutcode concurrency totdat er één klaar is. Sluit een stream altijd of consumeer hem volledig zodat het slot wordt vrijgegeven.
JSON-modus voor gestructureerde output
Wanneer je machine-leesbare output nodig hebt, stel je response_format in op een JSON object. Vermeld JSON ook in de prompt en beschrijf de gewenste keys, omdat de format flag geldige JSON syntax garandeert maar niet jouw 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"])
Valideer het resultaat nog steeds. Controleer of vereiste keys bestaan en het juiste type hebben voordat je ze gebruikt, en bepaal wat je code doet als dat niet zo is, zoals één keer opnieuw proberen met een duidelijkere instructie. Een dunne validatielaag, zelfs een paar isinstance checks, bespaart veel debuggen in productie.
Tool calling
Tool calling volgt de OpenAI structuur. Je beschrijft functies in tools, forceer optioneel een keuze met tool_choice, en het model retourneert tool_calls met JSON-argumenten. Je voert de functie uit en stuurt het resultaat terug als een bericht met role: "tool".
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)
De rates in dit voorbeeld zijn verzonnen voor de demo. In echte code zou de functie je eigen service aanroepen. Parseer argumenten defensief met json.loads binnen een try block, omdat een model af en toe onjuist opgebouwde argumenten kan genereren.
Rate limits, retries en parallelle taken
Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 per minuut toe; een proefsleutel staat 2 gelijktijdige en 60 per minuut toe. Overschrijden levert HTTP 429 op. De foutcode is rate_limited voor de per-minuut limiet en concurrency voor te veel gelijktijdige aanroepen. Tijdelijke overbelasting geeft ook een 429, met een Retry-After: 5 header. De OpenAI SDK probeert sommige fouten automatisch opnieuw, en je kunt dat verhogen met max_retries. Voeg voor batch taken je eigen limiet op threads toe zodat je door ontwerp onder het plafond blijft in plaats van door opnieuw proberen.
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))
Gebruik max_workers=2 op een proefsleutel. De async client, AsyncOpenAI, accepteert dezelfde argumenten; combineer het met een asyncio.Semaphore(8) om hetzelfde plafond af te dwingen. De docs vermelden de response headers die je kunt inspecteren voor limieten.
Geschiedenis van gesprekken bijhouden
De API is stateless. Het onthoudt de vorige aanroep niet, dus een chat met meerdere beurten werkt door telkens het hele gesprek te versturen. Houd een lijst van berichten bij, voeg de gebruikersbeurt toe, roep de API aan, en voeg vervolgens het antwoord van de assistent toe voordat de volgende ronde begint.
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."))
Dit patroon heeft kosten die groeit met elke beurt: elk verzoek betaalt voor alle eerdere beurten opnieuw als input tokens. Met een 100.000-token contextvenster heb je veel ruimte, maar lange sessies worden duur en traag. Een eenvoudig beleid is om het systeembericht en de laatste N beurten te behouden, of om het model te vragen om een korte samenvatting van oudere beurten en ze daarmee te vervangen. Kies een beleid vroeg, want het achteraf inbouwen van trimming in een chat-app is lastiger dan het van tevoren bouwen.
Foutafhandeling buiten 429
De SDK geeft getypeerde uitzonderingen, en het sorteren ervan is een paar regels waard. Authenticatieproblemen en bad requests lossen zichzelf niet op bij een retry, terwijl netwerkfouten en overbelasting dat meestal wel. Behandel ze anders.
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"))
Neem contact op met support en voeg de waarde van X-Request-Id van de mislukte aanroep mee. Het identificeert dat exacte verzoek. Stel een expliciete timeout in zoals getoond, omdat de standaard lang is, en een vastgelopen aanroep die een concurrentieslot vasthoudt verlaagt je throughput stil. Mislukte of geweigerde verzoeken worden niet in rekening gebracht, dus een retry van een mislukte aanroep verdubbelt de rekening niet.
Een kleine projectstructuur die schaalbaar is
Scripts groeien uit tot services. Een beetje structuur aan het begin houdt de API-details op één plek, zodat een latere wijziging in de modelnaam, de timeout of de limieten slechts één bestand raakt in plaats van twintig.
# 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
Elke andere module importeert complete en bouwt nooit een client. Dat enkele snijvlak is waar je later logging, een verbruiksteller of een semaphore aan toevoegt. Als je meer referentiemateriaal wilt, toont de documentatiepagina dezelfde endpoints in curl-vorm, wat handig is om een mislukte Python-aanroep te vergelijken met een bekend werkend verzoek.
Versie-pinning helpt ook. Pin het openai pakket in je requirements bestand en upgrade opzettelijk, lees eerst de release notes, omdat SDK-wijzigingen de namen van uitzonderingen of standaard retry-gedrag kunnen wijzigen. Combineer dat met een korte README notitie die vermeldt welke base URL en model ID het project verwacht, zodat een nieuwe teamgenoot het op dag één kan draaien zonder te vragen.
Een laatste punt over testen. Schrijf ten minste één test die draait tegen een fake client, zodat je suite geen tegoed verbruikt of afhankelijk is van het netwerk. Houd één live smoke test over, handmatig uitgevoerd of in een nachtelijke taak, om wijzigingen in de echte API vroeg op te merken.
Balance en kosten bijhouden in code
Elke response draagt X-Balance-USD, en de SDK stelt je in staat headers te lezen via with_raw_response. Het loggen ervan na elke aanroep is een goedkope manier om een lege balans te vangen voordat je gebruikers dat doen.
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))
Een uitgewerkte controle van de formule: een aanroep met 2.000 input tokens en 500 output tokens kost 2.000 x 0,15 / 1.000.000 = $0,0003 voor input, plus 500 x 0,50 / 1.000.000 = $0,00025 voor output, dus $0,00055. Duizend van zulke aanroepen komt neer op $0,55. Mislukte of geweigerde verzoeken worden niet in rekening gebracht, dus een log gebouwd uit succesvolle usage objects komt nauwkeurig overeen met de rekening.
Facturatie is betaal per gebruik van prepaid credit zonder abonnement. Opwaarderingen lopen van $20 tot $500 in elk geheel bedrag, met bonuses vanaf $50, en het tegoed verloopt nooit; de details staan op de prijspagina. Prompts worden niet gebruikt voor training.
Meer handleidingen
Vragen en antwoorden
Is er een apart MiniMax Python-pakket?
Die hoef je hier niet. Deze service is OpenAI-compatible, dus het reguliere openai pakket werkt met een custom base URL. Het is een onafhankelijke service, geen officiële SDK van de leverancier.
Werkt de async client?
Ja. AsyncOpenAI gebruikt dezelfde base_url en api_key argumenten. Houd het aantal actieve verzoeken op of onder je concurrentielimiet.
Hoe krijg ik tokenaantallen?
Elk non-streamed response heeft een usage object met prompt_tokens en completion_tokens. Voor streams wordt usage aan het einde verzonden; lees het dus uit het laatste chunk als je client dit exposeert.
Welke context length kan ik gebruiken?
Het contextvenster is 100.000 tokens, gedeeld tussen prompt en completion. max_tokens is optioneel.
Je sleutel is nog maar één formulier verwijderd
Maak een account aan, kopieer de sleutel, pas de base URL aan. Dat is de hele setup.