El punto de conexión /v1/chat/completions
En esta página
Actualización 2 de noviembre de 2026 — Modelos. Mistral Large 3 (
mistral-large-2512) y Mistral Medium 3.5 quedaron obsoletos el 31 de octubre de 2026 y se retirarán el 30 de abril de 2027. Su sucesor designado, Mistral Large 4 (mistral-large-4), está en vista previa pública desde el 6 de octubre. Los ejemplos de este curso utilizan el aliasmistral-large-latest, que actualmente apunta a Mistral Large 3 según su especificación oficial (verificado el 3 de noviembre de 2026). De forma similar,mistral-medium-latestapunta a Mistral Medium 3.5. Estos alias seguirán siendo válidos hasta el 30 de abril de 2027. Para nuevos proyectos, pruebamistral-large-4, su sucesor designado.
Tu puerta de entrada a los modelos de Mistral
Todo lo que hagas con la API de Mistral pasa por una única ruta: /v1/chat/completions. Este es el centro neurálgico de la plataforma y gestiona todas tus interacciones conversacionales con los modelos de lenguaje. Tanto si estás construyendo un chatbot de soporte interno, un extractor que convierte facturas en PDF en filas de base de datos, o un asistente de escritura integrado en tu CMS, estas tres aplicaciones, aparentemente distintas, llaman exactamente al mismo punto de conexión con diferentes mensajes y parámetros. No necesitas aprender tres integraciones separadas; solo tienes que dominar una.
A fecha de abril de 2026, este punto de conexión procesa miles de millones de solicitudes diarias en todo el mundo. Comprender su estructura es el primer paso para aprovechar los modelos de Mistral en producción.
La URL base
Todas las solicitudes a la API de Mistral parten de la misma base:
https://api.mistral.ai/v1/chat/completions
Envías una solicitud POST con un cuerpo JSON que contiene tus mensajes y parámetros, y la API devuelve una respuesta JSON estructurada. No hay sesiones que abrir ni estado en el servidor que mantener: cada llamada es independiente.
Anatomía de una solicitud
La forma más rápida de verificar que tu clave funciona es enviar una solicitud mínima usando curl directamente desde tu terminal:
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": "Hello, how does your API work?"}
]
}'
Dos cabeceras son obligatorias: Content-Type: application/json describe el formato del cuerpo de la solicitud y Authorization: Bearer <tu-clave> lleva tu autenticación. El cuerpo en sí debe contener al menos dos campos: model, el identificador del modelo a utilizar, y messages, el array que transporta la conversación.
Equivalente en Python con el SDK
Una vez superada la fase de pruebas, nadie escribe comandos curl crudos en producción. El SDK oficial realiza la misma llamada en apenas unas líneas:
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "Hello, how does your API work?"}
]
)
print(response.choices[0].message.content)
El SDK se encarga de las cabeceras, la serialización JSON y el análisis de la respuesta por ti. También gestiona reintentos automáticos para errores temporales, ahorrándote la escritura de tu propia lógica de reintento cuando un pico de tráfico provoca un fallo transitorio.
Estructura de la respuesta
No importa cómo llames a la API; siempre devuelve el mismo objeto JSON:
{
"id": "cmpl-abc123",
"object": "chat.completion",
"created": 1712150400,
"model": "mistral-large-latest",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Hello! The Mistral API works..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 15,
"completion_tokens": 87,
"total_tokens": 102
}
}
Tres campos merecen tu atención inmediata. choices es un array que contiene la o las respuestas generadas; aquí es donde encuentras el texto que mostrar al usuario. usage proporciona el recuento de tokens para la entrada, la salida y el total, lo que te permite rastrear el coste real de cada función en lugar de descubrir la factura a final de mes. Por último, finish_reason explica por qué se detuvo el modelo: stop para un final natural, length cuando el límite de tokens cortó la respuesta, o tool_calls cuando el modelo solicita la ejecución de herramientas. Un resumen que termina a media frase casi nunca es un problema del modelo; es un finish_reason de length que nadie leyó.
Códigos de error comunes
Cuando algo sale mal, la API devuelve códigos HTTP estándar:
- 400 — Solicitud mal formada (JSON inválido, parámetro faltante)
- 401 — Clave de API inválida o faltante
- 429 — Límite de tasa alcanzado (demasiadas solicitudes)
- 500 — Error del servidor (reintentar tras unos segundos)
En Python, el SDK lanza excepciones tipificadas que puedes capturar, lo que te permite distinguir entre una clave caducada y una saturación temporal, y reaccionar de forma diferente en cada caso:
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
client = Mistral(api_key=os.getenv("MISTRAL_API_KEY"))
try:
response = client.chat.complete(
model="mistral-large-latest",
messages=[{"role": "user", "content": "Test"}]
)
except SDKError as e:
print(f"API Error: {e.status_code} — {e.message}")
Acostúmbrate a envolver cada llamada en este bloque desde tu primer script. El día que tu aplicación se ejecute sin supervisión, te dirá qué ha fallado en lugar de detenerse en silencio.
Puntos clave
- El punto de conexión
/v1/chat/completionses el único necesario para interacciones conversacionales - Cada solicitud requiere un
modely un arraymessages - La respuesta siempre contiene
choices,usageyfinish_reason - El SDK de Python simplifica enormemente las llamadas en comparación con
curl - Los tokens de uso te permiten calcular tus costes con precisión