FR ▾

API MiniMax en Python : utilisez le SDK OpenAI

Vous n'avez pas besoin d'un client spécial pour appeler cette API en Python. Le package openai standard fonctionne une fois que vous avez défini l'URL de base et la clé, et ce guide couvre le chat, le streaming, le JSON, les outils, les tentatives et le calcul des coûts.

Mis à jour

Un ruban de crochets de code lumineux s'entrelaçant à travers des couches d'API empilées, représentant Python appelant une API

Points clés

  • Installez openai, puis passez base_url https://api.minimaxapikey.com/v1 et votre clé au client.
  • Utilisez l'ID de modèle uncensored pour le chat, le streaming, le mode JSON et l'appel d'outils.
  • Gérez le HTTP 429 avec un backoff, et limitez les threads à 8 pour une clé complète, 2 pour une clé d'essai.
  • Lisez l'utilisation de chaque réponse et multipliez par $0,15 et $0,50 par 1M de tokens pour suivre les dépenses.

Installer et effectuer le premier appel

Pour faire fonctionner minimax api python, la méthode la plus rapide est d'utiliser le package officiel openai sur PyPI. Le service derrière ce site est une API hébergée, compatible OpenAI, gérée par un fournisseur indépendant, donc il n'y a pas de SDK séparé à apprendre. Il ne s'agit pas de la plateforme du fournisseur, et les seules modifications par rapport à un script OpenAI standard sont l'URL de base, la clé et le nom du modèle.

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)

Obtenez la clé depuis la page des clés API. Les nouveaux comptes peuvent réclamer $0,50 de crédit d'essai en un clic, sans carte, et il reste valide pendant 7 jours. Gardez la clé dans une variable d'environnement comme indiqué plutôt que de la coller dans les fichiers source.

Paramètres d'échantillonnage et max_tokens

Les paramètres habituels sont transmis : temperature, top_p, stop, seed, ainsi que les pénalités de fréquence et de présence. Un seed fixe avec une température faible vous donne des sorties plus reproductibles pour les tests, bien que vous ne devriez pas le considérer comme une garantie de texte identique.

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 est optionnel. Sans lui, la complétion peut utiliser tout ce qui reste de la fenêtre de 100 000 tokens après votre prompt. C'est utile pour les longs documents, mais définissez une limite dans le code de production. Une génération incontrôlée coûte de vrais tokens de sortie à $0,50 par 1M, et une limite met un plafond aux dégâts d'un mauvais prompt.

Réponses en streaming

Passez stream=True et itérez. La réponse est livrée sous forme d'événements envoyés par le serveur, et le SDK les transforme en objets chunk. Imprimez le texte delta à mesure qu'il arrive pour une interface de chat qui semble réactive.

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)

Les chiffres d'utilisation sont envoyés à la fin du stream. Si votre version du SDK expose un attribut usage sur le dernier chunk, lisez-le là ; sinon, comptez les tokens de votre côté pour la budgétisation. Un point pratique : une requête en streaming occupe son slot de concurrence jusqu'à la fin du stream. Si vous ouvrez huit longs streams sur une clé complète, une neuvième requête obtiendra un 429 avec le code concurrency jusqu'à ce que l'un se termine. Fermez toujours ou consommez entièrement un stream pour libérer le slot.

Mode JSON pour les sorties structurées

Lorsque vous avez besoin d'une sortie lisible par machine, définissez response_format sur un objet JSON. Mentionnez JSON dans le prompt également, et décrivez les clés que vous souhaitez, car le drapeau de format garantit une syntaxe JSON valide mais pas votre schéma.

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"])

Validez toujours le résultat. Vérifiez que les clés requises existent et ont les bons types avant de les utiliser, et décidez ce que votre code fait lorsqu'elles n'existent pas, comme réessayer une fois avec une instruction plus claire. Une couche de validation mince, même quelques vérifications isinstance, économise beaucoup de débogage en production.

Appel d'outils

L'appel d'outils suit la forme OpenAI. Vous décrivez les fonctions dans tools, forcez éventuellement un choix avec tool_choice, et le modèle retourne tool_calls avec des arguments JSON. Vous exécutez la fonction et renvoyez le résultat en tant que message avec 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)

Les tarifs dans cet exemple sont fictifs pour la démo. Dans le code réel, la fonction appellerait votre propre service. Analysez les arguments de manière défensive avec json.loads à l'intérieur d'un bloc try, car un modèle peut occasionnellement émettre des arguments mal formés.

Limites de débit, tentatives et travail parallèle

Une clé complète permet 8 requêtes simultanées et 300 par minute ; une clé d'essai permet 2 simultanées et 60 par minute. Dépasser renvoie HTTP 429. Le code d'erreur est rate_limited pour la limite par minute et concurrency pour trop d'appels simultanés. Une surcharge temporaire donne également un 429, avec un en-tête Retry-After: 5. Le SDK OpenAI réessaie certaines erreurs de lui-même, et vous pouvez augmenter cela avec max_retries. Pour les travaux par lots, ajoutez votre propre limite sur les threads pour rester sous la limite par conception au lieu de réessayer.

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))

Utilisez max_workers=2 sur une clé d'essai. Le client asynchrone, AsyncOpenAI, prend les mêmes arguments ; associez-le à un asyncio.Semaphore(8) pour imposer la même limite. La documentation liste les en-têtes de réponse que vous pouvez inspecter pour les limites.

Gestion de l'historique de conversation

L'API est sans état. Elle ne se souvient pas de l'appel précédent, donc un chat multi-tours fonctionne en envoyant toute la conversation à chaque fois. Gardez une liste de messages, ajoutez le tour de l'utilisateur, appelez l'API, puis ajoutez la réponse de l'assistant avant le tour suivant.

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."))

Ce modèle a un coût qui augmente avec chaque tour : chaque requête paie pour tous les tours précédents à nouveau en tant que tokens d'entrée. Avec une fenêtre de 100 000 tokens, vous avez beaucoup de marge, mais les longues sessions deviennent coûteuses et lentes. Une politique simple est de garder le message système et les N derniers tours, ou de demander au modèle un résumé court des tours plus anciens et de les remplacer par celui-ci. Décidez d'une politique tôt, car ajouter une troncature dans une application de chat est plus gênant que de le construire dès le début.

Gestion des erreurs au-delà du 429

Le SDK lève des exceptions typées, et les trier vaut quelques lignes. Les problèmes d'authentification et les mauvaises requêtes ne se répareront pas d'eux-mêmes lors d'une nouvelle tentative, tandis que les erreurs réseau et la surcharge le feront généralement. Traitez-les différemment.

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"))

Lorsque vous contactez le support, incluez la valeur de X-Request-Id de l'appel échoué. Il identifie cette requête exacte. Définissez un timeout explicite comme indiqué, car la valeur par défaut est longue, et un appel bloqué qui occupe un slot de concurrence réduit silencieusement votre débit. Les requêtes échouées ou refusées ne sont pas facturées, donc réessayer un appel échoué ne double pas la facture.

Une petite structure de projet qui évolue

Les scripts deviennent des services. Une petite structure au début garde les détails de l'API à un seul endroit, donc un changement ultérieur du nom du modèle, du timeout ou des limites touche un fichier au lieu de vingt.

# 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

Chaque autre module importe complete et ne construit jamais un client. Cette seule articulation est l'endroit où vous ajoutez des logs, un compteur de dépenses ou un sémaphore plus tard. Si vous voulez plus de matériel de référence, la page de documentation montre les mêmes endpoints sous forme de curl, ce qui est pratique pour comparer un appel Python défaillant contre une requête connue pour fonctionner.

Le verrouillage de version aide aussi. Épinglez le package openai dans votre fichier requirements et mettez à jour intentionnellement, en lisant d'abord les notes de version, car les changements de SDK peuvent altérer les noms d'exceptions ou le comportement de retry par défaut. Associez cela à une courte note README indiquant quelle URL de base et quel ID de modèle le projet attend, afin qu'un nouveau collègue puisse le faire fonctionner dès le premier jour sans demander.

Un dernier point sur les tests. Écrivez au moins un test qui s'exécute contre un client factice, afin que votre suite ne dépense pas de crédit ou ne dépende pas du réseau. Gardez un seul test de fumée en direct, exécuté à la main ou dans un travail nocturne, pour attraper les changements dans la vraie API tôt.

Suivi du solde et des coûts dans le code

Chaque réponse porte X-Balance-USD, et le SDK vous permet de lire les en-têtes via with_raw_response. Les consigner après chaque appel est un moyen peu coûteux de détecter un solde vidé avant que vos utilisateurs ne le fassent.

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 exemple de vérification de la formule : un appel avec 2 000 tokens d'entrée et 500 tokens de sortie coûte 2 000 x 0,15 / 1 000 000 = $0,0003 pour l'entrée, plus 500 x 0,50 / 1 000 000 = $0,00025 pour la sortie, soit $0,00055. Un millier de tels appels s'élèvent à $0,55. Les requêtes échouées ou refusées ne sont pas facturées, donc un journal construit à partir d'objets d'utilisation réussis correspondra étroitement à la facture.

La facturation est paiement à l'usage à partir de crédit prépayé sans abonnement. Les recharges vont de $20 à $500 dans n'importe quel montant entier, avec des bonus à partir de $50, et le crédit n'expire jamais ; les détails sont sur la page des tarifs. Les prompts ne sont pas utilisés pour l'entraînement.

Questions et réponses

Existe-t-il un package Python séparé pour MiniMax ?

Vous n'en avez pas besoin ici. Ce service est compatible OpenAI, donc le package openai standard fonctionne avec une base_url personnalisée. Il s'agit d'un service indépendant, pas du SDK officiel du fournisseur.

Le client asynchrone fonctionne-t-il ?

Oui. AsyncOpenAI prend les mêmes arguments base_url et api_key. Maintenez le nombre de requêtes en cours à ou en dessous de votre limite de concurrence.

Comment obtenir les comptes de tokens ?

Chaque réponse non streaming a un objet usage avec prompt_tokens et completion_tokens. Pour les streams, usage est envoyé à la fin, donc lisez-le depuis le dernier chunk si votre client l'expose.

Quelle longueur de fenêtre de contexte puis-je utiliser ?

La fenêtre est de 100 000 tokens, partagée entre le prompt et la complétion. max_tokens est optionnel.

Votre clé est à un formulaire près

Créez un compte, copiez la clé, modifiez l'URL de base. C'est toute la configuration.

Obtenir une clé API