Activar el modo JSON
En esta página
Actualizado el 3 de noviembre de 2026: Los ejemplos de TypeScript importaban anteriormente
Mistralcomo una exportación por defecto (import Mistral from …), pero el SDK solo ofrece una exportación con nombre:import { Mistral } from "@mistralai/mistralai". Además, pasaban un contenido tipado comostring | ContentChunk[]directamente aJSON.parsey codificaban la clave de API en el código fuente. Verificado mediante compilación con el SDK 3.5.0 y TypeScript 7.0.2. Fuente: Mistral TypeScript SDK.
Cómo funciona el modo JSON
El modo JSON es el mecanismo más sencillo para obtener una salida estructurada de Mistral. Al activar un único parámetro, garantizas que la respuesta del modelo sea un JSON válido. No hace falta definir ningún esquema ni escribir ningún modelo de datos; solo obtendrás JSON sintácticamente correcto en cada llamada.
Activación en Python
Se activa mediante el parámetro response_format en el método client.chat.complete(). Ten en cuenta que el propio prompt debe describir la estructura esperada; explicaremos por qué esto no es opcional dentro de un momento.
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": "Describe las 3 ventajas principales de la computación en la nube. Devuelve el resultado como JSON con una clave 'advantages' que contenga una lista de objetos con 'title' y 'description'."
}
],
response_format={"type": "json_object"}
)
print(response.choices[0].message.content)
La salida será un JSON válido, listo para usar tal cual:
{
"advantages": [
{
"title": "Escalabilidad",
"description": "Ajuste dinámico de los recursos según la demanda."
},
{
"title": "Reducción de costes",
"description": "No se requiere inversión en infraestructura física."
},
{
"title": "Accesibilidad",
"description": "Acceso a los servicios desde cualquier lugar."
}
]
}
Activación en TypeScript
El SDK de TypeScript sigue exactamente la misma lógica, con nomenclatura en camelCase: el parámetro es responseFormat y el análisis se realiza con JSON.parse(). Aplica una precaución adicional: el SDK tipa content como string | ContentChunk[], por lo que JSON.parse solo aceptará el valor después de verificar que efectivamente es una cadena de texto.
import { Mistral } from "@mistralai/mistralai";
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const response = await client.chat.complete({
model: "mistral-large-latest",
messages: [
{
role: "user",
content: "Enumera 3 frameworks populares de JavaScript en JSON con 'name' y 'useCase'."
}
],
responseFormat: { type: "json_object" },
});
const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
throw new Error("La respuesta no contiene texto JSON.");
}
const data = JSON.parse(contenu);
console.log(data);
Las instrucciones explícitas no son opcionales
Este es el punto que muchos desarrolladores pasan por alto y la causa de la mayor parte de las decepciones con el modo JSON: activar el parámetro no es suficiente. El modo garantiza la sintaxis, no el contenido. Debes instruir explícitamente al modelo, dentro del prompt, sobre el formato que esperas.
Compara las siguientes dos llamadas. En la primera, no se da ninguna guía estructural: el modelo producirá JSON, pero las claves, sus nombres y su anidamiento variarán de una llamada a otra, dejando a tu código posterior sin puntos de anclaje estables.
# Mala práctica: sin instrucción JSON en el prompt
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{"role": "user", "content": "¿Cuáles son las ventajas de la nube?"}
],
response_format={"type": "json_object"}
)
# El modelo producirá JSON, pero la estructura será impredecible
En la segunda, se inserta un esqueleto estructural directamente en el prompt. El modelo tiene ahora un objetivo que imitar, lo que hace que la salida sea predecible entre llamadas.
# Buena práctica: instrucción clara en el prompt
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "user",
"content": """¿Cuáles son las ventajas de la computación en la nube?
Devuelve tu respuesta en JSON con la siguiente estructura:
{
"topic": "string",
"advantages": [
{"title": "string", "description": "string"}
]
}"""
}
],
response_format={"type": "json_object"}
)
Incluir un ejemplo de estructura en tu prompt guía al modelo hacia el formato deseado. Esto no es una garantía absoluta como las Salidas Estructuradas Personalizadas, pero es más que suficiente para la mayoría de los casos de uso.
Trasladar las instrucciones de formato al prompt del sistema
Una vez que el mismo procesamiento se repite a lo largo de cientos de entradas, dejar las instrucciones de formato en el mensaje del usuario se vuelve inmanejable: las copias en cada llamada y se mezclan con el contenido a procesar. Trasládalas en su lugar al prompt del sistema.
response = client.chat.complete(
model="mistral-large-latest",
messages=[
{
"role": "system",
"content": "Eres un asistente de extracción de datos. SIEMPRE devuelves tus respuestas en JSON con las claves 'entities', 'confidence' y 'source'."
},
{
"role": "user",
"content": "Extrae información de este texto: 'Acme Corp, fundada en 2019 en Lyon, emplea a 250 personas.'"
}
],
response_format={"type": "json_object"}
)
Esta separación —las instrucciones de formato llevadas por el rol system y el contenido a procesar por el rol user— hace que tu código sea significativamente más mantenible: cambiar el formato ocurre en un único lugar.
Análisis de la respuesta
Un último hábito que debes adquirir: la respuesta del modo JSON es siempre una cadena JSON dentro de message.content, nunca un objeto. El análisis es responsabilidad tuya, en ambos lenguajes.
import json
raw = response.choices[0].message.content
data = json.loads(raw)
# Acceder a los datos
for advantage in data["advantages"]:
print(f"- {advantage['title']}: {advantage['description']}")
const contenu = response.choices[0]?.message?.content;
if (typeof contenu !== "string") {
throw new Error("La respuesta no contiene texto JSON.");
}
const data = JSON.parse(contenu);
data.advantages.forEach((adv: any) => {
console.log(`- ${adv.title}: ${adv.description}`);
});
Puntos clave
- Activa el modo JSON con
response_format: {"type": "json_object"} - Usa
client.chat.complete()(noparse()) - Siempre instruye al modelo en el prompt sobre la estructura JSON esperada
- La respuesta es una cadena JSON; analízala con
json.loads()oJSON.parse() - Coloca las instrucciones de formato en el prompt del sistema para pipelines repetitivos