¿Cómo Usar la API de Mistral Medium 3.5?

Mistral lanzó Medium 3.5 el 29 de abril de 2026. El ID del modelo API es mistral-medium-3.5, el endpoint es https://api.mistral.ai/v1/chat/completions, y la estructura de la solicitud es lo suficientemente parecida al estándar de OpenAI como para que el intercambio de URLs base de otro proveedor requiera una sola línea de código. Las cifras destacadas son una ventana de contexto de 256K, visión nativa, llamada a funciones, soporte para 24 idiomas y un 77.6% en SWE-Bench Verified; cifras que lo sitúan en la misma conversación que GPT-5.5 y DeepSeek V4 para el tipo de trabajo agéntico y de alto contenido de código que la mayoría de los equipos están implementando actualmente.

Esta guía cubre autenticación, cada parámetro importante, ejemplos en Python y Node, entrada de visión, llamada a herramientas, modo JSON, streaming, manejo de errores y un flujo de trabajo de Apidog que mantiene los costos visibles mientras iteras en los prompts. Para guías de modelos comparables, consulta cómo usar la API de DeepSeek V4 y cómo usar la API de GPT-5.5.

En resumen

• Endpoint: POST https://api.mistral.ai/v1/chat/completions. La autenticación es un token de portador (bearer token) en el encabezado estándar Authorization.
• ID del modelo: mistral-medium-3.5. Ventana de contexto: 256K tokens. Precios: $1.5 por millón de tokens de entrada, $7.5 por millón de tokens de salida.
• Modelo fusionado denso de 128B con razonamiento, visión, llamada nativa a funciones, salida JSON estructurada y cobertura de 24 idiomas.
• Los pesos abiertos están disponibles en Hugging Face como mistralai/Mistral-Medium-3.5-128B bajo una Licencia MIT Modificada con una excepción para grandes ingresos.
• SWE-Bench Verified: 77.6%. τ³-Telecom: 91.4. Fuerte en codificación, seguimiento de instrucciones y uso de herramientas.
• Descarga Apidog para comparar (A/B) Medium 3.5 con tu modelo actual, guarda la clave como una variable secreta y observa la diferencia de costo por llamada.

¿Qué cambió en Medium 3.5

Medium 3 se lanzó a principios de año como un modelo solo de texto con un contexto de 128K. Medium 3.5 es una bestia diferente. Es el primer modelo insignia fusionado de Mistral: el seguimiento de instrucciones, el razonamiento y la codificación residen en un único conjunto de pesos, por lo que ya no tienes que elegir entre un checkpoint de chat y uno de razonamiento. La visión es nativa, el contexto se duplica a 256K, y la llamada a funciones está integrada a nivel del modelo en lugar de ser añadida a través de una superficie API separada.

Tres cifras anclan la actualización. SWE-Bench Verified con un 77.6% se sitúa en la misma banda que los principales modelos de frontera para el parcheo de código. τ³-Telecom con 91.4 lo coloca por delante de la mayoría de los modelos generalistas en diálogos agénticos de múltiples turnos. El contexto de 256K cubre una base de código completa de tamaño mediano o una transcripción de varias horas sin truncamiento. Ninguno de estos son errores de redondeo de marketing; se relacionan directamente con si el modelo puede finalizar tu tarea sin una segunda pasada.

El cambio de precios es la parte a presupuestar. Medium 3 tenía un costo de $0.40 por millón de tokens de entrada y $2.00 por millón de salida. Medium 3.5 salta a $1.5 de entrada y $7.5 de salida, aproximadamente 4 veces más. Ese es el costo del enfoque de checkpoint fusionado más la visión más el contexto más largo. Trata el Medium 3 más antiguo como la opción de rendimiento masivo y Medium 3.5 como el nivel "necesito esta respuesta correcta".

Requisitos previos

Antes de la primera llamada, ten listos cuatro elementos.

• Una cuenta Mistral en console.mistral.ai con un método de pago registrado. Sin saldo, las llamadas devolverán 402 Payment Required.
• Una clave API con ámbito para el proyecto al que se facturará. Las claves de proyecto son más seguras que las claves de cuenta para cualquier cosa que se envíe a producción.
• Un SDK. Mistral publica un paquete oficial mistralai para Python y JavaScript, y el SDK de OpenAI funciona con el mismo endpoint con un cambio de URL base.
• Un cliente API que pueda reproducir solicitudes sin saturar tu historial de terminal. curl funciona para la primera llamada. Después de eso, usa Apidog para mantener la clave fuera de tu historial de shell y los cuerpos de solicitud bajo control de versiones.

Exporta la clave una vez:

export MISTRAL_API_KEY="..."

Endpoint y autenticación

La Plateforme de Mistral expone todo a través de una única URL base.

POST https://api.mistral.ai/v1/chat/completions

La autenticación es un token de portador (bearer token) en el encabezado Authorization. La solicitud mínima viable se ve así:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-medium-3.5",
    "messages": [
      {"role": "user", "content": "Explain dense merged checkpoints in two sentences."}
    ]
  }'

Una respuesta exitosa devuelve un cuerpo JSON con un array choices, un bloque usage desglosado en prompt_tokens, completion_tokens y total_tokens, y un id que puedes usar para el rastreo. Los fallos devuelven un envoltorio error con code y message. La estructura coincide lo suficientemente con la de OpenAI como para que cualquier analizador de errores que ya tengas funcione sin modificaciones.

Parámetros de solicitud

Cada campo se asigna a costo o comportamiento. Aquí está el mapa para mistral-medium-3.5.

Dos pequeñas diferencias confunden a la gente al migrar desde OpenAI: tool_choice="any" significa "forzar una llamada a herramienta" (OpenAI usa `required`), y el parámetro de semilla es `random_seed` (OpenAI usa `seed`). Todo lo demás coincide.

Cliente Python

Mistral distribuye un SDK oficial de Python que coincide con la API uno a uno.

import os
from mistralai import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply in code only."},
        {"role": "user", "content": "Write a Rust function that debounces events."},
    ],
    temperature=0.3,
    max_tokens=2048,
)

print("Content:", response.choices[0].message.content)
print("Total tokens:", response.usage.total_tokens)
print("Cost estimate (USD):",
      response.usage.prompt_tokens * 1.5 / 1_000_000 +
      response.usage.completion_tokens * 7.5 / 1_000_000)

Si ya tienes una base de código con formato OpenAI, el SDK de Python de OpenAI funciona con el endpoint de Mistral con dos cambios: la URL base y el ID del modelo.

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MISTRAL_API_KEY"],
    base_url="https://api.mistral.ai/v1",
)

response = client.chat.completions.create(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Hello, Mistral."}],
)

La ruta del SDK de OpenAI es el camino de menor resistencia para equipos que ejecutan código agnóstico del proveedor; el SDK nativo mistralai es el camino que expone las características específicas de Mistral de manera limpia, así que elige basándote en si planeas usar la visión y las salidas estructuradas intensivamente.

Cliente Node

La misma elección de doble vía en Node. El SDK nativo:

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.chat.complete({
  model: "mistral-medium-3.5",
  messages: [
    { role: "user", content: "Explain dense merged checkpoints in plain English." },
  ],
  temperature: 0.7,
});

console.log(response.choices[0].message.content);
console.log("Usage:", response.usage);

La ruta del SDK de OpenAI, para paridad con el código existente:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.MISTRAL_API_KEY,
  baseURL: "https://api.mistral.ai/v1",
});

const response = await client.chat.completions.create({
  model: "mistral-medium-3.5",
  messages: [{ role: "user", content: "Hello, Mistral." }],
});

Respuestas en streaming

Establece stream: true e itera los fragmentos SSE. La estructura coincide exactamente con la de OpenAI, y el rastro de razonamiento acumulativo se intercala en choices[].delta.content en lugar de estar separado en un campo auxiliar.

stream = client.chat.stream(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Stream a 300-word essay on merged checkpoints."}],
)

for chunk in stream:
    delta = chunk.data.choices[0].delta.content or ""
    print(delta, end="", flush=True)

Para la salida en terminal, el ritmo de streaming de Mistral es más rápido que el de DeepSeek V4-Pro para la misma longitud de prompt y aproximadamente igual al de GPT-5.5, basándose en ejecuciones comparativas a través del visor de respuestas de Apidog.

Llamada a herramientas

Medium 3.5 incluye llamada nativa a funciones. Las funciones definidas en el array tools se vuelven invocables, y el modelo elige cuándo invocarlas.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Return the current weather for a city.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{"role": "user", "content": "Weather in Lagos in Celsius?"}],
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

A partir de ahí, ejecuta la función localmente, añade el resultado como un mensaje role: "tool", y vuelve a llamar a la API para continuar el bucle. El patrón es idéntico al bucle de uso de herramientas de OpenAI. La capacidad agéntica se muestra en la puntuación τ³-Telecom; en la práctica, esto se traduce en menos saltos desperdiciados en flujos de trabajo de múltiples turnos donde el modelo tiene que decidir entre llamar a una herramienta, preguntar al usuario y responder directamente.

Modo JSON y salida estructurada

Para una salida validada por esquema, pasa un esquema JSON en response_format.

schema = {
    "type": "json_schema",
    "json_schema": {
        "name": "release_note",
        "schema": {
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "date": {"type": "string"},
                "bullets": {"type": "array", "items": {"type": "string"}},
            },
            "required": ["title", "date", "bullets"],
            "additionalProperties": False,
        },
        "strict": True,
    },
}

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[
        {"role": "system", "content": "Reply with a single JSON object matching the schema."},
        {"role": "user", "content": "Summarize today's Mistral Medium 3.5 release."},
    ],
    response_format=schema,
)

El modo estricto aplica el esquema en el momento de la decodificación, por lo que no necesitas añadir un paso de análisis de Pydantic o Zod en el cliente; la respuesta coincidirá con el esquema o la llamada fallará con un error estructurado. Para casos de menor fricción donde solo necesitas JSON válido de cualquier forma, establece response_format={"type": "json_object"} y valida en el lado del cliente.

Entrada de visión

El codificador de visión de Medium 3.5 fue entrenado desde cero para manejar tamaños de imagen y relaciones de aspecto variables; no necesitas pre-redimensionar nada. Pasa el contenido de la imagen junto con el texto en el array messages.

response = client.chat.complete(
    model="mistral-medium-3.5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What is in this image and what is it doing wrong?"},
            {"type": "image_url", "image_url": "https://example.com/diagram.png"},
        ],
    }],
)

Las entradas de imagen se facturan como tokens de entrada a la misma tarifa de $1.5 por millón; el recuento exacto de tokens por imagen varía con la resolución y se informa en el campo usage.prompt_tokens. Para cargas de trabajo de imagen de alto volumen, registra el costo de tokens por imagen temprano y decide si comprimir, recortar o saltar fotogramas antes de escalar.

Crea la colección en Apidog

Reproducir solicitudes desde el terminal consume créditos y oculta las diferencias entre ejecuciones. El flujo de trabajo que sobrevive al uso real:

1. Descarga Apidog y crea un proyecto.
2. Añade un entorno con {{MISTRAL_API_KEY}} almacenado como una variable secreta para que nunca termine en exportaciones compartidas.
3. Guarda una solicitud POST a {{BASE_URL}}/chat/completions con el encabezado Authorization: Bearer {{MISTRAL_API_KEY}}.
4. Parametriza model, temperature y tool_choice para que puedas hacer pruebas A/B entre variantes sin duplicar solicitudes.
5. Usa el visor de respuestas para inspeccionar usage en cada ejecución. Añade un pequeño script post-respuesta que multiplique prompt_tokens * 1.5 / 1_000_000 + completion_tokens * 7.5 / 1_000_000 para que el costo por llamada aparezca junto a cada resultado.

Los equipos que ya ejecutan la colección de la API de DeepSeek V4 correspondiente en Apidog pueden duplicarla, cambiar la URL base a https://api.mistral.ai/v1, modificar el ID del modelo a mistral-medium-3.5, y ejecutar prompts comparativos entre ambos proveedores en minutos. El mismo patrón se aplica para comparar con GPT-5.5.

Manejo de errores

El envoltorio de error sigue de cerca las convenciones de OpenAI. Los códigos que encontrarás primero:

Envuelve las llamadas en una función de reintento que maneje los errores 429 y 5xx con retroceso exponencial. No reintentes automáticamente los errores 4xx; estos son errores lógicos, no fallos transitorios. El visor de respuestas de Apidog facilita la identificación de una carga útil tools mal formada porque el campo ofensivo se resalta en el cuerpo de la solicitud junto al error.

Patrones de control de costos

El salto de precio de 4x de Medium 3 a Medium 3.5 penaliza el enrutamiento perezoso. Cinco patrones mantienen la factura predecible.

1. Por defecto, Medium 3; escala a Medium 3.5. Realiza una primera pasada económica con Medium 3 y dirige los prompts difíciles a 3.5 solo cuando la pasada económica devuelva baja confianza o falle un validador.
2. Limita max_tokens. La mayoría de las respuestas caben en 2,000 tokens de salida. La ventana de contexto de 256K es para grandes volúmenes de entrada, no de salida; la salida es la parte cara a $7.5 por millón.
3. Mantén los prompts de sistema ligeros. Cada token de prompt de sistema se factura en cada llamada; reducir un preámbulo de 2K tokens a 500 tokens recorta tu factura de entrada en un 75% en un endpoint de alto volumen.
4. Registra usage en cada llamada. Envía prompt_tokens, completion_tokens y la estimación en USD por llamada a tu pila de observabilidad. Una alerta sobre un pico repentino de tokens de salida detecta prompts que se desviaron al territorio de la cadena de pensamiento.
5. Usa la visión selectivamente. Los tokens de imagen se acumulan rápidamente. Recorta a la región relevante antes de enviar, y escala a la resolución más baja que aún responda la pregunta.

Comparando Medium 3.5 con otros niveles de Mistral

La línea de productos de Mistral a finales de abril de 2026:

Medium 3.5 es el único nivel que combina el contexto largo, la visión y las capacidades de razonamiento fusionadas. El nivel Large ofrece una curva de costos diferente (salida más barata, entrada más cara) y supera a 3.5 en algunos benchmarks solo de texto; elige por carga de trabajo, no por nombre de nivel.

Migrando desde otro proveedor

La migración es principalmente un cambio de URL base.

Desde OpenAI:

- base_url="https://api.openai.com/v1"
- model="gpt-5.5"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Desde DeepSeek:

- base_url="https://api.deepseek.com/v1"
- model="deepseek-v4-pro"
+ base_url="https://api.mistral.ai/v1"
+ model="mistral-medium-3.5"

Dos detalles a tener en cuenta:

• tool_choice="required" en OpenAI se convierte en tool_choice="any" en Mistral.
• seed se convierte en random_seed.

Ejecuta la diferencia a través de tu suite de pruebas existente antes de cambiar el tráfico de producción. Mejor aún, replica el tráfico a Mistral en modo sombra durante un día, registra ambas respuestas y compáralas en Apidog antes de promocionar.

Casos de uso en el mundo real

Algunos patrones donde Medium 3.5 ya se amortiza:

• Asistentes de revisión de código. La puntuación del 77.6% en SWE-Bench Verified y el contexto de 256K lo hacen fuerte en la revisión a nivel de PR donde el modelo necesita ver la diferencia completa más los archivos circundantes.
• QA de documentos sobre PDFs largos. El contexto de 256K cubre la mayoría de contratos, RFP y documentos de política en una sola llamada sin segmentación.
• Extracción de datos multimodal. Extraer campos estructurados de recibos, capturas de pantalla o diagramas en una sola llamada es mejor que ejecutar OCR más un modelo de texto separado.
• Bucles de agente con llamadas a herramientas. La llamada nativa a funciones y la alta puntuación τ³-Telecom reducen el número de ciclos de "llamada a herramienta fallida, reintentar con JSON corregido" que consumen tokens.

Preguntas frecuentes

¿Cuál es el ID del modelo para Mistral Medium 3.5 en la API?mistral-medium-3.5. El checkpoint de Hugging Face se publica como mistralai/Mistral-Medium-3.5-128B. Si tú mismo sirves los pesos abiertos con vLLM o Unsloth, usa el ID de Hugging Face. Para la API alojada, usa el ID corto.

¿Es Medium 3.5 compatible con OpenAI?Cercano, pero no idéntico. La forma del endpoint, los encabezados y la mayoría de los parámetros coinciden exactamente con OpenAI, por lo que los SDKs de Python y Node de OpenAI funcionan con una anulación de la URL base. Las dos divergencias son tool_choice="any" (frente a required de OpenAI) y random_seed (frente a seed de OpenAI).

¿Puedo ejecutar Medium 3.5 localmente?Sí. Los pesos son abiertos bajo una Licencia MIT Modificada con una excepción para grandes ingresos. El recuento de 128B parámetros significa que necesitas una memoria GPU significativa; las construcciones GGUF cuantificadas de unsloth/Mistral-Medium-3.5-128B-GGUF se ejecutan en una sola tarjeta de consumo de gama alta. Los patrones de cómo ejecutar DeepSeek V4 localmente se traducen directamente.

¿Soporta streaming con llamadas a herramientas?Sí. El streaming devuelve fragmentos de argumentos de llamadas a herramientas incrementalmente en delta.tool_calls, con la misma estructura que el formato de llamada a herramientas en streaming de OpenAI. Los fragmentos se acumulan en un objeto JSON completo una vez que el stream se cierra.

¿Cómo cuento los tokens de entrada antes de enviarlos?Usa el tokenizador del paquete mistral-common de Python para obtener recuentos exactos. Es el mismo tokenizador que usa la API, por lo que los recuentos byte a byte coinciden con usage.prompt_tokens en la respuesta.

¿Qué longitud de contexto debo planificar para producción?La ventana de 256K es el límite, pero el precio escala linealmente. Una llamada de 200K tokens cuesta $0.30 solo en entrada antes de que el modelo comience a generar. La mayoría de las cargas de trabajo de producción se ajustan cómodamente por debajo de 32K; recurre al contexto largo solo cuando la tarea realmente lo requiera.

¿Hay un nivel gratuito?Mistral no anuncia un nivel gratuito permanente, pero las cuentas nuevas suelen venir con un pequeño crédito de prueba. Para una experimentación gratuita sostenida en modelos de nivel similar, consulta cómo usar la API de DeepSeek V4 de forma gratuita.