Las claves de API de MiniMax suelen provenir de dos lugares: la plataforma abierta de MiniMax y puntos de entrada compatibles como ZSQH AI Gateway. Ambos permiten llamar a los modelos, pero el registro, el alcance de la clave y la facturación funcionan por separado. Este artículo sigue el orden real de operación —registro, creación, almacenamiento, aislamiento de permisos, rotación y diagnóstico de errores 401— y al final ofrece criterios para elegir entre una clave oficial y una del gateway.

Para los equipos que integran por primera vez, conviene recordar una idea: una clave no es mejor por ser más universal, sino por estar separada por entorno, por persona y por uso, de modo que se pueda desactivar, rastrear y reemplazar. Así, si una clave falla, no arrastra toda la operación.

Nota: MiniMax es una marca registrada de su propietario y este artículo solo tiene fines técnicos. Los puntos de entrada, la gestión de claves y los límites se rigen por la documentación y la consola de MiniMax; los modelos y los criterios de facturación se consultan en la página de precios de modelos.

1. Primero, distingue tres tipos de clave

En la plataforma de MiniMax suelen existir dos clases de clave: la clave de interfaz de pago por uso y la clave de suscripción asociada al plan M. La primera se crea en la página de claves de interfaz de la cuenta y cubre modelos de lenguaje, video, voz e imagen. La segunda se consulta en la página de suscripción y facturación, y se usa para el plan M y los créditos ya comprados. La tercera es la clave de ZSQH AI Gateway, que solo es válida dentro del gateway y sirve para llamar de forma unificada a varios modelos habilitados.

No mezcles las tres clases. El incidente más común consiste en pegar una clave oficial en la dirección del gateway, o enviar una clave del gateway a la interfaz oficial, y luego revisar el código una y otra vez hasta descubrir que solo había un desajuste entre dirección y clave.

Tipo de clave Dónde se crea o consulta Alcance Cuándo conviene
Clave oficial de pago por uso Plataforma abierta, sección de claves de interfaz Modelos e interfaces habilitados en la cuenta oficial Solo MiniMax, liquidación directa con el proveedor
Clave oficial del plan M Página de suscripción y facturación Suscripción al plan M y créditos comprados Suscripciones ya adquiridas, uso por paquete
Clave del gateway Consola de ZSQH AI Gateway Modelos habilitados dentro del gateway Entrada única para varios modelos y factura única

2. Registro: confirma primero si es el sitio para China o el internacional

MiniMax tiene dos entradas: platform.minimax.cn y platform.minimax.io. Los accesos, las consolas y las Base URL son distintos, así que antes de registrarte confirma a cuál puede acceder tu equipo y cuál se adapta mejor a tu forma de pago. No te registres en el sitio para China y luego configures la clave contra la dirección internacional.

Para trabajo en equipo se recomienda una cuenta principal con subcuentas. La documentación del sitio para China indica que la cuenta principal puede crear subcuentas; estas comparten los beneficios, los límites de tasa y el consumo y la facturación de la API, pero no pueden ver ni administrar los pagos. Así cada persona tiene su propia identidad de acceso y, cuando alguien deja el equipo, basta con desactivar su subcuenta en lugar de compartir la contraseña principal.

Si la consola pide datos de empresa o algún método de verificación adicional, completa lo que muestre la página y guíate por el flujo que veas al registrarte.

3. Pasos para crear una clave

  1. Inicia sesión en la plataforma abierta de MiniMax y entra en la página de claves de interfaz del centro de usuario. En el sitio para China, la ruta es platform.minimax.cn/user-center/basic-information/interface-key.
  2. Pulsa la opción para crear una clave y dale un nombre claro, por ejemplo prod-atencion-cliente o test-zhang.
  3. Selecciona o confirma el alcance disponible según las opciones de la página. Si no hay permisos por modelo, significa que el control actual se basa en la cuenta.
  4. Copia la clave de inmediato y guárdala en un gestor de contraseñas o en un servicio de gestión de secretos. No la envíes por captura de pantalla a un grupo ni la escribas en comentarios del código.
  5. Si usas el plan M, la clave de suscripción no está en la página de claves de interfaz, sino en la de suscripción y facturación.
  6. Verifica la clave con una solicitud mínima y confirma que la región, la Base URL y el nombre del modelo coincidan.
  7. Registra en el inventario del equipo el responsable de la clave, su uso, la fecha de creación y la condición para desactivarla.

Sobre el paso 3 conviene ser explícito: según la documentación pública, no existe una guía general de permisos de clave por modelo; lo que muestre la consola es lo que vale. Si necesitas separar negocios, usa subcuentas o claves independientes por entorno en lugar de esperar que una sola clave lo controle todo.

4. Aislamiento de permisos: una clave por entorno

Como mínimo, separa tres entornos: desarrollo, preproducción y producción. La clave de producción solo debe vivir en variables de entorno del servidor o en un servicio de gestión de secretos, nunca en el navegador, en aplicaciones móviles o en clientes de escritorio. Una clave de prueba puede tener una cuota menor, lo que facilita desactivarla en cualquier momento.

Si el equipo tiene varias líneas de negocio, separa también por uso: una clave para atención al cliente, otra para generación de contenido y otra para procesamiento por lotes. Así, si una línea presenta anomalías, puedes desactivar solo su clave sin afectar a las demás, y localizar el consumo con mayor facilidad.

El objetivo del aislamiento no es añadir trámites, sino poner límites a los fallos. Una clave que atiende todos los negocios ahorra trabajo a corto plazo y complica el diagnóstico a largo plazo.

5. Guarda la clave en variables de entorno

No escribas la clave dentro del código. El ejemplo mínimo es el siguiente; el archivo .env solo debe usarse en local, mientras que en producción conviene el gestor de secretos de la plataforma o los secretos del contenedor.

# .env (no lo confirmes en Git)
MINIMAX_API_KEY=tu_clave
# Ejemplo del sitio para China; con el gateway usa su dirección y el nombre de modelo del sitio
MINIMAX_BASE_URL=https://api.minimax.cn/v1
MINIMAX_MODEL=MiniMax-M3.1-Flash

# .gitignore
.env
.env.*

En Python, lee la clave con os.environ["MINIMAX_API_KEY"] y no la pongas como valor predeterminado en los parámetros de una función. Ten en cuenta tres puntos: primero, .env debe estar en .gitignore; segundo, no incluyas la clave en capas de imágenes de contenedor ni en CI; tercero, enmascara los encabezados antes de imprimirlos en los registros, para no dejar Authorization escrito en los logs.

Si usas un servicio de gestión de secretos, asigna al aplicación permisos de solo lectura y registra cada lectura. Tampoco copies la clave en herramientas de chat ni en el cuerpo de documentos.

6. Rotación y respuesta ante filtraciones

La documentación oficial no fija un ciclo de rotación obligatorio, así que conviene definirlo según el riesgo: rota las claves críticas de producción cada 90 días y hazlo de inmediato ante cambios de personal, pérdida de dispositivos o sospecha de filtración.

El orden recomendado es crear la nueva, cambiar el tráfico y después desactivar la antigua:

  • Crea la clave nueva con la fecha en el nombre, por ejemplo prod-2026-10.
  • Guárdala en el gestor de secretos y valídala primero en preproducción.
  • Desvía el tráfico de producción de forma gradual y observa la tasa de errores y el consumo.
  • Cuando confirmes estabilidad, desactiva la clave anterior y conserva el registro de la operación.
  • Revisa si la clave antigua tuvo llamadas anómalas antes de desactivarla.

Si sospechas una filtración, no te limites a cambiar una cadena en el código. Desactiva o elimina la clave en la consola de inmediato, crea una nueva, revisa la facturación y los registros de llamadas y, si hace falta, contacta al soporte de la plataforma. La documentación también menciona que una clave expuesta públicamente puede ser desactivada automáticamente, pero no conviene depender de esa medida como única protección.

7. Diagnóstico de errores 401: primero la dirección, después la clave

Un 401 significa fallo de autenticación; no equivale a saldo insuficiente ni a límite de tasa. Revisa en este orden:

  • ¿El encabezado es Authorization: Bearer <clave>, con un espacio entre Bearer y la clave?
  • ¿La clave se copió completa, sin espacios, saltos de línea ni comillas alrededor?
  • ¿Una clave del sitio para China apunta a la dirección de ese sitio, y una internacional a la internacional?
  • ¿Una clave oficial se cargó por error en la dirección del gateway, o una clave del gateway en la dirección oficial?
  • ¿La clave fue eliminada, desactivada o pertenece a una suscripción vencida?
  • ¿La variable de entorno se cargó realmente? En un contenedor, imprime el nombre de la variable, nunca su valor.

Si recibes un 403, suele tratarse de permisos o cuota; un 429 apunta a límite de tasa; mensajes como insufficient balance sí indican saldo. Trata el 401 por separado de estos casos.

8. Cómo elegir entre clave oficial y clave del gateway

Si solo usas MiniMax, puedes completar el registro y la liquidación directamente con el proveedor y tu equipo puede administrar las claves de cada proveedor, la conexión directa es la ruta más simple. Si necesitas combinar MiniMax, Claude, GPT, DeepSeek y otros modelos, o prefieres una sola clave, una factura unificada y una vista común de consumo, el gateway reduce la administración.

El gateway implica una dependencia adicional, así que confirma tres cosas: qué modelos de MiniMax admite, si el criterio de facturación es claro y por dónde recibir soporte si algo falla. Prueba primero 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

¿Dónde se crea una clave de API de MiniMax?

La clave oficial de pago por uso se crea en la página de claves de interfaz del centro de usuario de la plataforma abierta; la clave de suscripción del plan M se consulta en la página de suscripción y facturación. La ruta exacta depende de la consola del sitio que uses.

¿Una sola clave puede llamar a texto, voz y video al mismo tiempo?

La clave oficial de pago por uso cubre modelos de lenguaje, video, voz e imagen, pero la disponibilidad depende de los beneficios de la cuenta, de los modelos habilitados y del tipo de interfaz. La voz y el video suelen usar interfaces de tareas asíncronas y no se pueden tratar como una interfaz de chat.

¿Se puede colocar la clave en el frontend o en una miniaplicación?

No. El código del frontend, las solicitudes del navegador y los paquetes de miniaplicaciones pueden ser descompilados o interceptados. La clave debe permanecer en el servidor y las solicitudes deben pasar por un proxy del lado servidor; si necesitas conexión directa, usa tokens de corta duración o permisos restringidos y asume el riesgo de filtración.

¿La rotación exige detener el servicio?

No. Crea primero la clave nueva, valídala en preproducción, desvía el tráfico de producción de forma gradual y desactiva la antigua al final. Lo importante es que ambas coexistan durante un periodo para evitar fallos totales en el momento del cambio.

¿Se pueden mezclar una clave oficial y una del gateway?

No. Cada clave solo es válida dentro de su propia plataforma y dirección. La mezcla suele manifestarse como 401 o 404; revisa primero si la Base URL y la clave provienen de la misma plataforma.

Próximos pasos

Define primero si solo necesitas MiniMax o una entrada única para varios modelos. Si usas un solo modelo, crea la clave según la documentación oficial. Si necesitas una entrada unificada, puedes registrarte en ZSQH AI Gateway, crear una clave de prueba y revisar modelos y facturación en la página de precios de modelos. En cualquier caso, guarda la clave en variables de entorno y separa prueba de producción.

Lecturas relacionadas: