Obtener una API Key de Mistral no es un proceso largo: creas una cuenta, entras en la consola y haces clic una vez para generar la clave. Lo que suele dar problemas es la configuración posterior: a qué workspace pertenece la clave, qué conectores puede usar, dónde debe guardarse, cuándo conviene rotarla y por qué una clave copiada correctamente sigue devolviendo un error 401.

Este artículo sigue el orden real de operación: creación de la clave, permisos, variables de entorno, rotación y diagnóstico de errores 401. También explica la diferencia entre una clave oficial y una clave del gateway de IA de ZSQH.

Nota: Mistral, Mistral AI y los nombres de modelos relacionados son marcas de Mistral AI. Este artículo no tiene relación de afiliación con Mistral AI. El contenido toma como referencia la documentación pública y las prácticas habituales de octubre de 2026; las cuotas, los permisos y la forma de los productos pueden cambiar, así que consulta la consola oficial y los precios de modelos de este sitio.

1. Primero, distingue: la clave oficial y la clave del gateway no se mezclan

Una API Key de Mistral puede proceder de dos lugares distintos.

La primera opción es una clave creada en la consola oficial de Mistral, que se usa con la dirección oficial https://api.mistral.ai/v1. La segunda es una clave creada en la consola del gateway de IA de ZSQH, que se usa con la dirección del gateway https://ai.zhongshangqihang.com/v1.

El formato de ambas claves puede parecerse, pero pertenecen a plataformas diferentes. La clave oficial solo funciona con la dirección oficial; la clave del gateway solo funciona con la dirección del gateway. Mezclarlas suele devolver un error 401, así que conviene confirmar este punto antes de investigar otras causas.

2. Registro de la cuenta y entrada en la consola

El proceso oficial se completa íntegramente en el navegador:

  1. Abre https://console.mistral.ai y registra una cuenta de Mistral o inicia sesión.
  2. Sigue las indicaciones de la página para completar la verificación de correo y otros pasos necesarios hasta entrar en la consola Studio.
  3. En el primer uso, la documentación oficial indica que el acceso a la API está activado de forma predeterminada y que no hace falta vincular una tarjeta de crédito, aunque existen límites de uso y de velocidad.
  4. Localiza API Keys en la navegación lateral.
  5. Haz clic en Create new key.
  6. Completa Name y elige Expiration y Connector access scope.
  7. Haz clic de nuevo en Create new key para terminar la creación.
  8. Copia la clave completa de inmediato y guárdala en un gestor de contraseñas o en un servicio de gestión de secretos del servidor.

El punto más importante es este: la clave completa solo se muestra una vez, en la ventana que aparece al crearla. Al cerrar esa ventana, la consola ya no vuelve a mostrar el valor completo. Si no la guardaste, tendrás que crear una nueva clave y eliminar la anterior.

3. Cómo completar las tres opciones al crear la clave

Name (nombre). Sirve para distinguir el propósito de la clave y no afecta a sus permisos. Conviene incluir el entorno y la aplicación, por ejemplo mistral-dev-chat o mistral-prod-batch. Un nombre genérico como «prueba» hace que, meses después, sea difícil saber si la clave se puede eliminar.

Expiration (caducidad). Determina el periodo de validez. La plataforma permite a los administradores definir políticas de caducidad; si la política está desactivada, es posible elegir que la clave no caduque. En la práctica, es más prudente asignar a las claves de negocio una fecha de vencimiento clara, por ejemplo con rotación trimestral. No conviene poner todas las claves como permanentes solo por comodidad.

Connector access scope (alcance de conectores). Hay dos opciones:

  • Shared connectors only: la clave solo puede acceder a los conectores compartidos con el workspace actual, no a los conectores privados de quien la creó. La documentación oficial recomienda esta opción para escenarios automatizados.
  • Private and shared connectors: permite acceder tanto a los conectores privados del creador como a los compartidos. Solo debería elegirse cuando realmente se necesiten conectores privados.

Una vez creada la clave, el workspace, el alcance de conectores y la fecha de caducidad no se pueden modificar directamente. Para cambiarlos hay que crear una clave sustituta y eliminar la anterior. Por eso, dedicar unos segundos a revisar la configuración en el momento de la creación ahorra trabajo después.

4. Workspace y permisos: la clave no es un pase global

Las claves de Mistral tienen alcance de workspace. Cada clave queda vinculada al workspace seleccionado al crearla, y la cuota, los límites de velocidad y el alcance de recursos de ese workspace se aplican a la clave. Dicho de otro modo, el límite de permisos no depende solo de la clave, sino también del workspace en el que vive.

Los administradores de la organización pueden consultar, crear, rotar y eliminar claves de todos los workspaces desde admin.mistral.ai/organization/api-keys, además de definir políticas de caducidad a nivel de organización. Los desarrolladores pueden gestionar sus propias claves desde el menú de usuario de Studio o desde la página API Keys.

La regla básica de seguridad es el mínimo privilegio: si la aplicación solo necesita conectores compartidos, no elijas conectores privados; si puedes crear una clave específica para el negocio, no reutilices la clave de administrador. Una vez que una clave de administrador entra en el código de producción, es muy difícil reducir su alcance.

5. Guardar la clave en variables de entorno

No escribas la clave en el código fuente, en JavaScript del frontend, en paquetes móviles ni en repositorios públicos. Lo recomendable es colocarla en una variable de entorno del servidor o en un servicio de gestión de secretos que la inyecte en tiempo de ejecución.

# macOS / Linux: solo válido para la sesión actual de la terminal
export MISTRAL_API_KEY="tu clave"

# Ejemplo de archivo .env en la raíz del proyecto
# (recuerda añadir .env a .gitignore)
MISTRAL_API_KEY=tu_clave

Lectura en Python:

import os

api_key = os.environ["MISTRAL_API_KEY"]

En Windows PowerShell se usa $env:MISTRAL_API_KEY="tu clave". En producción es preferible recurrir al Secrets Manager del proveedor de nube, a un Secret de Kubernetes o a un servicio equivalente, en lugar de mantener un archivo .env en el servidor de forma permanente.

Al copiar la clave, evita espacios y saltos de línea. En los registros guarda solo el prefijo o una huella hash, nunca el valor completo. Las llamadas desde el frontend deben pasar por el backend; no entregues la clave al navegador.

6. Rotación y revocación: sigue el orden y no elimines primero la clave antigua

El objetivo de la rotación es que la clave nueva asuma el tráfico antes de retirar la anterior, para no interrumpir el servicio. El orden recomendado es el siguiente:

  1. Crea una clave nueva en el mismo workspace y anota en el nombre la fecha de rotación.
  2. Guarda la clave nueva en el gestor de secretos o en las variables de entorno de la plataforma de despliegue.
  3. Despliega el servicio y confirma que las instancias nuevas ya leen la clave nueva.
  4. Valida la clave con una solicitud mínima y observa durante un tiempo la tasa de errores y el consumo.
  5. Cuando confirmes que ningún tráfico usa la clave antigua, elimínala en la consola.
  6. Revisa el consumo y los registros recientes para descartar llamadas anómalas.

Si sospechas que la clave se ha filtrado, el orden se invierte: elimina o desactiva primero la clave antigua para contener el problema, y después crea y despliega la nueva. La documentación oficial considera la eliminación como el mecanismo de revocación, y la clave deja de funcionar de inmediato. En un incidente de filtración no conviene «observar un rato»: cada minuto con una credencial expuesta puede generar costos.

7. Diagnóstico de errores 401: identifica primero el tipo de fallo

Un error 401 significa que la autenticación falló, pero la causa no siempre es «la clave está mal escrita». La siguiente tabla permite revisar los casos en orden.

Síntoma Causa habitual Acción
401 Unauthorized La solicitud no incluye el encabezado Authorization Agrega Authorization: Bearer <clave>
401 Unauthorized La clave se copió incompleta, con espacios o saltos de línea Vuelve a copiarla y revisa caracteres ocultos
401 Unauthorized La clave caducó o fue eliminada Confirma su estado en la consola y crea otra si hace falta
401 Unauthorized Clave oficial con la dirección del gateway, o al contrario La clave y la Base URL deben pertenecer a la misma plataforma
401 Unauthorized La solicitud se envió a una ruta incorrecta La ruta oficial de chat es /v1/chat/completions
403 Forbidden El workspace de la clave no tiene permiso sobre el modelo o el recurso Revisa workspace, permisos de modelo y alcance de conectores

También conviene distinguir errores cercanos: el 402 suele estar relacionado con la facturación, por ejemplo saldo insuficiente, límite de gasto alcanzado o pago fallido; el 403 indica permisos insuficientes, no una clave inválida; el 429 significa que se activó un límite de velocidad y que corresponde reintentar con espera progresiva, no cambiar de clave repetidamente. Mezclar 401, 402, 403 y 429 en el mismo diagnóstico alarga problemas que podrían resolverse rápido.

8. ¿Conexión directa oficial o gateway de ZSQH?

Si solo usas Mistral, tu cuenta oficial y tu método de pago funcionan sin inconvenientes, la conexión directa es una opción clara: consola, documentación y facturación están en un mismo lugar, y los límites de responsabilidad son sencillos.

Si necesitas llamar a Mistral, Claude, GPT, Gemini y otros modelos desde un mismo proyecto, o si prefieres recargar en yuanes y tener una facturación unificada, el gateway de IA de ZSQH puede reducir el costo de administración. El gateway ofrece una entrada compatible con OpenAI; para cambiar de modelo basta ajustar el campo model, y la clave y la dirección se cambian como un par. Los modelos disponibles y la facturación figuran en los precios de modelos. Las cuentas nuevas pueden crearse desde la página de registro o directamente en https://ai.zhongshangqihang.com.

En cualquier caso, no pongas la clave oficial y la clave del gateway en la misma variable de entorno. Usa nombres separados, como MISTRAL_API_KEY y ZSQH_API_KEY, y elige la entrada de forma explícita.

9. Siete comprobaciones antes de salir a producción

  • La clave solo existe en el servidor; no aparece completa en el frontend, los registros ni el repositorio.
  • Desarrollo, preproducción y producción usan claves distintas, preferiblemente en workspaces distintos.
  • Cada clave tiene un propósito y una fecha de caducidad definidos.
  • El alcance de conectores sigue el mínimo privilegio y las claves de negocio no usan permisos de administrador.
  • La cuenta tiene alertas de consumo o límites de gasto configurados para detectar llamadas anómalas.
  • Los registros conservan solo el prefijo o la huella de la clave, nunca la credencial completa.
  • Existe un procedimiento claro de revocación y rotación para bajas de personal, pérdida de dispositivos o sospecha de filtración.

Preguntas frecuentes

¿Se puede obtener una API Key de Mistral gratis?

La documentación oficial indica que el acceso a la API está activado de forma predeterminada en el primer uso y que no requiere tarjeta de crédito, pero el modo gratuito tiene límites de uso y de velocidad. La cuota y las restricciones concretas son las que muestre la consola oficial en cada momento. Para uso prolongado o de alta concurrencia suele ser necesario activar un plan de pago.

¿Se puede volver a ver el valor completo de la clave después de crearla?

No. La clave completa solo se muestra una vez en la ventana de creación; después de cerrarla no se puede recuperar. Si no la guardaste, tendrás que crear una nueva y eliminar la anterior. Lo recomendable es guardarla de inmediato en un gestor de contraseñas o en un servicio de gestión de secretos.

¿Se puede compartir una clave entre varias aplicaciones?

Técnicamente sí, pero no es aconsejable. Si distintas aplicaciones o entornos comparten una clave, cuando surge un problema no se puede saber quién está llamando ni revocar el acceso de forma individual. Es más seguro separar las claves por aplicación y entorno, y como mínimo distinguir pruebas de producción.

¿Un error 401 siempre significa que la clave está mal?

No necesariamente. Una clave ausente, con formato incorrecto, caducada o eliminada devuelve 401; también lo hace una solicitud sin el encabezado Bearer. Una clave y una Base URL de plataformas distintas suelen producir el mismo error. Confirma primero el estado de la clave, después la dirección de entrada y por último los encabezados de la solicitud.

¿Se puede usar una clave oficial con la dirección del gateway de ZSQH?

No. La clave oficial corresponde a https://api.mistral.ai/v1 y la clave del gateway corresponde a https://ai.zhongshangqihang.com/v1. Al cambiar de entrada, la clave y la Base URL deben reemplazarse juntas; mezclarlas suele devolver un error 401.

Lecturas relacionadas: