@ai-sdk/mistral
Version:
The **[Mistral provider](https://ai-sdk.dev/providers/ai-sdk-providers/mistral)** for the [AI SDK](https://ai-sdk.dev/docs) contains language model, embedding model, and speech model support for Mistral APIs.
448 lines (334 loc) • 14.9 kB
text/mdx
---
title: Mistral AI
description: Learn how to use Mistral.
---
# Mistral AI Provider
The [Mistral AI](https://mistral.ai/) provider contains language model,
embedding model, and speech model support for Mistral APIs.
## Setup
The Mistral provider is available in the `@ai-sdk/mistral` module. You can install it with
<InstallPackages packages="@ai-sdk/mistral" />
## Provider Instance
You can import the default provider instance `mistral` from `@ai-sdk/mistral`:
```ts
import { mistral } from '@ai-sdk/mistral';
```
If you need a customized setup, you can import `createMistral` from `@ai-sdk/mistral`
and create a provider instance with your settings:
```ts
import { createMistral } from '@ai-sdk/mistral';
const mistral = createMistral({
// custom settings
});
```
You can use the following optional settings to customize the Mistral provider instance:
- **baseURL** _string_
Use a different URL prefix for API calls, e.g. to use proxy servers.
The default prefix is `https://api.mistral.ai/v1`.
- **apiKey** _string_
API key that is being sent using the `Authorization` header.
It defaults to the `MISTRAL_API_KEY` environment variable.
- **headers** _Record<string,string>_
Custom headers to include in the requests.
- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise<Response>_
Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
Defaults to the global `fetch` function.
You can use it as a middleware to intercept requests,
or to provide a custom fetch implementation for e.g. testing.
## Language Models
You can create models that call the [Mistral chat API](https://docs.mistral.ai/api/#operation/createChatCompletion) using a provider instance.
The first argument is the model id, e.g. `mistral-large-latest`.
Some Mistral chat models support tool calls.
```ts
const model = mistral('mistral-large-latest');
```
Mistral chat models also support additional model settings that are not part of the [standard call settings](/docs/ai-sdk-core/settings).
You can pass them as an options argument and utilize `MistralLanguageModelChatOptions` for typing:
```ts
import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
const model = mistral('mistral-large-latest');
await generateText({
model,
providerOptions: {
mistral: {
safePrompt: true, // optional safety prompt injection
parallelToolCalls: false, // disable parallel tool calls (one tool per response)
} satisfies MistralLanguageModelChatOptions,
},
});
```
The following optional provider options are available for Mistral models:
- **safePrompt** _boolean_
Whether to inject a safety prompt before all conversations.
Defaults to `false`.
- **documentImageLimit** _number_
Maximum number of images to process in a document.
- **documentPageLimit** _number_
Maximum number of pages to process in a document.
- **strictJsonSchema** _boolean_
Whether to use strict JSON schema validation for structured outputs. Only applies when a schema is provided and only sets the [`strict` flag](https://docs.mistral.ai/api/#tag/chat/operation/chat_completion_v1_chat_completions_post) in addition to using [Custom Structured Outputs](https://docs.mistral.ai/capabilities/structured-output/custom_structured_output/), which is used by default if a schema is provided.
Defaults to `false`.
- **structuredOutputs** _boolean_
Whether to use [structured outputs](#structured-outputs). When enabled, tool calls and object generation will be strict and follow the provided schema.
Defaults to `true`.
- **parallelToolCalls** _boolean_
Whether to enable parallel function calling during tool use. When set to false, the model will use at most one tool per response.
Defaults to `true`.
### Document OCR
Mistral chat models support document OCR for PDF files.
You can optionally set image and page limits using the provider options.
```ts
import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
import { generateText } from 'ai';
const result = await generateText({
model: mistral('mistral-small-latest'),
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: 'What is an embedding model according to this document?',
},
{
type: 'file',
data: new URL(
'https://github.com/vercel/ai/blob/main/examples/ai-functions/data/ai.pdf?raw=true',
),
mediaType: 'application/pdf',
},
],
},
],
// optional settings:
providerOptions: {
mistral: {
documentImageLimit: 8,
documentPageLimit: 64,
} satisfies MistralLanguageModelChatOptions,
},
});
```
### Reasoning Models
Mistral offers reasoning models that provide step-by-step thinking capabilities:
- **magistral-small-2507**: Smaller reasoning model for efficient step-by-step thinking
- **magistral-medium-2507**: More powerful reasoning model balancing performance and cost
These models return structured reasoning content that the AI SDK extracts automatically. The reasoning is available via the `reasoningText` property in the result:
```ts
import { mistral } from '@ai-sdk/mistral';
import { generateText } from 'ai';
const result = await generateText({
model: mistral('magistral-small-2507'),
prompt: 'What is 15 * 24?',
});
console.log('REASONING:', result.reasoningText);
// Output: "Let me calculate this step by step..."
console.log('ANSWER:', result.text);
// Output: "360"
```
The SDK automatically parses Mistral's native reasoning format and provides separate `reasoningText` and `text` properties in the result. No middleware is needed.
#### Configurable Reasoning
Some Mistral models support configurable reasoning, which you can control via the `reasoning` parameter.
You can use the AI SDK's top-level `reasoning` setting to control reasoning effort:
```ts
import { mistral } from '@ai-sdk/mistral';
import { generateText } from 'ai';
const result = await generateText({
model: mistral('mistral-small-latest'),
reasoning: 'high',
prompt: 'What is 15 * 24?',
});
console.log('REASONING:', result.reasoningText);
console.log('ANSWER:', result.text);
```
So far, Mistral only supports `'high'` and `'none'` as effort levels.
### Example
You can use Mistral language models to generate text with the `generateText` function:
```ts
import { mistral } from '@ai-sdk/mistral';
import { generateText } from 'ai';
const { text } = await generateText({
model: mistral('mistral-large-latest'),
prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});
```
Mistral language models can also be used in the `streamText` function
and support structured data generation with [`Output`](/docs/reference/ai-sdk-core/output)
(see [AI SDK Core](/docs/ai-sdk-core)).
#### Structured Outputs
Mistral chat models support structured outputs using JSON Schema. You can use `generateText` or `streamText` with [`Output`](/docs/reference/ai-sdk-core/output)
and Zod, Valibot, or raw JSON Schema. The SDK sends your schema via Mistral's `response_format: { type: 'json_schema' }`.
```ts
import { mistral } from '@ai-sdk/mistral';
import { generateText, Output } from 'ai';
import { z } from 'zod';
const result = await generateText({
model: mistral('mistral-large-latest'),
output: Output.object({
schema: z.object({
recipe: z.object({
name: z.string(),
ingredients: z.array(z.string()),
instructions: z.array(z.string()),
}),
}),
}),
prompt: 'Generate a simple pasta recipe.',
});
console.log(JSON.stringify(result.output, null, 2));
```
You can enable strict JSON Schema validation using a provider option:
```ts highlight="7-11"
import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
import { generateText, Output } from 'ai';
import { z } from 'zod';
const result = await generateText({
model: mistral('mistral-large-latest'),
providerOptions: {
mistral: {
strictJsonSchema: true,
} satisfies MistralLanguageModelChatOptions,
},
output: Output.object({
schema: z.object({
title: z.string(),
items: z.array(
z.object({ id: z.string(), qty: z.number().int().min(1) }),
),
}),
}),
prompt: 'Generate a small shopping list.',
});
```
<Note>
When using structured outputs, the SDK no longer injects an extra "answer with
JSON" instruction. It relies on Mistral's native `json_schema`/`json_object`
response formats instead. You can customize the schema name/description via
the standard structured-output APIs.
</Note>
### Model Capabilities
| Model | Image Input | Object Generation | Tool Usage | Tool Streaming |
| ----------------------- | ----------- | ----------------- | ---------- | -------------- |
| `pixtral-large-latest` | <Check /> | <Check /> | <Check /> | <Check /> |
| `mistral-large-latest` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `mistral-medium-latest` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `mistral-medium-3` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `mistral-medium-2508` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `mistral-medium-2505` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `mistral-medium-3.5` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `mistral-small-latest` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `magistral-small-2507` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `magistral-medium-2507` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `magistral-small-2506` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `magistral-medium-2506` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `ministral-3b-latest` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `ministral-8b-latest` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `pixtral-12b-2409` | <Check /> | <Check /> | <Check /> | <Check /> |
| `open-mistral-7b` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `open-mixtral-8x7b` | <Cross /> | <Check /> | <Check /> | <Check /> |
| `open-mixtral-8x22b` | <Cross /> | <Check /> | <Check /> | <Check /> |
<Note>
The table above lists popular models. Please see the [Mistral
docs](https://docs.mistral.ai/getting-started/models/models_overview/) for a
full list of available models. The table above lists popular models. You can
also pass any available provider model ID as a string if needed.
</Note>
## Speech Models
You can create models that call the
[Mistral speech API](https://docs.mistral.ai/api/endpoint/audio/speech) using
the `.speech()` factory method:
```ts
const model = mistral.speech('voxtral-mini-tts-2603');
```
Use a preset or saved voice ID with [`generateSpeech`](/docs/reference/ai-sdk-core/generate-speech):
```ts
import { mistral } from '@ai-sdk/mistral';
import { generateSpeech } from 'ai';
const result = await generateSpeech({
model: mistral.speech('voxtral-mini-tts-2603'),
text: 'Hello from the AI SDK!',
voice: 'en_paul_neutral',
outputFormat: 'mp3',
});
const audio = result.audio.uint8Array;
```
The Mistral speech model maps `voice` to Mistral's `voice_id`. It supports
`mp3`, `wav`, `pcm`, `flac`, and `opus` output formats and defaults to `mp3`.
The `instructions`, `speed`, and `language` settings are not supported and
produce warnings when provided.
Mistral also supports one-off voice cloning with base64-encoded reference
audio. Pass it through `providerOptions.mistral.refAudio` and use
`MistralSpeechModelOptions` for type checking:
```ts highlight="9-13"
import { readFile } from 'node:fs/promises';
import { mistral, type MistralSpeechModelOptions } from '@ai-sdk/mistral';
import { generateSpeech } from 'ai';
const referenceAudio = await readFile('./reference.mp3');
const result = await generateSpeech({
model: mistral.speech('voxtral-mini-tts-2603'),
text: 'Hello from the AI SDK!',
providerOptions: {
mistral: {
refAudio: referenceAudio.toString('base64'),
} satisfies MistralSpeechModelOptions,
},
});
```
When `refAudio` is provided, it takes precedence over `voice`. Reference audio
is redacted from request metadata and API call errors returned by the provider.
<Note>
Only use reference audio with the speaker's explicit consent. Follow Mistral's
voice cloning usage policy and disclose AI-generated audio when required. This
provider integration supports non-streaming speech generation; Mistral's
streaming speech API is not exposed through `SpeechModelV4`.
</Note>
### Model Capabilities
| Model | Saved Voices | Reference Audio | Non-Streaming |
| ----------------------- | ------------ | --------------- | ------------- |
| `voxtral-mini-tts-2603` | <Check /> | <Check /> | <Check /> |
## Embedding Models
You can create models that call the [Mistral embeddings API](https://docs.mistral.ai/api/#operation/createEmbedding)
using the `.embedding()` factory method.
```ts
const model = mistral.embedding('mistral-embed');
```
You can use Mistral embedding models to generate embeddings with the `embed` function:
```ts
import { mistral } from '@ai-sdk/mistral';
import { embed } from 'ai';
const { embedding } = await embed({
model: mistral.embedding('codestral-embed-2505'),
value: 'function add(a: number, b: number) { return a + b; }',
});
```
Mistral embedding models support additional provider options through
`providerOptions.mistral`. You can validate them with
`MistralEmbeddingModelOptions`:
```ts
import { mistral, type MistralEmbeddingModelOptions } from '@ai-sdk/mistral';
import { embed } from 'ai';
const { embedding } = await embed({
model: mistral.embedding('mistral-embed'),
value: 'sunny day at the beach',
providerOptions: {
mistral: {
metadata: { source: 'knowledge-base' },
outputDimension: 1024,
outputDtype: 'float',
} satisfies MistralEmbeddingModelOptions,
},
});
```
The following optional provider options are available for Mistral embedding
models:
- **metadata** _Record<string, unknown>_
Additional metadata to attach to the embedding request.
- **outputDimension** _number_
The dimension of the output embeddings when supported by the model.
- **outputDtype** _string_
The data type of the output embeddings when supported by the model. Accepts
`'float'`, `'int8'`, `'uint8'`, `'binary'`, or `'ubinary'`.
### Model Capabilities
| Model | Default Dimensions |
| --------------- | ------------------ |
| `mistral-embed` | 1024 |