Mistral AI

The Mistral AI provider contains language model, embedding model, speech model, and transcription model support for Mistral APIs. You can use Mistral AI models through AI Gateway (recommended) or connect directly with @ai-sdk/mistral.

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5.5',
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

console.log(text);

Using AI Gateway

The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install ai:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available models.

Gateway feature and provider-option support depends on the model and the provider serving the request. See Gateway provider options.

Using @ai-sdk/mistral

For direct access to Mistral AI, install ai and @ai-sdk/mistral:

pnpm add ai @ai-sdk/mistral

npm install ai @ai-sdk/mistral

yarn add ai @ai-sdk/mistral

bun add ai @ai-sdk/mistral

Set your Mistral AI API credential in the MISTRAL_API_KEY environment variable:

export MISTRAL_API_KEY=your_api_key_here

AI Gateway does not expose every API in @ai-sdk/mistral. Use the direct provider for provider-specific APIs or custom connection settings.

Provider Instance

You can import the default provider instance mistral from @ai-sdk/mistral:

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:

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 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 using a provider instance. The first argument is the model id, e.g. mistral-large-latest. Some Mistral chat models support tool calls.

const model = mistral('mistral-large-latest');

Mistral chat models also support additional model settings that are not part of the standard call settings. You can pass them as an options argument and utilize MistralLanguageModelChatOptions for typing:

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 in addition to using Custom Structured Outputs, which is used by default if a schema is provided.

  Defaults to false.

• structuredOutputs boolean

  Whether to use 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.

• promptCacheKey string

  A stable identifier used to improve cache affinity for requests that share a prompt prefix.

Prompt Cache Affinity

Mistral prompt caching reuses shared prompt prefixes. Set promptCacheKey to a stable workflow, session, or conversation identifier to improve cache affinity. The provider sends it as Mistral's prompt_cache_key request field:

import { mistral, type MistralLanguageModelChatOptions } from '@ai-sdk/mistral';
import { generateText } from 'ai';

const result = await generateText({
  model: mistral('mistral-medium-3.5'),
  system: 'Classify each support request as account, billing, or technical.',
  prompt: 'The dashboard shows an error when I open an invoice.',
  providerOptions: {
    mistral: {
      promptCacheKey: 'support-classification-workflow-v1',
    } satisfies MistralLanguageModelChatOptions,
  },
});

console.log(result.usage.inputTokenDetails.cacheReadTokens);

Use the same key for requests with the same stable prefix. Multi-step generateText and streamText calls reuse their provider options for every step, so a single key applies across the complete tool loop. Prompt cache affinity is best-effort and does not guarantee a cache hit.

Treat cache keys as opaque identifiers. Do not include API keys, secrets, email addresses, or other sensitive personal data.

Document OCR

Mistral chat models support document OCR for PDF files. You can optionally set image and page limits using the provider options.

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-latest: Smaller reasoning model for efficient step-by-step thinking
• magistral-medium-latest: 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:

import { mistral } from '@ai-sdk/mistral';
import { generateText } from 'ai';

const result = await generateText({
  model: mistral('magistral-small-latest'),
  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:

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);

Most Mistral reasoning models support 'high' and 'none' as effort levels, so other levels are mapped to 'high'. GLM-5.3 models (zai-glm-5-3, zai-glm-5-3-flash, zai-glm-5, zai-glm-latest) support 'low', 'high', and 'max' and cannot disable reasoning: minimal and low are mapped to 'low', medium and high to 'high', xhigh and max to 'max', and 'none' to 'low' with a warning.

Example

You can use Mistral language models to generate text with the generateText function:

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 (see AI SDK Core).

Structured Outputs

Mistral chat models support structured outputs using JSON Schema. You can use generateText or streamText with Output and Zod, Valibot, or raw JSON Schema. The SDK sends your schema via Mistral's response_format: { type: 'json_schema' }.

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:

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.',
});

Conversations API

Use mistral.conversation(modelId) to create a model that calls Mistral's Conversations API (/v1/conversations). It supports generateText and streamText, including Mistral's built-in web search tools.

Web Search

The provider offers two tools:

• mistral.tools.webSearch(): searches the web.
• mistral.tools.webSearchPremium(): searches the web and accesses news articles through Mistral's integrated news providers.

Mistral executes these tools on the server. No execute function is needed. Search calls and results are available in result.toolCalls and result.toolResults, and URL citations are available in result.sources.

import { mistral } from '@ai-sdk/mistral';
import { generateText } from 'ai';

const result = await generateText({
  model: mistral.conversation('mistral-medium-latest'),
  tools: {
    web_search: mistral.tools.webSearch(),
  },
  prompt:
    "Use web search to find Mistral AI's official website. Cite your source.",
});

console.log(result.text);
console.log(result.sources);

Replace mistral.tools.webSearch() with mistral.tools.webSearchPremium() to use premium search.

You can also stream the answer and access citations after the stream completes:

import { mistral } from '@ai-sdk/mistral';
import { streamText } from 'ai';

const result = streamText({
  model: mistral.conversation('mistral-medium-latest'),
  tools: {
    web_search: mistral.tools.webSearch(),
  },
  prompt:
    "Use web search to find Mistral AI's official website. Cite your source.",
});

for await (const text of result.textStream) {
  process.stdout.write(text);
}

console.log(await result.sources);

Multi-Turn Conversations

Pass the previous user messages and responseMessages into the next call. Keep the complete response history, including search calls and results, so follow-up questions can use the retrieved information. The model does not retain conversation history between calls.

import { mistral } from '@ai-sdk/mistral';
import { generateText, type ModelMessage } from 'ai';

const model = mistral.conversation('mistral-medium-latest');
const tools = { web_search: mistral.tools.webSearch() };
const messages: ModelMessage[] = [
  {
    role: 'user',
    content: "Use web search to find Mistral AI's official website.",
  },
];

const first = await generateText({ model, tools, messages });
messages.push(...first.responseMessages);
messages.push({
  role: 'user',
  content:
    'Where is that company headquartered? Use web search and cite your source.',
});

const second = await generateText({ model, tools, messages });
console.log(second.text);
console.log(second.sources);

For streamText, consume the stream before appending await result.responseMessages to your message history.

Model Capabilities

Transcription Models

You can create models that call the Mistral audio transcription API using the .transcription() factory method:

const model = mistral.transcription('voxtral-mini-transcribe-3-0');

Use Mistral transcription models with transcribe:

import { mistral } from '@ai-sdk/mistral';
import { transcribe } from 'ai';
import { readFile } from 'node:fs/promises';

const result = await transcribe({
  model: mistral.transcription('voxtral-mini-transcribe-3-0'),
  audio: await readFile('audio.mp3'),
});

Mistral transcription models support additional provider options. Pass them through providerOptions.mistral and use MistralTranscriptionModelOptions for type checking:

import {
  mistral,
  type MistralTranscriptionModelOptions,
} from '@ai-sdk/mistral';
import { transcribe } from 'ai';
import { readFile } from 'node:fs/promises';

const result = await transcribe({
  model: mistral.transcription('voxtral-mini-transcribe-3-0'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    mistral: {
      timestampGranularities: ['segment'],
      diarize: true,
      returnLanguage: true,
      contextBias: ['Vercel', 'AI SDK', 'A discussion about TypeScript.'],
    } satisfies MistralTranscriptionModelOptions,
  },
});

The following optional provider options are available:

• language string

  The language of the audio, such as en. Providing it can improve accuracy.

• returnLanguage boolean

  Return the detected language with Voxtral 3. Without this option, the response language is normally absent. Cannot be true when language is provided.

• temperature number

  The sampling temperature for the transcription.

• timestampGranularities Array<'segment' | 'word'>

  Timestamp granularities to include in the response. Voxtral 3 supports only segment and allows it to be combined with language. The SDK rejects this combination for the legacy IDs voxtral-mini-2507, voxtral-mini-2602, and voxtral-mini-latest, throwing an InvalidArgumentError. Other model IDs are allowed to send the combination to Mistral. Model-specific timestamp and diarization requirements are validated by the Mistral API.

• diarize boolean

  Whether to identify speakers in the transcription. Voxtral 3 requires timestampGranularities: ['segment'] when this option is true.

• contextBias string[]

  Words, phrases, or descriptions of the recording that guide spelling for names, technical terms, or domain-specific vocabulary. Voxtral 3 accepts spaces and punctuation and has no fixed entry limit; entries share the context window with the audio. Earlier models require entries without commas or whitespace and support up to 100 entries.

The normalized result includes transcript text, language, timed segments, and duration when returned by Mistral. Mistral token and prompt-audio usage is available under result.providerMetadata.mistral.usage. Segment scores and speaker IDs from diarization are available under result.providerMetadata.mistral.segments.

Model Capabilities

Speech Models

You can create models that call the Mistral speech API using the .speech() factory method:

const model = mistral.speech('voxtral-mini-tts-3-0');

Use a preset or saved voice ID with generateSpeech:

import { mistral } from '@ai-sdk/mistral';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: mistral.speech('voxtral-mini-tts-3-0'),
  text: 'Hello from the AI SDK!',
  voice: 'gb_jane_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. Voxtral 3 style instructions are not available at launch. To control emotion and pace, include tags such as [emotion=happy] and [pace=slow] directly in text.

Voxtral 3 supports additional delivery controls through providerOptions.mistral:

• expressiveness number

  A value from 1 to 5 controlling expressiveness. Higher values trade voice similarity and stability for stronger delivery. Omit it to use the service default.

• phonemeHints Record<string, string[]>

  Map words in the input to lists of IPA phonemes. Mistral validates the supported phoneme inventory. See custom pronunciation.

import { mistral, type MistralSpeechModelOptions } from '@ai-sdk/mistral';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: mistral.speech('voxtral-mini-tts-3-0'),
  text: '[emotion=happy] I like tomato soup.',
  voice: 'gb_jane_neutral',
  providerOptions: {
    mistral: {
      expressiveness: 1.5,
      phonemeHints: { tomato: ['t', 'ə', 'm', 'ɑ', 't', 'oʊ'] },
    } satisfies MistralSpeechModelOptions,
  },
});

Mistral also supports one-off voice cloning with base64-encoded reference audio. Pass it through providerOptions.mistral.refAudio and use MistralSpeechModelOptions for type checking:

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-3-0'),
  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.

Model Capabilities

Embedding Models

You can create models that call the Mistral embeddings API using the .embedding() factory method.

const model = mistral.embedding('mistral-embed');

You can use Mistral embedding models to generate embeddings with the embed function:

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:

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