Los modelos de texto de MiniMax ofrecen una interfaz compatible con OpenAI. Un SDK existente de OpenAI suele necesitar solo tres cambios: la Base URL, la clave de API y el nombre del modelo. Aun así, en la práctica la integración se atasca en el dominio de la región, las mayúsculas del nombre del modelo, el contenido de razonamiento y los parámetros de tokens. Este artículo sigue el orden «dirección, modelo, llamada, diagnóstico y migración» para completar la primera llamada.

La conclusión inicial: la dirección oficial compatible con OpenAI termina en /v1 y el endpoint de chat es /v1/chat/completions; el nombre del modelo debe coincidir exactamente con la documentación oficial; el código nuevo debería usar max_completion_tokens y reservar presupuesto de salida para el contenido de razonamiento.

Nota: MiniMax es una marca registrada de su propietario y este artículo solo tiene fines técnicos. Los nombres de modelo, las interfaces, el contexto y los límites se rigen por la documentación oficial de MiniMax y por la página de precios de modelos. Verifica en la consola los nombres de modelo de los ejemplos antes de usarlos en producción.

1. Base URL: elige primero la región y el protocolo

MiniMax tiene dos dominios, uno para China y otro internacional, y además tres entradas: compatible con OpenAI, compatible con Anthropic y nativa. La opción más común es la compatible con OpenAI: sitio internacional https://api.minimax.io/v1, sitio para China https://api.minimax.cn/v1, con el endpoint de chat POST /v1/chat/completions.

Si usas el SDK de Anthropic o herramientas como Claude Code, la entrada recomendada es la compatible con Anthropic: sitio internacional https://api.minimax.io/anthropic, sitio para China https://api.minimax.cn/anthropic, con el endpoint de mensajes POST /anthropic/v1/messages. La interfaz nativa anterior POST /v1/text/chatcompletion_v2 sigue existiendo, pero las integraciones nuevas deberían preferir las interfaces compatibles, con parámetros y ecosistema más uniformes.

Escenario Base URL Endpoint típico
Compatible con OpenAI (internacional) https://api.minimax.io/v1 POST /v1/chat/completions
Compatible con OpenAI (China) https://api.minimax.cn/v1 POST /v1/chat/completions
Compatible con Anthropic (internacional) https://api.minimax.io/anthropic POST /anthropic/v1/messages
Compatible con Anthropic (China) https://api.minimax.cn/anthropic POST /anthropic/v1/messages
Interfaz nativa de texto https://api.minimax.io o https://api.minimax.cn POST /v1/text/chatcompletion_v2
Gateway ZSQH https://ai.zhongshangqihang.com/v1 POST /v1/chat/completions

La dirección de la tabla y la clave deben provenir de la misma plataforma. Una clave del sitio para China con la dirección internacional suele devolver 401 de inmediato; una clave del gateway con la dirección oficial produce el mismo resultado. Hay otro error frecuente: la Base URL ya incluye /v1 y la ruta de la solicitud vuelve a añadirlo, hasta formar /v1/v1/chat/completions.

2. Nombre del modelo: mayúsculas y versión deben coincidir

A octubre de 2026, la documentación oficial lista como modelos de texto actuales MiniMax-M3.1-Flash y MiniMax-M3, con una ventana de contexto de 1.000.000 de tokens. MiniMax-M3.1-Flash permite ajustar la profundidad de razonamiento; MiniMax-M3 es el modelo multimodal de codificación de la misma generación.

Los modelos de la generación anterior siguen apareciendo en la documentación: MiniMax-M2.7, MiniMax-M2.7-highspeed, MiniMax-M2.5, MiniMax-M2.5-highspeed, MiniMax-M2.1, MiniMax-M2.1-highspeed y MiniMax-M2, con 204.800 tokens de contexto. También existe MiniMax-M2-her, con 64K de contexto. Los nombres distinguen mayúsculas y guiones, así que cópialos en lugar de escribirlos a mano.

Si usas el gateway de ZSQH, los nombres de modelo se rigen por la página de precios de modelos y pueden diferir de la nomenclatura oficial. No fijes el nombre del modelo dentro del código: colócalo en una variable de entorno o en un centro de configuración para cambiarlo sin tocar la lógica.

3. curl: primero una solicitud sin streaming

Prepara la variable de entorno MINIMAX_API_KEY con la clave. El ejemplo usa la interfaz compatible con OpenAI del sitio para China; para el internacional cambia el dominio a api.minimax.io, y para el gateway usa su dirección. No actives el streaming todavía: confirma primero la estructura de respuesta.

export MINIMAX_API_KEY="tu_clave"

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": "Eres un asistente breve."},
      {"role": "user", "content": "Explica en tres frases qué es una Base URL."}
    ],
    "max_completion_tokens": 512,
    "stream": false
  }'

En el JSON de respuesta, choices[0].message.content contiene la respuesta final. Con la serie M3, el contenido de razonamiento suele aparecer en el campo reasoning_content, mientras que content solo lleva la respuesta final. No mezcles ambos en la presentación salvo que tu producto quiera mostrar el proceso de razonamiento.

Si usas el gateway, cambia a la vez la dirección, la clave y el nombre del modelo. Cambiar solo uno de los tres suele producir un vaivén entre 401 y model not found.

4. Python: llamada con el SDK de OpenAI

Después de instalar openai, apunta base_url a la dirección compatible de MiniMax. El ejemplo coloca la dirección y el modelo en variables de entorno para alternar entre la plataforma oficial y el gateway.

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": "Eres un asistente breve."},
        {"role": "user", "content": "Escribe un ejemplo en Python que lea un CSV y cuente sus filas."},
    ],
    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 la respuesta en streaming, el razonamiento aparece en delta.reasoning_content y el texto en delta.content; con stream_options.include_usage en true, el último fragmento incluye el consumo. Distintas versiones del SDK pueden ubicar los campos desconocidos en lugares diferentes, así que imprime una vez la respuesta sin procesar en el entorno de pruebas antes de leerla.

5. Tokens y parámetros de muestreo: no cambies solo max_tokens

En integraciones nuevas, usa max_completion_tokens para controlar la longitud de salida; max_tokens figura como parámetro antiguo en la documentación y puede seguir siendo compatible, pero no conviene depender de él en código nuevo. Los tokens de razonamiento de la serie M3 también cuentan dentro del límite de salida; si el límite es demasiado bajo, aparecerá finish_reason: "length" con content vacío.

Parámetros habituales:

  • temperature: controla la aleatoriedad; el rango válido depende de la documentación vigente y un valor fuera de rango devuelve 400.
  • top_p: 0.95 por defecto en la serie M3 y 0.9 en M2.x; normalmente se ajusta solo uno de los dos.
  • reasoning_effort: la serie M3 admite low, medium, high, xhigh y max, con max por defecto; bajarlo puede reducir latencia y tokens de salida.
  • thinking: MiniMax-M3.1-Flash fuerza el razonamiento y enviar disabled devuelve 400; para otros modelos, consulta la documentación.
  • n: solo admite 1; parámetros como presence_penalty y frequency_penalty pueden ignorarse.
  • Llamada a herramientas: usa tools, no el antiguo function_call; en conversaciones con varias rondas, devuelve el mensaje completo del asistente, incluidos tool_calls y el razonamiento, al historial.

Si la latencia es alta, baja primero reasoning_effort y luego acorta los límites de entrada y salida; no cambies de modelo de inmediato. En los modelos con razonamiento, la calidad y la latencia suelen moverse juntas, así que muchos escenarios no necesitan un modelo más pequeño si los parámetros están bien ajustados.

6. Errores comunes: ubica el problema por código de estado

  • 401: clave ausente, formato incorrecto o clave que no corresponde al sitio o al gateway. Revisa Authorization: Bearer y la Base URL.
  • 404: ruta incorrecta, o Base URL con /v1 de más o de menos. La dirección compatible con OpenAI termina en /v1 y luego se añade /chat/completions.
  • model not found o model_not_found: nombre mal escrito, mayúsculas incorrectas o cuenta sin permiso para ese modelo. Copia el nombre desde la documentación o la página de precios.
  • 400: parámetro fuera de rango, por ejemplo temperature excedido, thinking: disabled en M3.1-Flash o un valor no admitido en reasoning_effort.
  • finish_reason: "length" con contenido vacío: el límite de salida es demasiado bajo y los tokens de razonamiento agotaron el presupuesto. Aumenta max_completion_tokens.
  • 429: límite de tasa alcanzado. La documentación ofrece como referencia 200 RPM y 10.000.000 TPM para la serie M3, y 500 RPM y 20.000.000 TPM para M2.x; lo válido es lo que indique la cuenta y la consola. Reduce la concurrencia y añade reintentos con retroceso.
  • 5xx o tiempo de espera agotado: fluctuación del proveedor o problema de red. Configura tiempos de espera, retroceso exponencial y un modelo de respaldo; no reintentes sin límite.

Las cifras de límite de tasa son solo una referencia de la documentación oficial en octubre de 2026 y pueden variar según cuenta, modelo e interfaz. En producción, guíate por la consola y por lo que observes en la práctica; no llenes la concurrencia siguiendo los números de la documentación.

7. Lista de verificación para la migración

  1. Confirma la plataforma de destino: sitio oficial para China, sitio oficial internacional o gateway de ZSQH. La clave y la Base URL deben venir de la misma plataforma.
  2. Cambia base_url: /v1 para la interfaz compatible con OpenAI y /anthropic para la compatible con Anthropic; no los mezcles.
  3. Cambia el nombre del modelo: cópialo de la documentación o de precios de modelos y revisa mayúsculas, guiones y número de versión.
  4. Ajusta los parámetros de salida: prefiere max_completion_tokens y deja presupuesto suficiente para los tokens de razonamiento.
  5. Revisa el análisis del streaming: el texto está en delta.content y el razonamiento en delta.reasoning_content; no supongas que solo hay un campo.
  6. Revisa la llamada a herramientas: usa tools y devuelve el mensaje completo del asistente con su razonamiento como exige la plataforma.
  7. Añade tiempos de espera, reintentos y cortacircuitos: aplica retroceso exponencial a 429 y 5xx y fija un tiempo máximo por solicitud.
  8. Añade registros y monitoreo de consumo: guarda modelo, duración, tokens de entrada y salida y códigos de error, sin imprimir la clave.
  9. Cambia el tráfico de forma gradual: empieza por un negocio de bajo riesgo, compara calidad y costo, y luego amplía.
  10. Prepara la reversión: conserva la configuración y la clave anteriores durante un tiempo y límpialas cuando confirmes estabilidad.

Esta lista también sirve para migrar de OpenAI a MiniMax o de la conexión oficial al gateway. Lo esencial no es cambiar una línea de Base URL, sino revisar juntos autenticación, modelo, parámetros, análisis de streaming y monitoreo.

8. ¿Conexión oficial o gateway?

Si solo usas MiniMax, el consumo es estable y puedes completar el registro y la liquidación con el proveedor, la conexión oficial es la ruta más corta. Si necesitas varios modelos, una factura unificada, una sola clave o reducir la cantidad de configuraciones en la red local, el gateway resulta más adecuado.

Al elegir un gateway, confirma cuatro puntos: qué modelos de MiniMax admite, si es compatible con la interfaz que usas (OpenAI o Anthropic), si el criterio de facturación es claro y por dónde recibir soporte ante anomalías. Prueba con poco volumen y luego envía tráfico de producción. Puedes revisar modelos y facturación en precios de modelos y crear una clave de prueba desde el registro.

Preguntas frecuentes

¿Cuál es la Base URL de la API de MiniMax?

Para la interfaz compatible con OpenAI, el sitio internacional usa https://api.minimax.io/v1 y el sitio para China usa https://api.minimax.cn/v1. Para la compatible con Anthropic se usan https://api.minimax.io/anthropic y https://api.minimax.cn/anthropic. Guíate por el sitio en el que te registraste.

¿La API de MiniMax es compatible con el SDK de OpenAI?

Es compatible con las interfaces de chat habituales. Apunta base_url a la dirección /v1 de MiniMax y cambia el nombre del modelo por el de MiniMax. La compatibilidad no implica identidad total: los campos de razonamiento, los parámetros de tokens y los detalles de la llamada a herramientas aún presentan diferencias.

¿Por qué la respuesta llega vacía con finish_reason length?

El límite de salida se agotó con los tokens de razonamiento. La serie M3 cuenta el razonamiento dentro del presupuesto de salida; aumenta max_completion_tokens y revisa si hay un max_tokens demasiado bajo.

¿Se puede desactivar el razonamiento?

MiniMax-M3.1-Flash fuerza el razonamiento y devuelve 400 si se envía thinking: disabled. Para saber si otros modelos permiten desactivarlo, consulta la documentación vigente; si quieres reducir latencia, baja primero reasoning_effort.

¿Qué cambios exige migrar desde OpenAI?

Como mínimo, la clave, la Base URL, el nombre del modelo y los parámetros de salida; después revisa los campos de streaming, la llamada a herramientas, los tiempos de espera, los reintentos y los registros. Conviene ejecutar primero un curl sin streaming, luego Python con streaming y, por último, un cambio gradual de tráfico.

Próximos pasos

Elige un modelo, ejecuta una solicitud sin streaming con curl y después una con streaming en Python. Cuando content y reasoning_content se analicen correctamente, integra el flujo en tu aplicación. Si necesitas una entrada unificada, puedes registrarte en ZSQH AI Gateway y revisar los modelos disponibles y la facturación en la página de precios de modelos.

Lecturas relacionadas: