Tu primera llamada a la API en Python
En esta página
Tu primer intercambio con un modelo de Mistral
El SDK ya está instalado y tu clave de API lista: es el momento de enviar una solicitud real y, lo que es más importante, entender qué recibes de vuelta. Muchos desarrolladores se detienen en la primera línea de la respuesta e ignoran el resto del objeto devuelto. Es un error, porque el seguimiento de costes y el diagnóstico de respuestas truncadas residen precisamente en esos datos restantes. Empezaremos con un código mínimo e iremos avanzando hasta cubrir la estructura completa.
Inicializar el cliente
El cliente es el punto de entrada para todas tus interacciones con la API:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Se encarga de las conexiones HTTP, los reintentos ante errores de red y la serialización de solicitudes. Instáncialo una sola vez al arrancar la aplicación. Recrear un cliente para cada llamada te obliga a pagar innecesariamente por el establecimiento de la conexión y es una de las causas más sutiles de latencia excesiva.
Enviar una solicitud con chat.complete()
Usarás el método chat.complete() la mayor parte del tiempo. Envía tus mensajes y espera la respuesta completa del modelo antes de devolver el control:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{
"role": "user",
"content": "Explica el concepto de tokenización en tres frases."
}
]
)
print(response.choices[0].message.content)
Aquí bastan dos parámetros. model especifica el ID del modelo: mistral-small-latest apunta siempre a la última versión de Mistral Small, lo que lo convierte en la opción natural para empezar, ya que es rápido y económico. messages espera una lista de mensajes estructurados, cada uno con un role —system, user o assistant— y un campo content que contiene el texto. Esta estructura puede parecer pesada para una única pregunta, pero tiene todo el sentido cuando llegues a la lección sobre conversaciones de varios turnos.
Leer el objeto devuelto
El objeto response contiene mucho más que el texto generado:
# Texto de la respuesta
text = response.choices[0].message.content
# Rol (siempre "assistant" en una respuesta)
role = response.choices[0].message.role
# Motivo de parada
finish = response.choices[0].finish_reason # "stop", "length", etc.
# Estadísticas de tokens
input_tokens = response.usage.prompt_tokens
output_tokens = response.usage.completion_tokens
total_tokens = response.usage.total_tokens
print(f"Respuesta ({output_tokens} tokens): {text}")
print(f"Total de tokens consumidos: {total_tokens}")
Presta mucha atención al campo usage desde el primer día. Registrarlo en cada llamada te indica exactamente qué función de tu aplicación está quemando tu presupuesto, sin tener que hacer ingeniería inversa de tu factura a final de mes.
En cuanto a finish_reason, indica por qué se detuvo el modelo y puede tomar uno de estos valores:
stop: el modelo finalizó su respuesta de forma naturallength: la respuesta se cortó porque alcanzómax_tokensmodel_length: el contexto total (entrada + salida) alcanzó el límite del modelo
Una respuesta que se corta a mitad de frase no es un error del modelo: es un finish_reason de length que nadie comprobó. Verifícalo siempre antes de concluir que hay un problema de calidad.
Ajustar el comportamiento del modelo
Tres parámetros adicionales te permiten dirigir la generación:
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": "Propón tres nombres para una startup educativa de IA."
}
],
temperature=0.7,
max_tokens=500,
top_p=0.95,
)
Temperature controla el grado de libertad del modelo. En 0.0, las respuestas son deterministas: el mismo prompt produce siempre el mismo texto, lo que deseas para extracción o clasificación. Entre 0.3 y 0.5, obtienes un buen equilibrio para tareas factuales. Entre 0.7 y 1.0, las respuestas se vuelven más creativas y variadas; este es el rango usado en el ejemplo anterior, ya que pedimos ideas de nombres y ver tres veces la misma idea carecería de sentido. Por encima de 1.0, la generación se vuelve muy aleatoria y rara vez tiene utilidad práctica.
max_tokens limita la longitud de la respuesta, lo que ayuda a controlar costes y mantiene las salidas manejables. Recuerda simplemente que, si el modelo se corta, finish_reason será "length". top_p afecta a la diversidad mediante un mecanismo distinto: filtra los tokens menos probables. Un valor de 0.95 significa que el modelo solo considera los tokens que representan el 95 % de la probabilidad acumulada.
Una llamada lista para producción
En condiciones reales, la red falla, las claves caducan y las cuotas se agotan. Envuelve siempre tus llamadas en gestión de errores:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
try:
response = client.chat.complete(
model="mistral-small-latest",
messages=[
{"role": "user", "content": "¿Cuál es la capital de Francia?"}
],
max_tokens=100,
)
text = response.choices[0].message.content
print(f"Respuesta: {text}")
print(f"Tokens usados: {response.usage.total_tokens}")
except Exception as e:
print(f"Error en la llamada a la API: {e}")
Usa este esqueleto para tus propios experimentos sustituyendo simplemente el contenido del mensaje. Es el punto de partida para todo lo que sigue en este curso.
Puntos clave
client.chat.complete()es el método principal para interactuar con los modelos- El texto de la respuesta está en
response.choices[0].message.content response.usageindica cuántos tokens se han consumido (útil para el seguimiento de costes)temperaturecontrola la creatividad;max_tokenslimita la longitud- Empieza con
mistral-small-latest: es rápido, económico y ofrece buen rendimiento