¿Cómo usar la API de Mistral Large 4?

Mistral Large 4 se lanzó en la API de Mistral el 6 de octubre de 2026, tres semanas antes de sus pesos abiertos. Si quieres probar “Le Chonk”, con 1 billón de parámetros, la API es la única forma de acceder por ahora y también la más barata: Mistral lo lista a $0.68 por millón de tokens de entrada y $2.09 por millón de tokens de salida durante la vista previa pública, la mitad del precio de lista de $1.36 / $4.18.

Prueba Apidog hoy

Esta guía te lleva de cero a una primera llamada funcional en unos cinco minutos. Después cubre los puntos que suelen causar problemas: fragmentos de razonamiento, entrada de imágenes, llamadas a funciones, salida JSON y costes. Puedes guardar y reproducir cada solicitud en Apidog para comparar Large 4 con los modelos que ya utilizas.

¿Nuevo en el modelo? Lee primero Mistral Ha Vuelto: Le Chonk Supera a GPT-6 Astra y Claude en Ciberseguridad para revisar los benchmarks y el contexto del titular sobre ciberseguridad.

Lo que necesitas

Elemento	Valor
URL base	https://api.mistral.ai/v1
Autenticación	Authorization: Bearer $MISTRAL_API_KEY
ID del modelo	mistral-large-4 (alias mistral-large-4-0)
Endpoint principal	POST /v1/chat/completions
Ventana de contexto	1M tokens
Tipos de entrada	Texto, imágenes
SDK de Python	pip install mistralai
SDK de TypeScript	npm install @mistralai/mistralai

Paso 1: Obtén una clave API

1. Inicia sesión en Mistral Studio —anteriormente La Plateforme—.
2. Abre Claves API y crea una clave nueva. Usa un nombre que indique dónde se utilizará, como local-dev o ci-staging.
3. Copia la clave. Studio no volverá a mostrarla.
4. Expórtala en tu shell:

export MISTRAL_API_KEY="your-key-here"

No incluyas la clave en el control de código fuente. Si la conectas a varias herramientas, consulta estas mejores prácticas de gestión de claves API para rotación y alcance.

Paso 2: Realiza tu primera llamada

La comprobación más rápida es una llamada con curl:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": "Give me three edge cases to test on a pagination API."
      }
    ]
  }'

Una respuesta correcta incluye:

• choices[0].message.content: la respuesta del modelo.
• usage.prompt_tokens: tokens de entrada.
• usage.completion_tokens: tokens de salida.
• usage.total_tokens: total de tokens.

Si recibes un 401, la clave es incorrecta o no se ha exportado. Un 404 para el modelo normalmente indica un error tipográfico en el ID.

La misma llamada en Python

import os
from mistralai import Mistral

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

response = client.chat.complete(
    model="mistral-large-4",
    messages=[
        {
            "role": "user",
            "content": "Give me three edge cases to test on a pagination API."
        }
    ],
)

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

La misma llamada en TypeScript

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

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

const response = await client.chat.complete({
  model: "mistral-large-4",
  messages: [
    {
      role: "user",
      content: "Give me three edge cases to test on a pagination API.",
    },
  ],
});

console.log(response.choices[0].message.content);

Paso 3: Guarda la solicitud en Apidog

Escribir comandos curl deja de escalar cuando empiezas a comparar modelos. Para guardar esta prueba en Apidog:

1. Crea una solicitud HTTP: POST https://api.mistral.ai/v1/chat/completions.
2. Añade una variable de entorno llamada MISTRAL_API_KEY.
3. Configura este encabezado:

   Authorization: Bearer {{MISTRAL_API_KEY}}

1. Pega el cuerpo JSON del Paso 2 y pulsa Enviar.
2. Duplica la solicitud, cambia model por el modelo que utilizas hoy —por ejemplo, mistral-medium-3-5— y ejecuta ambas.

Así tendrás dos solicitudes guardadas con el mismo prompt. Apidog muestra el cuerpo, estado, tiempo y tamaño de cada respuesta, lo que permite comparar calidad, latencia y los contadores de usage sin crear un script.

Añade también una aserción posterior a la respuesta que verifique que choices[0].message.content no está vacío. Tendrás una prueba de humo reutilizable cuando Mistral actualice la vista previa.

Paso 4: Activa o desactiva el razonamiento

Large 4 es un modelo híbrido: puede responder rápidamente o usar razonamiento paso a paso. Controla ese comportamiento con reasoning_effort.

Valor	Comportamiento	Úsalo para
"none"	Pensamiento mínimo, sin fragmento de razonamiento en la respuesta	Chat, extracción, clasificación y flujos sensibles a la latencia
"high"	Fragmento de razonamiento completo antes de la respuesta final	Depuración, planificación de varios pasos, matemáticas y revisión de código

Ejemplo con razonamiento alto:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": "Our API returns 200 with an empty body under load. List likely causes in order of probability."
      }
    ],
    "reasoning_effort": "high"
  }'

Atención: con reasoning_effort: "high", message.content deja de ser una cadena. Se convierte en una lista de fragmentos.

La lista incluye:

• Un fragmento thinking con el rastro de razonamiento.
• Un fragmento text con la respuesta final.

No imprimas response.choices[0].message.content directamente si tu aplicación espera texto. Extrae el fragmento text:

response = client.chat.complete(
    model="mistral-large-4",
    messages=[
        {
            "role": "user",
            "content": "Why would a 200 response have an empty body?"
        }
    ],
    reasoning_effort="high",
)

content = response.choices[0].message.content

if isinstance(content, str):
    answer = content
else:
    answer = "".join(c.text for c in content if c.type == "text")

print(answer)

Los tokens de pensamiento se facturan como tokens de salida. Usa "none" como valor predeterminado y cambia a "high" solo en las solicitudes que realmente necesiten razonamiento.

Paso 5: Envía una imagen

Large 4 es multimodal de forma nativa e incluye un codificador de visión de 1.6B parámetros. Envía imágenes como partes del contenido junto con el texto:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "This is a screenshot of our API error dashboard. Which endpoint is failing most and what is the error code?"
          },
          {
            "type": "image_url",
            "image_url": "https://example.com/dashboard.png"
          }
        ]
      }
    ]
  }'

Para archivos locales, utiliza una URL de datos base64:

{
  "type": "image_url",
  "image_url": "data:image/png;base64,<encoded>"
}

Mistral informa que Large 4 obtiene un 42% en el benchmark Dense 200 de anclaje visual, frente al 41% de GPT-6 Astra. Por eso, las capturas de dashboards, gráficos y estados de interfaz son casos de uso razonables.

Paso 6: Usa llamadas a funciones

Las llamadas a funciones permiten que el modelo seleccione una herramienta y que tu aplicación ejecute la operación real. Large 4 obtuvo un 59.9% en AutomationBench, por lo que este flujo es especialmente relevante para agentes.

Primero, define las herramientas disponibles:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": "Look up the status of an order by its ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "The order ID, e.g. ORD-1042"
                    }
                },
                "required": ["order_id"],
            },
        },
    }
]

messages = [
    {
        "role": "user",
        "content": "Where is order ORD-1042?"
    }
]

response = client.chat.complete(
    model="mistral-large-4",
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

tool_call = response.choices[0].message.tool_calls[0]

print(tool_call.function.name, tool_call.function.arguments)

Después, ejecuta la función en tu backend y devuelve el resultado usando el tool_call_id correspondiente:

import json

result = {
    "order_id": "ORD-1042",
    "status": "shipped",
    "eta": "2026-10-09",
}

messages.append(response.choices[0].message)
messages.append({
    "role": "tool",
    "name": "get_order_status",
    "content": json.dumps(result),
    "tool_call_id": tool_call.id,
})

final = client.chat.complete(
    model="mistral-large-4",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)

El esquema de cada herramienta es JSON Schema. Si tu API ya tiene una especificación OpenAPI, puedes trasladar el esquema de solicitud de cada operación a parameters. Diseñar primero la especificación en Apidog ayuda a mantener sincronizadas la API real y las definiciones de herramientas.

Paso 7: Obtén JSON de vuelta

Cuando necesites una respuesta legible por máquina, configura response_format:

curl https://api.mistral.ai/v1/chat/completions \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-large-4",
    "messages": [
      {
        "role": "user",
        "content": "Extract method, path and status code from: GET /v1/users/42 returned 404. Reply in JSON."
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

Menciona JSON tanto en el prompt como en response_format.

Para esquemas estrictos, Mistral también admite:

{
  "type": "json_schema",
  "json_schema": {
    "...": "esquema completo"
  }
}

En Apidog, añade una aserción de JSON Schema a la respuesta. Así, un cambio en la forma de salida fallará explícitamente en lugar de romper un servicio posterior.

Cuánto cuesta

Uso	Precio de vista previa	Precio de lista
Entrada, por 1M de tokens	$0.68	$1.36
Entrada en caché, por 1M de tokens	$0.07	$0.14
Salida, por 1M de tokens	$2.09	$4.18

Ejemplo: un agente realiza 10.000 llamadas al día, cada una con 3.000 tokens de entrada —principalmente prompt de sistema y herramientas en caché— y 500 tokens de salida.

• Entrada: 30M de tokens. Si 2.500 de cada 3.000 están en caché, son 25M en caché a $0.07 y 5M nuevos a $0.68: aproximadamente $5.15/día.
• Salida: 5M de tokens a $2.09: aproximadamente $10.45/día.
• Total: aproximadamente $15.60/día con el precio de vista previa, o alrededor de $31 con precio de lista.

La misma carga de trabajo en GPT-6 Astra, a $10 / $50 por millón antes de descuentos por caché, costaría varios cientos de dólares al día. Mistral no ha indicado cuándo terminará el precio de vista previa, así que presupuesta según el precio de lista.

Errores comunes

Error	Causa probable	Solución
401 No autorizado	Clave faltante o incorrecta	Verifica echo $MISTRAL_API_KEY y el prefijo Bearer
404 / modelo inválido	Error tipográfico en el ID del modelo	Usa mistral-large-4 exactamente
422 Entidad no procesable	Cuerpo malformado, normalmente un esquema tools incorrecto	Valida el JSON Schema de parameters en cada herramienta
429 Demasiadas solicitudes	Límite de tarifa de tu nivel de espacio de trabajo	Aplica retroceso y reintentos, o aumenta los límites en Studio
La respuesta se imprime como lista	reasoning_effort: "high" devuelve fragmentos	Extrae el fragmento text como se muestra en el Paso 4

Preguntas frecuentes

¿Mistral Large 4 es compatible con OpenAI?

La forma de la solicitud es muy similar: model, messages, tools, tool_choice y response_format funcionan como esperarías. Para mayor seguridad, utiliza los SDK de Mistral o HTTP puro. La salida de razonamiento usa el formato de fragmentos propio de Mistral.

¿Cuándo puedo ejecutarlo localmente?

Mistral dice que los pesos se enviarán a finales de octubre de 2026. Con 1.05T de parámetros totales, necesita hardware de servidor multi-GPU. Esta guía para ejecutar Mistral 3 localmente cubre las herramientas para modelos más pequeños mientras tanto.

¿Es la vista previa lo suficientemente estable para producción?

Todavía no. El modelo está etiquetado como vista previa pública y puede cambiar antes del lanzamiento de los pesos. Fija tus pruebas, ejecútalas de nuevo cuando Mistral actualice el modelo y mantén configurado un modelo de respaldo.

¿Puedo usar Large 4 con mi código Mistral existente?

Sí. La URL base, autenticación y SDK son los mismos. Cambia la cadena model a mistral-large-4. Si vienes de Medium 3.5, consulta esta guía de la API de Mistral Medium 3.5 para las partes que se mantienen.

Resumen

En cinco minutos puedes tener una llamada funcional. Dedica la siguiente hora a ejecutar tus prompts reales contra Large 4 y tu modelo actual en paralelo.

Guarda ambas solicitudes en Apidog, añade aserciones para el estado y la forma de respuesta, y podrás decidir rápidamente si Le Chonk merece un lugar en tu pila mientras el precio de vista previa sigue a mitad de precio.