¿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 el “Le Chonk” de 1 billón de parámetros ahora, la API es la única forma de acceder, y en este momento también es 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.

Esta guía te lleva de cero a una primera llamada funcional en unos cinco minutos, luego cubre las partes que suelen confundir a la gente: fragmentos de razonamiento, entrada de imágenes, llamadas a funciones, salida JSON y coste. Cada solicitud se puede guardar y reproducir en Apidog para que puedas comparar Large 4 con cualquier modelo que uses hoy.

¿Nuevo en el modelo? Lee primero Mistral Ha Vuelto: Le Chonk Supera a GPT-6 Astra y Claude en Ciberseguridad para ver los puntos de referencia y el truco detrás del titular de ciberseguridad.

Lo que necesitas

Paso 1: Obtén una clave API

1. Inicia sesión en Mistral Studio (anteriormente La Plateforme).
2. Abre Claves API y crea una nueva clave. Dale un nombre que indique dónde se utilizará, como local-dev o ci-staging.
3. Cópiala una vez. Studio no la mostrará de nuevo.
4. Expórtala en tu shell:

export MISTRAL_API_KEY="your-key-here"

Mantén la clave fuera del control de código fuente. Si la estás conectando a varias herramientas, nuestra guía de mejores prácticas de gestión de claves API cubre la rotación y el alcance.

Paso 2: Realiza tu primera llamada

La verificación más rápida es un simple 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 exitosa devuelve choices[0].message.content con la respuesta y un bloque usage con prompt_tokens, completion_tokens y total_tokens. Si recibes un 401, la clave es incorrecta o no ha sido exportada. Un 404 en el modelo generalmente significa un error tipográfico en el ID del modelo.

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)

Y 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: Guárdalo en Apidog

Escribir comandos curl se vuelve tedioso en el momento en que empiezas a comparar modelos. En Apidog:

1. Crea una nueva solicitud HTTP: POST https://api.mistral.ai/v1/chat/completions.
2. Añade una variable de entorno MISTRAL_API_KEY y configura el encabezado Authorization: Bearer {{MISTRAL_API_KEY}}.
3. Pega el cuerpo JSON del Paso 2 y pulsa Enviar.
4. Duplica la solicitud, cambia model al modelo que usas hoy (por ejemplo, mistral-medium-3-5), y ejecuta ambas.

Ahora tienes dos solicitudes guardadas con el mismo prompt. Apidog muestra el cuerpo de la respuesta, el estado, el tiempo y el tamaño para cada una, para que puedas comparar la calidad de la respuesta, la latencia y los recuentos de tokens de usage sin escribir un script. Añade una aserción post-respuesta de que choices[0].message.content no está vacío y tendrás una prueba de humo que podrás volver a ejecutar cada vez que Mistral actualice la vista previa.

Paso 4: Activar y desactivar el razonamiento

Large 4 es un modelo híbrido: el mismo modelo gestiona respuestas rápidas y razonamiento paso a paso. Lo controlas con un parámetro, reasoning_effort:

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"
  }'

**Esta es la parte que rompe los analizadores.** Con reasoning_effort: "high", message.content ya no es una cadena. Se convierte en una lista de fragmentos:

• un fragmento thinking que contiene el rastro de razonamiento, y
• un fragmento text que contiene la respuesta final.

Así que response.choices[0].message.content imprimirá una lista, no tu respuesta. Extrae explícitamente el fragmento de texto:

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, por lo que "high" cuesta más por solicitud. Establece el valor predeterminado en "none" y cambia a "high" solo en las llamadas que lo necesiten.

Paso 5: Envía una imagen

Large 4 es multimodal de forma nativa, con un codificador de visión de 1.6B parámetros. Pasa las imágenes como partes del contenido junto a tu 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, envía una URL de datos base64 en su lugar: "image_url": "data:image/png;base64,<encoded>". Mistral informa que Large 4 obtiene un 42% en el benchmark Dense 200 de anclaje visual, justo por delante del 41% de GPT-6 Astra, por lo que las capturas de pantalla de dashboards, gráficos y estados de UI son una opción razonable.

Paso 6: Llamada a funciones

La llamada a funciones es donde los benchmarks de agente de Large 4 (59.9% en AutomationBench) se vuelven útiles. Tú describes las herramientas, el modelo decide cuándo llamarlas, y tu código ejecuta la llamada.

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)

Ejecuta la función tú mismo, luego envía el resultado de vuelta con 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 la herramienta es un JSON Schema simple. Si tu API ya tiene una especificación OpenAPI, puedes trasladar el esquema de solicitud para cada operación directamente a parameters. Diseñar la especificación en Apidog primero mantiene las definiciones de la herramienta y la API real sincronizadas.

Paso 7: Obtener JSON de vuelta

Cuando necesites una salida 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 en el prompt así como en response_format. Para formas estrictas, Mistral también soporta {"type": "json_schema", "json_schema": {...}} con un esquema completo. En Apidog, añade una aserción de JSON Schema en la respuesta para que una forma cambiante falle ruidosamente en lugar de romper un servicio posterior.

Cuánto cuesta

Un ejemplo práctico: un agente que realiza 10,000 llamadas al día, cada una con 3,000 tokens de entrada (principalmente un 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é, eso es 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 precio de vista previa**, o alrededor de $31 con precio de lista.

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

Errores comunes

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 esperas. Usa los SDK de Mistral o HTTP puro para mayor seguridad. La salida de razonamiento utiliza 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. Nuestra guía ejecutar Mistral 3 localmente cubre las herramientas para los 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, vuélvelas a ejecutar cuando Mistral actualice el modelo y mantén un modelo de respaldo configurado.

**¿Puedo usar Large 4 con mi código Mistral existente?** Sí. Misma URL base, misma autenticación, mismo SDK. Cambia la cadena model a mistral-large-4. Si vienes de Medium 3.5, consulta nuestra guía de la API de Mistral Medium 3.5 para las partes que se mantienen.

Resumen

Cinco minutos te darán una llamada funcional. La siguiente hora se aprovecha mejor ejecutando tus prompts reales contra Large 4 y tu modelo actual en paralelo. Guarda ambas solicitudes en Apidog, añade aserciones sobre el estado y la forma de la respuesta, y sabrás en un día si Le Chonk se gana un lugar en tu pila, mientras el precio de vista previa sigue a mitad de precio.