Primeira Chamada e Streaming em TypeScript
Nesta página
Lição atualizada a 3 de novembro de 2026 após compilar exemplos em modo estrito com o SDK
@mistralai/mistralai3.5.0 e TypeScript 7.0.2. O SDK tipificacontentcomostring | ContentChunk[]: conversas multi-turno e loops de streaming falhavam na compilação sem uma verificaçãotypeof content === 'string'. O exemplo de configuração combinava anteriormentetemperatureetopP, o que a documentação da API desaconselha modificar em conjunto. O tratamento de erros utiliza agora a classeMistralErrordo SDK, e a rota Express valida a pergunta antes de chamar a API. Fontes: Mistral TypeScript SDK (README) · parâmetros de conclusão de chat.
Envie o Seu Primeiro Pedido
Agora que o SDK está instalado, vamos à prática. O método chat.complete() do SDK TypeScript é o equivalente exato do SDK Python: mesmos parâmetros, mesma estrutura de resposta, exceto pelas convenções de nomenclatura. Se seguiu as lições de Python, está em terreno familiar; apenas a sintaxe assíncrona do JavaScript é nova.
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();
Os pontos de interrogação em response.choices[0]?.message?.content não são apenas decorativos: nos tipos do SDK, message e content são opcionais, e choices[0] não existe se a lista vier vazia. O acesso seguro devolve undefined em vez de lançar uma exceção. Note também que content nem sempre é uma string: o SDK tipifica-o como string | ContentChunk[] porque uma resposta pode chegar como uma lista de fragmentos (texto, raciocínio thinking, referências, etc.).
Compreender a Resposta
A estrutura da resposta é idêntica à do SDK Python. Analisá-la ajuda a entender pelo que está a pagar e porque é que uma resposta parou. O exemplo seguinte extrai o texto, o motivo da paragem e a contagem de tokens um a um; ao digitá-lo, o seu editor sugerirá cada campo, provando que a tipagem está a fazer o seu trabalho.
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 da resposta
const texte = response.choices[0]?.message?.content;
// Motivo da paragem
const finRaison = response.choices[0]?.finishReason;
// Estatí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}`);
}
Note a capitalização: onde o Python expõe max_tokens, finish_reason e prompt_tokens, o TypeScript usa maxTokens, finishReason e promptTokens. Este é o erro número um ao portar manualmente um exemplo de Python — e o compilador sinalizá-lo-á imediatamente.
Streaming
O streaming é essencial para interfaces web: sem ele, o utilizador encara um ecrã congelado durante vários segundos; com ele, o texto aparece palavra por palavra e a latência percebida colapsa. O SDK TypeScript expõe o stream como um gerador assíncrono, que percorre com 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();
}
Dois detalhes merecem a sua atenção. O conteúdo reside em chunk.data, não diretamente em chunk: este é o wrapper de eventos do SDK desde a versão 1.0. E a verificação typeof content === 'string' filtra tanto fragmentos sem conteúdo, que sujariam a sua saída com undefined, como conteúdo em lista de fragmentos, que process.stdout.write não aceita: sem ela, o modo estrito recusa-se a compilar.
Expor o Stream via Express
Um stream que nunca sai do terminal não serve para nada. Eis como retransmiti-lo para um navegador usando Server-Sent Events a partir de uma API Express. A pergunta é validada antes de qualquer chamada para evitar enviar um pedido vazio à API. Os três cabeçalhos abrem então o canal, cada fragmento é enviado de volta como JSON num evento data:, e um marcador [DONE] sinaliza ao cliente para fechar a ligação.
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'));
Conversas Multi-Turno
A gestão do histórico segue o mesmo princípio que em Python: o modelo não tem memória, por isso mantém um array de mensagens e reenvia tudo a cada turno. Em TypeScript, declarar um tipo Message explícito impede que insira um papel inexistente ou um objeto mal formado — um erro que a API devolveria otherwise como um 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();
A verificação typeof contenu === 'string' não é um luxo: o campo content da resposta pode ser uma lista de fragmentos, enquanto o seu tipo Message espera uma string. Observe depois a terceira pergunta: “How do I add constraints?” só faz sentido porque as duas trocas anteriores ainda estão no array. Leve o exercício mais longe removendo a linha que adiciona a resposta do assistente ao histórico, e verá o modelo perder o fio à meada no segundo turno.
Ajustar a Geração e Tratar Erros
Os parâmetros avançados são idênticos aos do SDK Python — apenas muda a capitalização. Uma temperature baixa para um entregável estruturado e um maxTokens calibrado para o comprimento esperado produzem respostas mais previsíveis. Defina temperature ou topP, não ambos: esta é a recomendação da documentação da API, que aconselha uma temperature entre 0 e 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,
});
Finalmente, qualquer chamada de rede pode falhar: chave inválida, quota excedida, indisponibilidade. Envolva sempre a chamada num try/catch e verifique o tipo de erro antes de ler as suas propriedades, caso contrário o TypeScript recusará a compilação. Todos os erros HTTP devolvidos pela API herdam de MistralError, que expõe statusCode e body; erros de rede (ConnectionError, RequestTimeoutError, etc.) não herdam dele, mas permanecem instâncias 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) {
// Resposta de erro da API: 401 chave recusada, 429 limite atingido...
console.error(`Mistral API Error ${error.statusCode}: ${error.message}`);
} else if (error instanceof Error) {
// Sem resposta da API: rede em baixo, tempo limite excedido...
console.error(`Error: ${error.message}`);
}
}
Pontos-chave
client.chat.complete()é assíncrono — useawait- O streaming usa
for await...ofno resultado declient.chat.stream() - A tipagem do TypeScript deteta erros de parâmetros em tempo de compilação
- A integração SSE com Express é direta para interfaces web em tempo real
- O histórico de conversação é gerido com um array tipado
Message[] contenté uma string ou uma lista de fragmentos: testetypeof content === 'string'antes de o usar como texto- Os erros HTTP do SDK herdam de
MistralError(statusCode,body)