API MiniMax in Python: usa l'SDK OpenAI
Non hai bisogno di un client speciale per chiamare questa API da Python. Il pacchetto openai standard funziona una volta impostato il base URL e la chiave, e questa guida copre chat, streaming, JSON, strumenti, retry e calcolo dei costi.
Aggiornato

Punti chiave
- Installa openai, quindi passa base_url https://api.minimaxapikey.com/v1 e la tua chiave al client.
- Usa l'ID del modello uncensored per chat, streaming, modalità JSON e chiamata di funzioni.
- Gestisci l'HTTP 429 con backoff e limita i thread a 8 per una chiave completa, 2 per una chiave di prova.
- Leggi l'utilizzo da ogni risposta e moltiplica per $0,15 e $0,50 per 1M di token per tracciare la spesa.
Installa ed effettua la prima chiamata
Per minimax api python, la via più rapida è il pacchetto ufficiale openai su PyPI. Il servizio dietro questo sito è un'API ospitata compatibile con OpenAI gestita da un provider indipendente, quindi non c'è un SDK separato da imparare. Non è la piattaforma del fornitore, e le uniche modifiche rispetto a uno script OpenAI standard sono l'URL di base, la chiave e il nome del modello.
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)
Ottieni la chiave dalla pagina chiave API. I nuovi account possono richiedere $0,50 di credito di prova con un clic, senza carta, valido per 7 giorni. Tieni la chiave in una variabile d'ambiente come mostrato, invece di incollarla nei file sorgente.
Parametri di campionamento e max_tokens
I soliti parametri vengono passati: temperature, top_p, stop, seed, e le penalità di frequenza e presenza. Un seed fisso con una temperatura bassa ti dà output più ripetibili per i test, anche se non dovresti considerarlo una garanzia di testo identico.
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 è opzionale. Senza di esso, il completamento può usare tutto ciò che resta della finestra da 100.000 token dopo il tuo prompt. È utile per documenti lunghi, ma imposta un limite nel codice di produzione. Una generazione incontrollata costa token reali a $0,50 per 1M, e un limite mette un tetto ai danni da un prompt difettoso.
Risposte in streaming
Passa stream=True e itera. La risposta viene fornita come eventi server-sent, e l'SDK li trasforma in oggetti chunk. Stampa il testo delta man mano che arriva per un'interfaccia chat che sembra reattiva.
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)
I numeri di utilizzo vengono inviati alla fine dello stream. Se la versione del tuo SDK espone un attributo usage sull'ultimo chunk, leggilo lì; altrimenti conta i token dal tuo lato per il budgeting. Un punto pratico: una richiesta in streaming mantiene il suo slot di concorrenza fino al termine dello stream. Se apri otto stream lunghi con una chiave completa, una nona richiesta riceverà un 429 con il codice concurrency fino al completamento di uno. Chiudi sempre o consuma completamente uno stream così che lo slot venga rilasciato.
Modalità JSON per output strutturato
Quando hai bisogno di output leggibile dalla macchina, imposta response_format su un oggetto JSON. Menziona JSON anche nel prompt e descrivi le chiavi che vuoi, perché il flag del formato garantisce una sintassi JSON valida ma non il tuo 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"])
Convalida comunque il risultato. Verifica che le chiavi richieste esistano e abbiano i tipi corretti prima di usarle, e decidi cosa fa il tuo codice quando non lo fanno, come ritentare una volta con un'istruzione più chiara. Uno strato di convalida sottile, anche poche verifiche isinstance, risparmia molto debugging in produzione.
Chiamata di funzioni
La chiamata di funzioni segue la forma OpenAI. Descrivi le funzioni in tools, forza opzionalmente una scelta con tool_choice, e il modello restituisce tool_calls con argomenti JSON. Esegui la funzione e invia il risultato indietro come messaggio con 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)
Le tariffe in questo esempio sono inventati per la demo. Nel codice reale la funzione chiamerebbe il tuo servizio. Analizza gli argomenti in modo difensivo con json.loads all'interno di un blocco try, poiché un modello può occasionalmente emettere argomenti malformati.
Limiti di velocità, retry e lavoro parallelo
Una chiave completa permette 8 richieste parallele e 300 al minuto; una chiave di prova ne permette 2 concorrenti e 60 al minuto. Superare i limiti restituisce HTTP 429. Il codice errore è rate_limited per il limite al minuto e concurrency per troppe chiamate simultanee. Un sovraccarico temporaneo restituisce anche un 429, con un'intestazione Retry-After: 5. L'SDK OpenAI riprova alcuni errori autonomamente, e puoi aumentare questo valore con max_retries. Per i lavori batch, aggiungi il tuo limite di thread in modo da restare sotto il limite per progettazione invece che per ritentativi.
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))
Usa max_workers=2 su una chiave di prova. Il client asincrono, AsyncOpenAI, accetta gli stessi argomenti; abbinalo a un asyncio.Semaphore(8) per imporre lo stesso limite. La documentazione elenca le intestazioni di risposta che puoi ispezionare per i limiti.
Conservazione della cronologia delle conversazioni
L'API è stateless. Non ricorda la chiamata precedente, quindi una chat multi-turno funziona inviando l'intera conversazione ogni volta. Tieni un elenco di messaggi, aggiungi il turno dell'utente, chiama l'API, quindi aggiungi la risposta dell'assistente prima del turno successivo.
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."))
Questo pattern ha un costo che cresce con ogni turno: ogni richiesta paga di nuovo tutti i turni precedenti come token di input. Con una finestra da 100.000 token hai molto spazio, ma le sessioni lunghe diventano costose e lente. Una politica semplice è mantenere il messaggio di sistema e gli ultimi N turni, o chiedere al modello un breve riassunto dei turni precedenti e sostituirli con esso. Decidi una politica presto, perché aggiungere il trimming a un'app chat è più scomodo che costruirlo fin dall'inizio.
Gestione degli errori oltre il 429
L'SDK solleva eccezioni tipizzate, e ordinarle vale poche righe. Problemi di autenticazione e richieste errate non si risolvono da soli con il retry, mentre gli errori di rete e il sovraccarico di solito sì. Trattali in modo diverso.
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"))
Quando contatti il supporto, includi il valore di X-Request-Id dalla chiamata fallita. Identifica quella specifica richiesta. Imposta un timeout esplicito come mostrato, poiché il default è lungo, e una chiamata bloccata che tiene uno slot di concorrenza riduce silenziosamente il tuo throughput. Le richieste fallite o rifiutate non vengono addebitate, quindi ritentare una chiamata fallita non raddoppia il conto.
Una piccola struttura di progetto che scala
Gli script diventano servizi. Una piccola struttura all'inizio mantiene i dettagli dell'API in un unico punto, così una modifica successiva al nome del modello, al timeout o ai limiti tocca un file invece di venti.
# 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
Ogni altro modulo importa complete e non crea mai un client. Quel singolo punto è dove aggiungi logging, un contatore delle spese o un semaphore in seguito. Se vuoi più materiale di riferimento, la pagina docs mostra gli stessi endpoint in forma curl, utile per confrontare una chiamata Python fallita con una richiesta valida nota.
Il version pinning aiuta anche. Blocca il pacchetto openai nel tuo file requirements e aggiorna con intento, leggendo prima le note di rilascio, perché le modifiche all'SDK possono alterare i nomi delle eccezioni o il comportamento di retry predefinito. Abbinalo a una breve nota README che indica quale base URL e ID modello si aspetta il progetto, così un nuovo collega può eseguirlo dal primo giorno senza chiedere.
Un ultimo punto sui test. Scrivi almeno un test che gira contro un client finto, così la tua suite non spende credito o dipende dalla rete. Tieni un singolo test di fumo live, eseguito manualmente o in un lavoro notturno, per catturare presto i cambiamenti nell'API reale.
Monitoraggio del saldo e dei costi nel codice
Ogni risposta trasporta X-Balance-USD, e l'SDK ti permette di leggere le intestazioni attraverso with_raw_response. Registrarlo dopo ogni chiamata è un modo economico per catturare un saldo esaurito prima che lo facciano i tuoi utenti.
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))
Un controllo di calcolo della formula: una chiamata con 2.000 token di input e 500 token di output costa 2.000 x 0,15 / 1.000.000 = $0,0003 per l'input, più 500 x 0,50 / 1.000.000 = $0,00025 per l'output, quindi $0,00055. Mille chiamate di questo tipo ammontano a $0,55. Le richieste fallite o rifiutate non vengono addebitate, quindi un log costruito da oggetti di utilizzo riusciti corrisponderà strettamente al conto.
La fatturazione è pagamento a consumo da credito prepagato senza abbonamento. Le ricariche vanno da $20 a $500 in qualsiasi importo intero, con bonus a partire da $50, e il credito non scade mai; i dettagli sono nella pagina prezzi. I prompt non sono usati per l'addestramento.
Altre guide
Domande e risposte
Esiste un pacchetto Python separato per MiniMax?
Non ne hai bisogno qui. Questo servizio è compatibile con OpenAI, quindi il pacchetto openai standard funziona con un base_url personalizzato. È un servizio indipendente, non l'SDK ufficiale del fornitore.
Il client async funziona?
Sì. AsyncOpenAI accetta gli stessi argomenti base_url e api_key. Tieni il numero di richieste in corso pari o inferiore al tuo limite di concorrenza.
Come ottengo i conteggi dei token?
Ogni risposta non in streaming ha un oggetto usage con prompt_tokens e completion_tokens. Per gli stream, usage viene inviato alla fine, quindi leggilo dall'ultimo chunk se il tuo client lo espone.
Quale lunghezza di contesto posso usare?
La finestra è di 100.000 token, condivisa tra prompt e completamento. max_tokens è opzionale.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.