Instalar o SDK TypeScript da Mistral
Nesta página
Lição atualizada em 3 de novembro de 2026 após execução dos exemplos com o SDK
@mistralai/mistralai3.5.0 e TypeScript 7.0.2. A versão original não compilava. Executarnpx tscsem o TypeScript instalado transfere o pacote npm abandonadotsc(versão 2.0.4) em vez do compilador. O script de teste estava localizado fora da pastasrcdeclarada emtsconfig.json. O objetoprocesssó é reconhecido com@types/node. Por fim, o modo estrito rejeitamodels.data.lengthemodel.idsem validação prévia. Otsconfig.jsonsegue agora o cenário «compilar e depois executar com Node.js» do guia TypeScript, e as versões Node.js 18 e 20, que chegaram ao fim de vida, deixaram de ser listadas como suficientes. Fontes: Download TypeScript · Choosing compiler options (TypeScript) · TypeScript 6.0 changes · tsx and TypeScript · SDK supported runtimes · Node.js release schedule.
Por que utilizar o SDK TypeScript?
Se a sua pilha tecnológica assenta no Node.js, Deno ou Bun, o SDK TypeScript da Mistral permite-lhe integrar modelos diretamente nas suas aplicações JavaScript e TypeScript. Evita camadas intermédias em Python ou a escrita de chamadas HTTP personalizadas. Este é o cenário mais comum ao adicionar IA a uma aplicação web existente: uma API Express, um backend Next.js ou um worker Node a processar uma fila de mensagens.
A tipagem estática do TypeScript adiciona uma rede de segurança que compensa logo na primeira hora de desenvolvimento. O seu editor completa os nomes dos parâmetros, poupando-o de adivinhar entre maxTokens e max_tokens; erros de capitalização ou campos inventados surgem na compilação, e não em produção às 3 da manhã; e a documentação dos parâmetros aparece ao passar o rato, sem sair do ficheiro. Esta rede de segurança é ainda mais relevante porque as respostas da API são objetos aninhados, onde é fácil perder um nível.
Pré-requisitos
O SDK destina-se às versões LTS mantidas do Node.js. Em 3 de novembro de 2026, estas são as versões 22, 24 e 26; o Node.js 18 e 20 já não recebem correções de segurança. Verifique a sua versão com node --version antes de prosseguir: o SDK depende de módulos ES e da API nativa fetch. Precisa também de um gestor de pacotes (npm, yarn ou pnpm) e de uma chave de API Mistral criada e disponível como variável de ambiente, conforme abordado em lições anteriores.
Instalação
O SDK oficial é publicado no npm como @mistralai/mistralai:
# Com npm
npm install @mistralai/mistralai
# Com yarn
yarn add @mistralai/mistralai
# Com pnpm
pnpm add @mistralai/mistralai
Configuração do TypeScript
Se utilizar TypeScript — o que recomendamos — instale três ferramentas como dependências de desenvolvimento: o compilador, tsx (que executa ficheiros .ts sem etapa de compilação) e @types/node (que descreve objetos do Node.js como process ao TypeScript):
npm install -D typescript tsx @types/node
Não salte esta etapa. Sem o TypeScript instalado no projeto, npx tsc obtém o pacote tsc do npm — um compilador legado abandonado (2.0.4) — em vez do TypeScript. De seguida, declare o projeto como módulos ES, tal como a documentação do TypeScript exige para código compilado e depois executado pelo Node.js:
npm pkg set type=module
Por fim, crie tsconfig.json. Utiliza as definições que o guia oficial do TypeScript recomenda para este cenário (module: nodenext). Ativa também o modo estrito, que o obriga a lidar com valores potencialmente ausentes nas respostas da API — uma restrição saudável — e compila src/ para dist/:
{
"compilerOptions": {
"target": "esnext",
"module": "nodenext",
"types": ["node"],
"strict": true,
"skipLibCheck": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
Três linhas merecem explicação, pois cada uma previne um erro detetado durante os testes desta lição:
"types": ["node"]carrega os tipos do Node.js. Desde o TypeScript 6.0, os pacotes@typesdeixaram de ser carregados automaticamente. Sem esta linha,process.envdesencadeia o erro “Cannot find name ‘process’”, mesmo com@types/nodeinstalado."rootDir": "src"define a raiz de origem para os ficheiros compilados:src/test-mistral.tstorna-sedist/test-mistral.js. Sem isto, o TypeScript 7 reporta o erro TS5011 sempre que os seus fontes não estiverem na raiz do projeto."skipLibCheck": trueignora a verificação de tipos nos ficheiros de declaração de dependências. Esta é também uma definição padrão emtsconfig.jsongerado pornpx tsc --init. Com o SDK 3.5.0 e o TypeScript 7, omitir isto causa um erro nas próprias declarações do SDK que o seu código não consegue corrigir.
O SDK é publicado como módulos ES e inclui os seus próprios tipos: não é necessário nenhum pacote @types/ para o mesmo. Se o seu editor não tiver preenchimento automático, o problema reside no seu tsconfig.json, e não na falta de um pacote de tipos.
Configurar a Variável de Ambiente
Nunca codifique a chave de API diretamente no seu código-fonte. No Node.js, a solução padrão é dotenv, que carrega variáveis de um ficheiro local no arranque do processo:
npm install dotenv
Crie um ficheiro .env na raiz do seu projeto:
MISTRAL_API_KEY=your-api-key-here
Adicione imediatamente este ficheiro ao seu .gitignore, antes do seu primeiro commit. É exatamente neste momento que as chaves escapam:
.env
.env.local
A importação dotenv/config deve preceder qualquer leitura de process.env. Caso contrário, a variável permanece indefinida quando instancia o cliente:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
Verificar a Instalação
Antes de escrever lógica de negócio, valide toda a cadeia — instalação, chave, rede — com um script mínimo. Crie src/test-mistral.ts e solicite simplesmente a lista de modelos acessíveis à sua conta:
import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';
async function main() {
const client = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
// Listar modelos disponíveis
const models = await client.models.list();
const liste = models.data ?? [];
console.log(`Available models: ${liste.length}`);
for (const model of liste.slice(0, 5)) {
// Um tipo de modelo desconhecido para esta versão do SDK é marcado como 'UNKNOWN'
if (model.type === 'UNKNOWN') continue;
console.log(` - ${model.id}`);
}
}
main().catch(console.error);
Estas duas verificações não são decorativas. O SDK declara data como opcional, e cada entrada da lista é quer um cartão de modelo base, quer um cartão de modelo ajustado (fine-tuned), quer um valor desconhecido (type: 'UNKNOWN'). Quando a API adiciona um novo tipo de modelo, o SDK preserva-o nesta forma em vez de falhar. Sem estes dois testes, o modo estrito recusa-se a compilar.
Em desenvolvimento, execute-o com tsx, instalado anteriormente, que transpila em tempo real e poupa-lhe uma etapa de compilação:
npx tsx src/test-mistral.ts
Aviso: tsx não verifica tipos; remove-os e executa. Apenas tsc reporta erros de tipagem. Execute npx tsc --noEmit para verificar sem compilar. Para compilar e depois executar, tal como a sua pipeline de build fará:
npx tsc && node dist/test-mistral.js
Uma chave válida apresenta a contagem de modelos e as primeiras cinco entradas. Uma chave rejeitada apresenta um erro Status 401 (Invalid API Key): a cadeia funciona, apenas a chave está incorreta.
Organizar o Projeto
Assim que a verificação for bem-sucedida, estruture o projeto para que a chave e o cliente não se dispersem por vários ficheiros:
mon-projet/
├── src/
│ ├── index.ts # Ponto de entrada
│ ├── mistral-client.ts # Inicialização do cliente (singleton)
│ └── utils/
├── .env # Variáveis de ambiente (ignoradas pelo git)
├── .gitignore
├── package.json
└── tsconfig.json
Centralizar a inicialização do cliente num módulo dedicado evita recriá-lo em todos os ficheiros. Mais importante ainda, faz com que a aplicação falhe no arranque, e não na primeira chamada do utilizador, caso a chave esteja em falta:
// src/mistral-client.ts
import { Mistral } from '@mistralai/mistralai';
if (!process.env.MISTRAL_API_KEY) {
throw new Error('The MISTRAL_API_KEY variable is required.');
}
export const mistral = new Mistral({
apiKey: process.env.MISTRAL_API_KEY,
});
O restante código simplesmente importa este cliente pré-configurado:
// src/index.ts
import 'dotenv/config';
import { mistral } from './mistral-client.js';
Note a extensão .js na importação relativa. Com module: nodenext, o TypeScript exige o nome do ficheiro tal como existirá após a compilação, e tsx sabe mapeá-lo para o ficheiro .ts. A ordem de importação também importa: dotenv/config executa antes de mistral-client.js, pelo que a chave é carregada quando esse módulo verifica a sua presença.
Pontos-chave
- Instale o SDK TypeScript com
npm install @mistralai/mistralai - A importação principal é
import { Mistral } from '@mistralai/mistralai' - Instale
typescript,tsxe@types/nodecomo dependências de desenvolvimento antes de chamarnpx tsc - Utilize
module: nodenexte"type": "module"para código compilado e depois executado pelo Node.js; as importações relativas levam a extensão.js - Utilize um ficheiro
.envcomdotenvpara gerir a chave de API - O SDK fornece tipos TypeScript nativos: aproveite o preenchimento automático e deixe o
tscverificar o que otsxignora - Centralize a inicialização do cliente num módulo dedicado