Les modèles texte de MiniMax proposent une interface compatible OpenAI : un SDK OpenAI existant ne demande généralement que trois changements — l'URL de base, la clé API et le nom du modèle. En pratique, l'intégration bloque souvent sur le domaine régional, la casse du nom de modèle, le contenu de raisonnement et les paramètres de tokens. Cet article suit l'ordre « adresse — modèle — appel — diagnostic — migration » pour réaliser le premier appel.

Conclusion rapide : l'adresse officielle compatible OpenAI se termine par /v1, et le point de terminaison de chat est /v1/chat/completions ; le nom du modèle doit correspondre exactement à la documentation officielle ; le nouveau code privilégie max_completion_tokens et réserve un budget de sortie pour le raisonnement.

Note : MiniMax est une marque de son titulaire ; cet article est purement technique. Les noms de modèles, interfaces, contextes et limites suivent la documentation officielle MiniMax et la page Tarifs du site. Vérifiez les noms de modèles dans la console avant tout usage en production.

1. URL de base : choisir d'abord la région et le protocole

MiniMax dispose aujourd'hui de deux domaines, site Chine et site international, et de trois points d'entrée : compatible OpenAI, compatible Anthropic et interface native. Le choix le plus courant est la compatibilité OpenAI : site international https://api.minimax.io/v1, site Chine https://api.minimax.cn/v1, point de terminaison de chat POST /v1/chat/completions.

Si vous utilisez le SDK Anthropic ou un outil comme Claude Code, l'entrée compatible Anthropic est recommandée : site international https://api.minimax.io/anthropic, site Chine https://api.minimax.cn/anthropic, point de terminaison de messages POST /anthropic/v1/messages. L'ancienne interface native POST /v1/text/chatcompletion_v2 existe toujours, mais les nouvelles intégrations privilégient l'interface compatible, plus homogène en paramètres et en écosystème.

Scénario URL de base Point de terminaison typique
Officiel compatible OpenAI (international) https://api.minimax.io/v1 POST /v1/chat/completions
Officiel compatible OpenAI (Chine) https://api.minimax.cn/v1 POST /v1/chat/completions
Officiel compatible Anthropic (international) https://api.minimax.io/anthropic POST /anthropic/v1/messages
Officiel compatible Anthropic (Chine) https://api.minimax.cn/anthropic POST /anthropic/v1/messages
Interface texte native https://api.minimax.io ou https://api.minimax.cn POST /v1/text/chatcompletion_v2
Passerelle ZSQH https://ai.zhongshangqihang.com/v1 POST /v1/chat/completions

L'adresse du tableau doit venir de la même plateforme que la clé. Une clé du site Chine avec l'adresse internationale renvoie généralement un 401 ; une clé de passerelle avec l'adresse officielle donne le même résultat. Autre erreur fréquente : l'URL de base contient déjà /v1 et le chemin de requête l'ajoute une seconde fois, produisant /v1/v1/chat/completions.

2. Nom du modèle : respecter la casse et la version

Depuis octobre 2026, la documentation officielle liste comme modèles texte courants MiniMax-M3.1-Flash et MiniMax-M3, avec une fenêtre de contexte de 1 000 000 tokens. MiniMax-M3.1-Flash permet de régler la profondeur de raisonnement ; MiniMax-M3 est le modèle de codage multimodal de la même génération.

La génération précédente reste documentée : MiniMax-M2.7, MiniMax-M2.7-highspeed, MiniMax-M2.5, MiniMax-M2.5-highspeed, MiniMax-M2.1, MiniMax-M2.1-highspeed, MiniMax-M2, avec un contexte de 204 800 tokens. Il existe aussi MiniMax-M2-her, avec un contexte de 64K. Les noms de modèles distinguent la casse et les traits d'union : copiez-les, ne les retapez pas.

Si vous passez par la passerelle ZSQH, les noms de modèles suivent la page Tarifs et peuvent différer des noms officiels. Ne figez pas le nom du modèle dans le code : placez-le dans une variable d'environnement ou un centre de configuration, et ne changez que la configuration lors d'une bascule.

3. curl : valider d'abord une requête non streaming

Préparez la variable d'environnement MINIMAX_API_KEY avec la clé. L'exemple ci-dessous utilise l'interface compatible OpenAI du site Chine ; pour l'international, remplacez le domaine par api.minimax.io, et pour la passerelle, par l'adresse de la passerelle. N'activez pas le streaming tout de suite : confirmez d'abord la structure de réponse.

export MINIMAX_API_KEY="votre_cle"

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": "Tu es un assistant concis qui répond en français."},
      {"role": "user", "content": "Explique en trois phrases ce qu'est une URL de base."}
    ],
    "max_completion_tokens": 512,
    "stream": false
  }'

Dans le JSON retourné, choices[0].message.content contient la réponse finale. Avec la série M3, le raisonnement se trouve généralement dans reasoning_content, et content ne contient que la réponse finale. Ne mélangez pas les deux à l'affichage, sauf si votre produit doit montrer le raisonnement.

Si vous passez par la passerelle, changez ensemble l'adresse, la clé et le nom du modèle. N'en changer qu'un seul fait généralement osciller entre 401 et model not found.

4. Python : appeler avec le SDK OpenAI

Après installation de openai, pointez base_url vers l'adresse compatible MiniMax. L'exemple place l'adresse et le modèle dans des variables d'environnement, pour basculer facilement entre l'officiel et la passerelle.

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": "Tu es un assistant concis qui répond en français."},
        {"role": "user", "content": "Écris un exemple Python qui lit un CSV et compte les lignes."},
    ],
    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="")

En streaming, le raisonnement se trouve dans delta.reasoning_content et le texte dans delta.content ; avec stream_options.include_usage à true, le dernier chunk porte l'usage. Selon la version du SDK, les champs inconnus peuvent être placés différemment : imprimez une fois la réponse brute dans l'environnement de test avant de la lire.

5. Tokens et paramètres d'échantillonnage : ne changez pas que max_tokens

Pour une nouvelle intégration, privilégiez max_completion_tokens pour contrôler la longueur de sortie ; max_tokens est marqué comme ancien paramètre dans la documentation officielle, encore toléré, mais à ne pas utiliser dans le nouveau code. Les tokens de raisonnement de la série M3 comptent aussi dans la limite de sortie : une limite trop basse produit finish_reason: "length" avec un content vide.

Paramètres courants :

  • temperature : contrôle l'aléatoire ; la plage acceptée suit la documentation courante, une valeur hors plage renvoie 400.
  • top_p : par défaut 0,95 pour la série M3 et 0,9 pour M2.x ; ne réglez généralement qu'un des deux.
  • reasoning_effort : la série M3 accepte low, medium, high, xhigh et max, avec max par défaut ; baisser réduit la latence et les tokens de sortie.
  • thinking : MiniMax-M3.1-Flash force le raisonnement ; passer disabled renvoie 400. Le support des autres modèles suit la documentation.
  • n : seule la valeur 1 est prise en charge ; presence_penalty, frequency_penalty et d'autres paramètres peuvent être ignorés.
  • Appel d'outils : utilisez tools, pas l'ancien function_call ; en multi-tours, renvoyez l'historique complet du message assistant, y compris tool_calls et le raisonnement.

En cas de latence élevée, baissez d'abord reasoning_effort, puis raccourcissez les limites d'entrée et de sortie, avant de changer de modèle. Pour un modèle de raisonnement, qualité et latence évoluent ensemble : bien réglé, il évite souvent de passer à un modèle plus petit.

6. Erreurs fréquentes : localiser par code de statut

  • 401 : clé absente, mal formée, ou incompatible avec le site ou la passerelle. Vérifiez Authorization: Bearer et l'URL de base.
  • 404 : chemin incorrect, ou /v1 en trop ou manquant dans l'URL de base. L'adresse compatible OpenAI se termine par /v1, puis on ajoute /chat/completions.
  • model not found ou model_not_found : nom mal orthographié, casse incorrecte, ou compte sans permission sur ce modèle. Copiez depuis la documentation ou la page tarifaire.
  • 400 : paramètre hors limites, par exemple temperature hors plage, thinking: disabled envoyé à M3.1-Flash, ou valeur non prise en charge pour reasoning_effort.
  • finish_reason: "length" avec contenu vide : limite de sortie trop basse, les tokens de raisonnement ont consommé le budget. Augmentez max_completion_tokens.
  • 429 : limitation de débit. La documentation officielle donne comme référence 200 RPM et 10 000 000 TPM pour la série M3, 500 RPM et 20 000 000 TPM pour M2.x ; l'état réel dépend du compte et de la console. Réduisez la concurrence et ajoutez du backoff.
  • 5xx ou timeout : fluctuation amont ou problème réseau. Configurez timeouts, backoff exponentiel et modèle de secours, sans retries illimités.

Ces chiffres de limitation ne sont que des références de la documentation officielle d'octobre 2026 ; ils varient selon le compte, le modèle et l'interface. En production, fiez-vous à la console et aux observations réelles : ne saturez pas la concurrence en recopiant les chiffres de la documentation.

7. Checklist de migration

  1. Confirmer la plateforme cible : site officiel Chine, site officiel international ou passerelle ZSQH. La clé et l'URL de base doivent venir de la même plateforme.
  2. Changer base_url : /v1 pour la compatibilité OpenAI, /anthropic pour la compatibilité Anthropic, sans mélanger.
  3. Changer le nom du modèle : copier depuis la documentation officielle ou Tarifs, en respectant casse, traits d'union et numéro de version.
  4. Changer les paramètres de sortie : privilégier max_completion_tokens et réserver un budget suffisant aux tokens de raisonnement.
  5. Vérifier l'analyse du streaming : lire delta.content pour le texte et delta.reasoning_content pour le raisonnement, sans supposer un champ unique.
  6. Vérifier l'appel d'outils : utiliser tools et renvoyer le message assistant complet avec le raisonnement, comme demandé officiellement.
  7. Ajouter timeouts, retries et disjoncteur : backoff exponentiel sur 429 et 5xx, timeout par requête.
  8. Ajouter journaux et supervision d'usage : nom du modèle, durée, tokens d'entrée et de sortie, codes d'erreur, sans jamais journaliser la clé.
  9. Basculer en progressif : commencer par une activité à faible risque, comparer qualité et coût, puis élargir.
  10. Préparer le retour arrière : conserver l'ancienne configuration et l'ancienne clé un certain temps, puis nettoyer après stabilisation.

Cette checklist vaut aussi pour une migration d'OpenAI vers MiniMax, ou d'un accès direct vers une passerelle. Le cœur de la migration n'est pas de changer une ligne d'URL de base, mais de vérifier ensemble authentification, modèles, paramètres, analyse du streaming et supervision.

8. Accès direct officiel ou passerelle

Si vous n'intégrez que MiniMax, avec un usage stable et une inscription et un règlement officiels réalisables directement, l'accès direct est le plus court. Si vous devez intégrer plusieurs modèles, unifier la facturation et les clés, ou réduire le nombre de configurations à maintenir sur le réseau chinois, une passerelle est plus adaptée.

Pour choisir une passerelle, vérifiez quatre points : quels modèles MiniMax sont pris en charge, si l'interface utilisée (OpenAI ou Anthropic) est compatible, si la règle de facturation est claire, et quel canal de support existe en cas d'anomalie. Testez d'abord avec un petit montant, puis envoyez le trafic de production. Consultez Tarifs pour les modèles et la facturation, et créez une clé de test depuis l'inscription.

Questions fréquentes

Quelle est l'URL de base de l'API MiniMax ?

Pour la compatibilité OpenAI, le site international utilise https://api.minimax.io/v1 et le site Chine https://api.minimax.cn/v1. Pour la compatibilité Anthropic : https://api.minimax.io/anthropic et https://api.minimax.cn/anthropic. Faites référence au site sur lequel vous êtes inscrit.

L'API MiniMax est-elle compatible avec le SDK OpenAI ?

Elle est compatible avec les interfaces de chat courantes. Pointez base_url vers l'adresse /v1 de MiniMax et remplacez le nom du modèle par celui de MiniMax. Mais compatibilité ne signifie pas identité : champs de raisonnement, paramètres de tokens et détails d'appel d'outils diffèrent encore.

Pourquoi le contenu est-il vide avec finish_reason à length ?

La limite de sortie a été consommée par les tokens de raisonnement. La série M3 compte le raisonnement dans le budget de sortie : augmentez d'abord max_completion_tokens, puis vérifiez qu'un max_tokens trop bas n'est pas défini.

Peut-on désactiver le raisonnement ?

MiniMax-M3.1-Flash force le raisonnement ; passer thinking: disabled renvoie 400. Le support de la désactivation sur les autres modèles suit la documentation officielle actuelle ; pour réduire la latence, baissez d'abord reasoning_effort.

Que faut-il changer pour migrer depuis OpenAI ?

Au minimum la clé, l'URL de base, le nom du modèle et les paramètres de sortie ; vérifiez ensuite les champs de streaming, l'appel d'outils, les timeouts et les journaux. Il est conseillé de lancer d'abord un curl non streaming, puis un Python en streaming, et enfin une bascule progressive.

Étape suivante

Choisissez un modèle, validez une requête non streaming avec curl, puis une requête streaming en Python ; une fois content et reasoning_content correctement analysés, branchez le métier. Pour un point d'entrée unifié, créez un compte ZSQH AI Gateway et vérifiez les modèles et la facturation sur la page Tarifs.

Pour aller plus loin