DEV Community

Cover image for ¿Cómo Usar la API de Mistral Medium 3.5?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿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 suficientemente compatible con el estándar de OpenAI como para migrar cambiando la URL base y el nombre del modelo. Sus datos principales: ventana de contexto de 256K, visión nativa, llamada a funciones, soporte para 24 idiomas y 77.6% en SWE-Bench Verified. Para equipos que construyen agentes, revisores de código o flujos multimodales, Medium 3.5 entra en la misma categoría práctica que GPT-5.5 y DeepSeek V4.

Prueba Apidog hoy

Esta guía muestra cómo autenticarte, configurar parámetros, llamar a la API desde Python y Node, usar visión, herramientas, JSON estructurado, streaming, manejo de errores y un flujo de trabajo con Apidog para iterar prompts sin perder visibilidad de costos. Para modelos comparables, revisa 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.
  • Autenticación: bearer token en el encabezado Authorization.
  • Modelo: mistral-medium-3.5.
  • Contexto: 256K tokens.
  • Precios: $1.5 por millón de tokens de entrada y $7.5 por millón de tokens de salida.
  • Capacidades: razonamiento, visión, llamada nativa a funciones, salida JSON estructurada y cobertura de 24 idiomas.
  • Pesos abiertos: mistralai/Mistral-Medium-3.5-128B en Hugging Face bajo una Licencia MIT Modificada con una excepción para grandes ingresos.
  • Benchmarks destacados: 77.6% en SWE-Bench Verified y 91.4 en τ³-Telecom.
  • Puedes descargar Apidog para comparar Medium 3.5 contra tu modelo actual, guardar la clave como variable secreta y calcular el costo por llamada.

¿Qué cambió en Medium 3.5?

Medium 3 se lanzó como un modelo solo de texto con contexto de 128K. Medium 3.5 cambia el perfil: es el primer modelo insignia fusionado de Mistral. Seguimiento de instrucciones, razonamiento y codificación viven en un único conjunto de pesos, por lo que no tienes que elegir entre un checkpoint de chat y uno de razonamiento.

Mistral Medium 3.5

Los cambios que más afectan a implementación:

  • Contexto duplicado: de 128K a 256K.
  • Visión nativa.
  • Llamada a funciones integrada en el modelo.
  • Mejor rendimiento en tareas de código: 77.6% en SWE-Bench Verified.
  • Mejor rendimiento en flujos agénticos: 91.4 en τ³-Telecom.

El cambio de precio también importa. Medium 3 costaba $0.40 por millón de tokens de entrada y $2.00 por millón de salida. Medium 3.5 sube a $1.5 de entrada y $7.5 de salida. Úsalo como nivel de mayor precisión para tareas donde el razonamiento, el código, la visión o el contexto largo justifiquen el costo.

Requisitos previos

Antes de hacer la primera llamada, prepara:

  1. Una cuenta en console.mistral.ai con método de pago. Sin saldo, la API puede devolver 402 Payment Required.
  2. Una clave API asociada al proyecto que recibirá la facturación.
  3. Un SDK:
    • mistralai para Python o JavaScript.
    • SDK de OpenAI si quieres reutilizar código compatible cambiando base_url.
  4. Un cliente API. curl sirve para probar, pero para iterar prompts, guardar entornos y revisar costos por respuesta, usa Apidog.

Apidog workflow

Exporta la clave:

export MISTRAL_API_KEY="..."
Enter fullscreen mode Exit fullscreen mode

Endpoint y autenticación

El endpoint de chat completions es:

POST https://api.mistral.ai/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

La autenticación usa un bearer token:

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."
      }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

Una respuesta correcta incluye:

  • choices: respuestas generadas.
  • usage.prompt_tokens: tokens de entrada.
  • usage.completion_tokens: tokens de salida.
  • usage.total_tokens: total facturable.
  • id: identificador útil para trazabilidad.

Los errores vienen en un objeto error con code y message.

Parámetros principales

Parámetro Tipo Valores Uso
model string mistral-medium-3.5 Requerido.
messages array roles y contenido Requerido. Compatible con el esquema estilo OpenAI.
temperature float 0 a 1.5 Usa 0.3 para código y 0.7 para uso general.
top_p float 0 a 1 Muestreo nucleus. Por defecto 1.0.
max_tokens int hasta el límite de contexto Limita la salida. Clave para controlar costos.
stream bool true / false Activa streaming SSE.
tools array especificación de funciones Define herramientas invocables.
tool_choice string u objeto auto, any, none o herramienta específica En Mistral, any fuerza una llamada a herramienta.
response_format object JSON object o JSON schema Controla salida estructurada.
random_seed int entero Reproducibilidad.
safe_prompt bool true / false Añade el preámbulo de seguridad de Mistral.
presence_penalty float -2 a 2 Penaliza repetición de temas.
frequency_penalty float -2 a 2 Penaliza repetición de tokens.

Dos diferencias al migrar desde OpenAI:

OpenAI:  tool_choice="required"
Mistral: tool_choice="any"
Enter fullscreen mode Exit fullscreen mode 
OpenAI:  seed
Mistral: random_seed
Enter fullscreen mode Exit fullscreen mode

Cliente Python

Instala el SDK oficial:

pip install mistralai
Enter fullscreen mode Exit fullscreen mode

Ejemplo básico:

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(response.choices[0].message.content)

prompt_cost = response.usage.prompt_tokens * 1.5 / 1_000_000
completion_cost = response.usage.completion_tokens * 7.5 / 1_000_000

print("Total tokens:", response.usage.total_tokens)
print("Estimated cost USD:", prompt_cost + completion_cost)
Enter fullscreen mode Exit fullscreen mode

Si ya usas el SDK de OpenAI, cambia la URL base:

import os
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."}
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Usa el SDK nativo si quieres aprovechar características específicas de Mistral de forma más directa. Usa el SDK de OpenAI si tu código ya es agnóstico del proveedor.

Cliente Node.js

Instala el SDK nativo:

npm install @mistralai/mistralai
Enter fullscreen mode Exit fullscreen mode

Ejemplo:

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);
Enter fullscreen mode Exit fullscreen mode

Con el SDK de OpenAI:

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." },
  ],
});

console.log(response.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

Streaming

Activa stream: true para recibir fragmentos SSE.

import os
from mistralai import Mistral

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

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)
Enter fullscreen mode Exit fullscreen mode

El contenido llega en choices[].delta.content, con una forma compatible con el patrón de streaming de OpenAI.

Para comparar latencia, tokens y costo por ejecución, puedes usar el visor de respuestas de Apidog.

Llamada a herramientas

Medium 3.5 soporta llamada nativa a funciones mediante tools.

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)
print(tool_call.function.arguments)
Enter fullscreen mode Exit fullscreen mode

Flujo recomendado:

  1. Envía el prompt con tools.
  2. Lee message.tool_calls.
  3. Ejecuta la función en tu backend.
  4. Añade el resultado como mensaje role: "tool".
  5. Llama de nuevo a la API para que el modelo continúe con contexto del resultado.

El patrón es equivalente al bucle de herramientas de OpenAI, con la diferencia de tool_choice="any" si quieres forzar una llamada.

Modo JSON y salida estructurada

Para respuestas validadas por esquema, pasa 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,
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Para casos más simples, usa:

response_format = {"type": "json_object"}
Enter fullscreen mode Exit fullscreen mode

Luego valida con Pydantic, Zod o tu validador preferido en el cliente.

Entrada de visión

Medium 3.5 acepta imágenes junto con texto dentro de 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",
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

Las imágenes se facturan como tokens de entrada a $1.5 por millón. El conteo exacto depende de la resolución y aparece en usage.prompt_tokens.

Para cargas multimodales de alto volumen:

  • Recorta la región relevante antes de enviar.
  • Reduce resolución cuando sea posible.
  • Registra prompt_tokens por imagen.
  • Evita enviar frames redundantes en video o capturas secuenciales.

Crea una colección en Apidog

Para evitar prompts dispersos en terminal y tener costos visibles, crea una colección reutilizable:

  1. Descarga Apidog y crea un proyecto.
  2. Crea un entorno con:
    • BASE_URL=https://api.mistral.ai/v1
    • MISTRAL_API_KEY=...
  3. Guarda MISTRAL_API_KEY como variable secreta.
  4. Crea una solicitud: 
   POST {{BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode
  1. Añade encabezados: 
   Authorization: Bearer {{MISTRAL_API_KEY}}
   Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode
  1. Usa un body parametrizable: 
{
  "model": "mistral-medium-3.5",
  "temperature": 0.3,
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "Review this function and suggest improvements."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode
  1. Revisa usage en cada respuesta.
  2. Añade un cálculo de costo: 
const usage = response.json().usage;

const cost =
  usage.prompt_tokens * 1.5 / 1_000_000 +
  usage.completion_tokens * 7.5 / 1_000_000;

console.log(`Estimated cost USD: ${cost}`);
Enter fullscreen mode Exit fullscreen mode

Si ya tienes una colección para DeepSeek V4, duplícala y cambia:

- https://api.deepseek.com/v1
- deepseek-v4-pro
+ https://api.mistral.ai/v1
+ mistral-medium-3.5
Enter fullscreen mode Exit fullscreen mode

El mismo patrón sirve para comparar con GPT-5.5.

Manejo de errores

Errores frecuentes:

Código Significado Acción
400 Solicitud incorrecta Valida messages, tools y el JSON enviado.
401 Clave inválida Regenera la clave en console.mistral.ai.
402 Pago requerido Añade saldo o método de pago.
403 Modelo no permitido Revisa permisos del proyecto y el ID del modelo.
422 Parámetro fuera de rango Revisa max_tokens, tool_choice o esquema JSON.
429 Rate limit Reintenta con retroceso exponencial.
500 Error del servidor Reintenta una vez y registra el fallo.
503 Sobrecarga Espera o usa otro nivel temporalmente.

Implementa reintentos solo para 429 y 5xx:

import time
from mistralai import Mistral

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

def complete_with_retry(payload, retries=3):
    for attempt in range(retries):
        try:
            return client.chat.complete(**payload)
        except Exception as exc:
            status = getattr(exc, "status_code", None)

            if status not in [429, 500, 502, 503, 504]:
                raise

            if attempt == retries - 1:
                raise

            sleep_seconds = 2 ** attempt
            time.sleep(sleep_seconds)
Enter fullscreen mode Exit fullscreen mode

No reintentes automáticamente errores 4xx que no sean 429: normalmente indican un problema de payload, permisos o facturación.

Control de costos

Medium 3.5 es más caro que Medium 3, así que evita enviarlo todo al modelo más potente por defecto.

Patrones prácticos:

  1. Usa Medium 3 por defecto y escala a Medium 3.5 cuando haga falta.

    Por ejemplo, usa Medium 3 para clasificación o borradores y Medium 3.5 cuando falle un validador o se requiera razonamiento más fuerte.

  2. Limita max_tokens.

    La salida cuesta $7.5 por millón. Si esperas respuestas cortas, no dejes el máximo abierto.

  3. Reduce prompts de sistema largos.

    Un preámbulo de 2K tokens se factura en cada llamada. Si puedes bajarlo a 500 tokens, reduces ese costo de entrada en 75%.

  4. Registra usage siempre.

    Envía prompt_tokens, completion_tokens, total_tokens y costo estimado a tu observabilidad.

  5. Usa visión selectivamente.

    Recorta o comprime imágenes antes de enviarlas. No mandes pantallas completas si solo necesitas una tabla o un diagrama.

Ejemplo de cálculo:

def estimate_cost_usd(prompt_tokens, completion_tokens):
    return (
        prompt_tokens * 1.5 / 1_000_000 +
        completion_tokens * 7.5 / 1_000_000
    )
Enter fullscreen mode Exit fullscreen mode

Comparación con otros modelos de Mistral

Modelo Contexto Entrada $/M Salida $/M Visión Mejor para
mistral-small 32K $0.10 $0.30 No Clasificación de alto volumen, chat ligero
mistral-medium-3 128K $0.40 $2.00 No Rendimiento masivo, chat largo
mistral-medium-3.5 256K $1.5 $7.5 Sí Razonamiento, código, visión, agentes
mistral-large 128K $2.00 $6.00 Limitada Razonamiento de texto de nivel frontera

Medium 3.5 es el nivel que combina contexto largo, visión y razonamiento fusionado. No lo elijas solo por nombre: úsalo cuando esas capacidades sean necesarias para la tarea.

Migración desde otro proveedor

La migración suele ser un cambio de URL base y modelo.

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Ajustes a revisar:

- tool_choice="required"
+ tool_choice="any"
Enter fullscreen mode Exit fullscreen mode 
- seed=123
+ random_seed=123
Enter fullscreen mode Exit fullscreen mode

Antes de mover tráfico de producción:

  1. Ejecuta tu suite de pruebas actual.
  2. Compara respuestas para prompts críticos.
  3. Registra usage y costo por llamada.
  4. Si es posible, ejecuta modo sombra durante un día y compara resultados en Apidog.

Casos de uso prácticos

Medium 3.5 encaja especialmente bien en:

  • Revisión de código a nivel PR.

    El contexto de 256K permite incluir diffs grandes y archivos relacionados.

  • QA sobre documentos largos.

    Contratos, RFPs y políticas pueden procesarse en una sola llamada cuando caben en la ventana.

  • Extracción multimodal.

    Puedes extraer campos estructurados desde recibos, capturas o diagramas sin encadenar OCR y otro modelo de texto.

  • Agentes con herramientas.

    La llamada nativa a funciones reduce fricción en flujos donde el modelo debe decidir entre responder, pedir información o invocar una herramienta.

Preguntas frecuentes

¿Cuál es el ID del modelo?

Para la API alojada:

mistral-medium-3.5
Enter fullscreen mode Exit fullscreen mode

En Hugging Face:

mistralai/Mistral-Medium-3.5-128B
Enter fullscreen mode Exit fullscreen mode

Si sirves los pesos abiertos con vLLM o Unsloth, usa el ID del checkpoint de Hugging Face.

¿Medium 3.5 es compatible con OpenAI?

Es compatible en la forma general del endpoint, encabezados y muchos parámetros. Los SDKs de OpenAI para Python y Node funcionan cambiando base_url.

Diferencias clave:

  • tool_choice="any" en lugar de tool_choice="required".
  • random_seed en lugar de seed.

¿Puedo ejecutar Medium 3.5 localmente?

Sí. Los pesos están abiertos bajo una Licencia MIT Modificada con una excepción para grandes ingresos. El modelo tiene 128B parámetros, por lo que requiere memoria GPU significativa. Las builds GGUF cuantificadas de unsloth/Mistral-Medium-3.5-128B-GGUF pueden ejecutarse en una tarjeta de consumo de gama alta.

Los patrones de cómo ejecutar DeepSeek V4 localmente se aplican de forma similar.

¿Soporta streaming con herramientas?

Sí. El streaming puede devolver fragmentos incrementales de llamadas a herramientas en delta.tool_calls. Debes acumular esos fragmentos hasta formar el JSON completo antes de ejecutar la función.

¿Cómo cuento tokens antes de enviar?

Usa el tokenizador del paquete Python mistral-common. Es el mismo tokenizador que usa la API, por lo que los conteos deberían alinearse con usage.prompt_tokens.

¿Qué longitud de contexto debería usar en producción?

256K es el límite, no el objetivo. Una llamada de 200K tokens cuesta $0.30 solo en entrada antes de generar salida. Para producción, intenta mantener la mayoría de las llamadas por debajo de 32K y usa contexto largo solo cuando la tarea lo requiera.

¿Hay un nivel gratuito?

Mistral no anuncia un nivel gratuito permanente, aunque las cuentas nuevas pueden incluir crédito de prueba. Para experimentar con modelos comparables sin costo sostenido, revisa cómo usar la API de DeepSeek V4 de forma gratuita.

Top comments (0)