La integración con la API de Mistral tiene una ruta corta: una Base URL, una clave y un nombre de modelo bastan para completar la primera llamada. Lo que suele bloquear a los equipos no es el código, sino tres detalles: si la dirección está completa, si el nombre del modelo corresponde a la versión actual y si la clave y el punto de entrada forman la pareja correcta.

Este artículo parte de la entrada oficial https://api.mistral.ai/v1, completa la primera llamada con curl y con Python y después repasa el streaming, el modo JSON, el uso de herramientas, los errores habituales y la lista de comprobación para migrar de la conexión directa al 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. Los modelos, parámetros y cuotas pueden cambiar según la versión; consulta la documentación oficial y los precios de modelos de este sitio.

1. Tres cosas que confirmar antes de integrar

La primera es el origen de la clave. Las claves oficiales se crean en https://console.mistral.ai y solo funcionan con la entrada oficial; las claves del gateway se crean en la consola de ZSQH y solo funcionan con la entrada del gateway.

La segunda es la Base URL. La entrada oficial es https://api.mistral.ai/v1, y la ruta completa de chat completions es https://api.mistral.ai/v1/chat/completions.

La tercera es el nombre del modelo. Mistral ofrece tanto alias -latest como nombres de versión fija con fecha, y no significan lo mismo. Los alias cambian cuando el proveedor actualiza la versión predeterminada, mientras que las versiones fijas son más adecuadas para producción y para comparar regresiones.

Cuando estos tres puntos están confirmados, se escribe el código. Si se hace al revés, es fácil quedar atrapado entre errores 401 y 404.

2. Base URL y ruta de la solicitud

La dirección base de la API oficial es:

https://api.mistral.ai/v1

Chat completions usa POST /v1/chat/completions. La solicitud necesita dos encabezados:

Authorization: Bearer <MISTRAL_API_KEY>
Content-Type: application/json

Si usas el SDK oficial de Python, normalmente basta con pasar api_key, porque el SDK construye la dirección automáticamente. Si usas el SDK de OpenAI, configura base_url como https://api.mistral.ai/v1; el SDK añadirá /chat/completions al final.

El error más habitual aquí es duplicar la ruta: base_url ya incluye /v1 y la ruta de la solicitud vuelve a escribir /v1/chat/completions, de modo que termina en /v1/v1/chat/completions y devuelve 404. Otro error frecuente es mezclar la dirección oficial con la del gateway, lo que se manifiesta como un 401.

La entrada compatible con OpenAI del gateway de IA de ZSQH es https://ai.zhongshangqihang.com/v1, con las mismas reglas de ruta. Al cambiar de entrada, modifica solo base_url y api_key, sin cruzarlos entre plataformas.

3. Nombres de modelo: alias o versión fija

Hasta octubre de 2026, la guía de inicio rápido oficial usa mistral-large-latest, y la documentación de llamadas a funciones también menciona alias como mistral-medium-latest y mistral-small-latest. La página general de modelos incluye nombres de versión fija como mistral-large-4 (vista previa pública), mistral-large-2512, mistral-medium-3-5, mistral-small-2603, además de modelos especializados como ministral-14b-2512 y codestral-2508.

La diferencia entre ambos tipos de nombre es la siguiente:

  • Los alias -latest apuntan a la versión predeterminada actual del proveedor. Sirven para validaciones rápidas y proyectos no críticos, pero su comportamiento puede cambiar cuando cambia la versión predeterminada.
  • Los nombres fijos con fecha o generación apuntan a una versión concreta. Son adecuados para producción porque permiten bloquear el comportamiento, comparar despliegues y revertir con facilidad.

Las distintas páginas oficiales no se actualizan al mismo ritmo, así que la versión exacta a la que apunta un alias debe confirmarse en la consola o en la lista de modelos devuelta por la API en el momento de la llamada. Antes de integrar, puedes usar client.models.list() del SDK o la consola para comprobar qué modelos están disponibles; no copies nombres de artículos antiguos.

Si usas el gateway de IA de ZSQH, los nombres de modelo se rigen por la página de precios de modelos de este sitio. El gateway puede aplicar un mapeo sobre los nombres del proveedor, de modo que trasladar directamente el nombre oficial no siempre funciona.

4. Primer curl: validar la solicitud mínima

Primero configura la variable de entorno y después envía la solicitud más corta posible. Usa un max_tokens pequeño para reducir la espera y las distracciones.

export MISTRAL_API_KEY="tu clave"

curl https://api.mistral.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
    "model": "mistral-large-latest",
    "messages": [
      {"role": "user", "content": "Responde solo OK"}
    ],
    "max_tokens": 32
  }'

Si la respuesta es 200 y choices[0].message.content contiene texto, la clave, la Base URL y el nombre del modelo son correctos. Si devuelve 401, revisa primero la clave y los encabezados; si devuelve 404, revisa la ruta y el nombre del modelo; si devuelve 402, revisa el estado de la facturación.

5. Llamadas con Python: SDK de Mistral y SDK de OpenAI

El paquete oficial de Python se llama mistralai:

pip install mistralai

Ejemplo mínimo:

import os
from mistralai.client import Mistral

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    response = client.chat.complete(
        model="mistral-large-latest",
        messages=[
            {"role": "system", "content": "Eres un asistente técnico. Responde de forma concisa."},
            {"role": "user", "content": "Explica en tres frases qué es una base de datos vectorial."},
        ],
        max_tokens=256,
    )

print(response.choices[0].message.content)
print(response.usage)

Presta atención a la ruta de importación: la documentación actual del SDK usa from mistralai.client import Mistral, mientras que algunas versiones antiguas escribían from mistralai import Mistral. No mezcles ambos estilos; si aparece ModuleNotFoundError, revisa la versión instalada y las notas de migración oficiales.

Si quieres reutilizar código existente del SDK de OpenAI, apunta base_url a https://api.mistral.ai/v1 y cambia api_key por la clave de Mistral. La forma de la solicitud es muy parecida a OpenAI Chat Completions y la práctica está extendida en la comunidad; sin embargo, la documentación oficial no presenta la API de Mistral como un producto «compatible con OpenAI», y el soporte de parámetros, la estructura de errores y los campos extendidos se rigen por la referencia oficial de la API. Antes de salir a producción, valida con solicitudes reales y no des por hecho que todos los parámetros de OpenAI funcionan.

6. Salida en streaming

Las interfaces de chat suelen necesitar respuestas palabra por palabra. El SDK de Mistral usa client.chat.stream(...), que devuelve un flujo de eventos; el incremento de texto está en chunk.data.choices[0].delta.content:

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    stream = client.chat.stream(
        model="mistral-large-latest",
        messages=[{"role": "user", "content": "Escribe un ejemplo de Python que lea un CSV"}],
    )
    for chunk in stream:
        delta = chunk.data.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)

La respuesta en streaming usa SSE con solo datos y termina con data: [DONE]. En ingeniería hay que resolver tres cosas: los incrementos vacíos, la desconexión del cliente y los reintentos por tiempo de espera. No escribas en la base de datos con cada incremento; concatena el texto completo y guárdalo al final.

7. Modo JSON, salida estructurada y uso de herramientas

El modo JSON se activa con response_format={"type": "json_object"}. La documentación oficial indica que los modelos actuales, salvo codestral-mamba, lo admiten. Con el modo activado, la salida se restringe a JSON válido, pero el campo content sigue siendo una cadena JSON y hay que analizarla con json.loads(). En el prompt conviene indicar explícitamente «devuelve un objeto JSON» y los campos esperados; no dependas solo del parámetro.

La salida estructurada es útil cuando los campos son fijos. El SDK oficial ofrece client.chat.parse(...), que acepta un modelo de Pydantic y devuelve el objeto ya analizado. Si usas JSON Schema sin procesar, configura strict: true y additionalProperties: false en el objeto. Cuanto más estrictos sean los campos, menor será el margen de improvisación del modelo y más sencilla la validación posterior.

El uso de herramientas se configura con el arreglo tools; tool_choice admite auto, any y none, y parallel_tool_calls controla si se permiten llamadas en paralelo. El modelo solo devuelve el nombre de la herramienta y sus argumentos; la ejecución real corresponde a tu backend. Cuando recibas tool_calls, agrega el mensaje del asistente tal cual a la lista de mensajes, añade un mensaje tool con el tool_call_id correspondiente y vuelve a llamar al modelo hasta que entregue la respuesta final. Las llamadas encadenadas deben procesarse en un bucle; no basta con una sola ronda.

8. Errores habituales y diagnóstico

Error Causa habitual Acción
400 El cuerpo no es JSON válido o faltan model o messages Valida primero la solicitud mínima con curl
401 Clave ausente, incorrecta, caducada o incompatible con la entrada Revisa el encabezado Bearer y el origen de la clave
402 Problema de facturación: saldo, límite de gasto o pago fallido Revisa la facturación y la cuota en la consola
403 La cuenta o el workspace no tiene permiso sobre el modelo Revisa workspace, permisos de modelo y plan
404 Ruta incorrecta o modelo o recurso inexistente Confirma /v1/chat/completions y el nombre del modelo
422 JSON válido pero valores de parámetros inválidos Revisa tipos, valores de enumeración y longitud de arreglos
429 Se superó el límite de velocidad, tokens o concurrencia Aplica espera exponencial y lee Retry-After
500/503 Anomalía del servidor o sobrecarga temporal Espera un breve periodo y reintenta; si persiste, consulta la página de estado

No intentes sortear un 429 creando más claves. La cuota oficial se contabiliza por cuenta, workspace o plan, y varias claves suelen compartir el mismo límite. Lo correcto es reducir la concurrencia, aplicar espera exponencial, escalonar los trabajos por lotes y, si hace falta, considerar un plan superior.

9. Lista de comprobación para migrar de la conexión oficial al gateway

  1. Crea una cuenta en el gateway de IA de ZSQH, genera una clave del gateway y guárdala por separado de la clave oficial.
  2. Cambia base_url por https://ai.zhongshangqihang.com/v1 y reemplaza también api_key.
  3. Confirma de nuevo los nombres de modelo en los precios de modelos; no reutilices directamente los nombres oficiales.
  4. Conserva el cuerpo original de la solicitud, elimina primero los parámetros extendidos que el gateway no admita y vuelve a añadirlos uno por uno.
  5. Compara salidas, latencia y usage con el mismo lote de prompts reales durante tres a siete días.
  6. Mantén la conexión directa oficial como canal de respaldo y prepara un interruptor de reversión.
  7. Supervisa errores 401, 429, 5xx y tiempos de espera; ante una anomalía, cambia de canal antes de investigar.

La migración no termina con «cambiar una dirección». El mapeo de modelos, el soporte de parámetros, el comportamiento del streaming y la forma de facturar pueden diferir; valida primero con poco tráfico y después pasa a producción.

Preguntas frecuentes

¿La Base URL debe incluir /v1?

La entrada oficial sí incluye /v1, es decir, https://api.mistral.ai/v1. La ruta completa de chat completions es https://api.mistral.ai/v1/chat/completions. Con el SDK de OpenAI, basta con escribir base_url hasta /v1, porque el SDK añade /chat/completions por su cuenta; no lo escribas otra vez a mano.

¿Conviene usar un alias -latest o una versión fija?

Para validaciones rápidas, un alias como mistral-large-latest evita tener que buscar el número de versión. En producción es preferible un nombre fijo con fecha o generación: el comportamiento es reproducible y revertir es más sencillo. En cualquier caso, confirma la disponibilidad actual en la documentación oficial o en la consola antes de desplegar.

¿Se puede usar la API de Mistral con el SDK de OpenAI?

La forma de la solicitud es parecida y suele funcionar apuntando base_url a https://api.mistral.ai/v1 y usando una clave de Mistral. Sin embargo, el proveedor no la promociona como un producto compatible con OpenAI, y algunos parámetros y estructuras de error pueden diferir. Valida primero con una solicitud mínima y después revisa uno por uno los parámetros extendidos que use tu proyecto.

¿Por qué el modo JSON no devuelve un objeto?

El modo JSON garantiza que la salida sea JSON válido, pero content llega como cadena y hay que analizarla. Ejecuta primero json.loads() y después valida contra el esquema. Si el prompt indica con claridad que se espera un objeto JSON y describe la estructura de campos, se reducen los campos vacíos y la deriva de formato.

¿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 migrar, la clave y la Base URL deben cambiarse como un par; mezclarlas suele devolver un error 401.

Lecturas relacionadas: