Primera llamada y streaming en TypeScript
En esta página
Lección actualizada el 3 de noviembre de 2026 tras compilar los ejemplos en modo estricto con el SDK
@mistralai/mistralai3.5.0 y TypeScript 7.0.2. El SDK tipacontentcomostring | ContentChunk[]: las conversaciones de varios turnos y los bucles de streaming no compilaban sin una comprobacióntypeof content === 'string'. El ejemplo de configuración combinaba anteriormentetemperatureytopP, algo que la documentación de la API desaconseja modificar simultáneamente. La gestión de errores utiliza ahora la claseMistralErrordel SDK, y la ruta de Express valida la pregunta antes de llamar a la API. Fuentes: Mistral TypeScript SDK (README) · parámetros de finalización de chat.
Envía tu primera solicitud
Ahora que el SDK está instalado, pasemos a la práctica. El método chat.complete() del SDK de TypeScript es exactamente equivalente al del SDK de Python: mismos parámetros, misma estructura de respuesta, salvo por las convenciones de nomenclatura. Si has seguido las lecciones de Python, estás en terreno conocido; lo único nuevo es la sintaxis asíncrona de JavaScript.
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
async function main() {
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: [
{
role: 'user',
content: 'Explain the concept of a closure in JavaScript in three sentences.',
},
],
});
console.log(response.choices[0]?.message?.content);
}
main();
Los signos de interrogación en response.choices[0]?.message?.content no están ahí por adornar: en los tipos del SDK, message y content son opcionales, y choices[0] no existe si la lista vuelve vacía. El acceso seguro devuelve undefined en lugar de lanzar una excepción. Ten también en cuenta que content no siempre es una cadena: el SDK lo tipa como string | ContentChunk[] porque una respuesta puede llegar como una lista de fragmentos (texto, razonamiento thinking, referencias, etc.).
Comprensión de la respuesta
La estructura de la respuesta es idéntica a la del SDK de Python. Analizarla te ayuda a entender qué estás pagando y por qué se detuvo una respuesta. El siguiente ejemplo extrae el texto, el motivo de parada y el recuento de tokens uno a uno; escribirlo hará que tu editor sugiera cada campo, demostrando que el tipado está haciendo su trabajo.
async function analyserReponse() {
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: [
{ role: 'user', content: 'What is the capital of France?' },
],
maxTokens: 100,
});
// Texto de la respuesta
const texte = response.choices[0]?.message?.content;
// Motivo de parada
const finRaison = response.choices[0]?.finishReason;
// Estadísticas de tokens
const tokensEntree = response.usage?.promptTokens;
const tokensSortie = response.usage?.completionTokens;
console.log(`Response: ${texte}`);
console.log(`Tokens: ${tokensEntree} input + ${tokensSortie} output`);
console.log(`Stop: ${finRaison}`);
}
Fíjate en las mayúsculas: mientras que Python expone max_tokens, finish_reason y prompt_tokens, TypeScript usa maxTokens, finishReason y promptTokens. Este es el error número uno al portar manualmente un ejemplo de Python, y el compilador lo señalará de inmediato.
Streaming
El streaming es esencial para las interfaces web: sin él, el usuario contempla una pantalla congelada durante varios segundos; con él, el texto aparece palabra a palabra y la latencia percibida se desploma. El SDK de TypeScript expone el flujo como un generador asíncrono, que iteras con for await...of:
async function streamReponse() {
const stream = await client.chat.stream({
model: 'mistral-small-latest',
messages: [
{
role: 'user',
content: 'Describe the five main design patterns in JavaScript.',
},
],
});
for await (const chunk of stream) {
const content = chunk.data.choices[0]?.delta.content;
if (typeof content === 'string') {
process.stdout.write(content);
}
}
console.log();
}
Dos detalles merecen tu atención. El contenido reside en chunk.data, no directamente en chunk: este es el contenedor de eventos del SDK desde la versión 1.0. Y la comprobación typeof content === 'string' filtra tanto los fragmentos sin contenido, que ensuciarían tu salida con undefined, como el contenido en forma de lista de fragmentos, que process.stdout.write no acepta: sin ella, el modo estricto se niega a compilar.
Exposición del flujo mediante Express
Un flujo que nunca sale de la terminal no sirve de nada. Aquí tienes cómo retransmitirlo a un navegador usando Server-Sent Events desde una API de Express. La pregunta se valida antes de cualquier llamada para evitar enviar una solicitud vacía a la API. Los tres encabezados abren entonces el canal, cada fragmento se envía de vuelta como JSON en un evento data:, y un marcador [DONE] señala al cliente que cierre la conexión.
import express from 'express';
import { Mistral } from '@mistralai/mistralai';
const app = express();
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
app.get('/api/chat', async (req, res) => {
const question = typeof req.query.q === 'string' ? req.query.q : '';
if (!question) {
res.status(400).json({ error: 'Missing q parameter' });
return;
}
res.setHeader('Content-Type', 'text/event-stream');
res.setHeader('Cache-Control', 'no-cache');
res.setHeader('Connection', 'keep-alive');
const stream = await client.chat.stream({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: question }],
});
for await (const chunk of stream) {
const content = chunk.data.choices[0]?.delta.content;
if (typeof content === 'string' && content) {
res.write(`data: ${JSON.stringify({ text: content })}\n\n`);
}
}
res.write('data: [DONE]\n\n');
res.end();
});
app.listen(3000, () => console.log('Server on port 3000'));
Conversaciones de varios turnos
La gestión del historial sigue el mismo principio que en Python: el modelo no tiene memoria, así que mantienes un array de mensajes y reenvías todo el conjunto en cada turno. En TypeScript, declarar un tipo Message explícito evita introducir un rol inexistente o un objeto mal formado, un error que la API devolvería otherwise como un 400.
import { Mistral } from '@mistralai/mistralai';
type Message = {
role: 'system' | 'user' | 'assistant';
content: string;
};
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });
const historique: Message[] = [
{
role: 'system',
content: 'You are an expert TypeScript assistant. Respond in English.',
},
];
async function poserQuestion(question: string): Promise<string> {
historique.push({ role: 'user', content: question });
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: historique,
});
const contenu = response.choices[0]?.message?.content;
const reponse = typeof contenu === 'string' ? contenu : '';
historique.push({ role: 'assistant', content: reponse });
return reponse;
}
async function main() {
console.log(await poserQuestion('What is a generic type?'));
console.log(await poserQuestion('Show me a concrete example.'));
console.log(await poserQuestion('How do I add constraints?'));
}
main();
La comprobación typeof contenu === 'string' no es un lujo: el campo content de la respuesta puede ser una lista de fragmentos, mientras que tu tipo Message espera una cadena. Observa luego la tercera pregunta: «¿Cómo añado restricciones?» solo tiene sentido porque los dos intercambios anteriores siguen en el array. Pon a prueba el ejercicio eliminando la línea que añade la respuesta del asistente al historial, y verás cómo el modelo pierde el hilo en el segundo turno.
Ajuste de la generación y gestión de errores
Los parámetros avanzados son idénticos a los del SDK de Python; solo cambia la capitalización. Una temperature baja para un entregable estructurado y un maxTokens calibrado a la longitud esperada producen respuestas más predecibles. Establece temperature o topP, no ambos: esta es la recomendación de la documentación de la API, que aconseja una temperature entre 0 y 0,7.
const response = await client.chat.complete({
model: 'mistral-large-latest',
messages: [
{ role: 'user', content: 'Propose an architecture for a B2B SaaS.' },
],
temperature: 0.5,
maxTokens: 1000,
});
Por último, cualquier llamada de red puede fallar: clave no válida, cuota superada, interrupción del servicio. Envuelve siempre la llamada en un try/catch y comprueba el tipo de error antes de leer sus propiedades; de lo contrario, TypeScript se negará a compilar. Todos los errores HTTP devueltos por la API heredan de MistralError, que expone statusCode y body; los errores de red (ConnectionError, RequestTimeoutError, etc.) no heredan de ella, pero siguen siendo instancias de Error.
import * as errors from '@mistralai/mistralai/models/errors';
try {
const response = await client.chat.complete({
model: 'mistral-small-latest',
messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0]?.message?.content);
} catch (error) {
if (error instanceof errors.MistralError) {
// Respuesta de error de la API: clave rechazada 401, límite alcanzado 429...
console.error(`Mistral API Error ${error.statusCode}: ${error.message}`);
} else if (error instanceof Error) {
// Sin respuesta de la API: red caída, tiempo de espera superado...
console.error(`Error: ${error.message}`);
}
}
Puntos clave
client.chat.complete()es asíncrono: usaawait- El streaming utiliza
for await...ofsobre el resultado declient.chat.stream() - El tipado de TypeScript detecta errores de parámetros en tiempo de compilación
- La integración SSE con Express es sencilla para interfaces web en tiempo real
- El historial de conversación se gestiona con un array tipado
Message[] contentes una cadena o una lista de fragmentos: compruebatypeof content === 'string'antes de usarlo como texto- Los errores HTTP del SDK heredan de
MistralError(statusCode,body)