Ir al contenido principal
Español— Elegir un idioma
Menú

El punto de conexión /v1/chat/completions

Lección 1 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Tu puerta de entrada a los modelos de Mistral
  2. La URL base
  3. Anatomía de una solicitud
  4. Equivalente en Python con el SDK
  5. Estructura de la respuesta
  6. Códigos de error comunes
  7. Puntos clave

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 alias mistral-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-latest apunta a Mistral Medium 3.5. Estos alias seguirán siendo válidos hasta el 30 de abril de 2027. Para nuevos proyectos, prueba mistral-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.

1 punto de conexión
Para todas las conversaciones
POST
Único método HTTP
< 500 ms
Latencia del primer token (streaming)
JSON
Formato de entrada/salida

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/completions es el único necesario para interacciones conversacionales
  • Cada solicitud requiere un model y un array messages
  • La respuesta siempre contiene choices, usage y finish_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