@ai-sdk/mistral 4.0.68 → 4.0.70

package/docs/20-mistral.mdx

@@ -1,6 +1,6 @@
 ---
 title: Mistral AI
-description: Learn how to use Mistral.
+description: Learn how to use Mistral AI with AI Gateway and the direct provider.
 ---
 
 # Mistral AI Provider
@@ -8,12 +8,56 @@ description: Learn how to use Mistral.
 The [Mistral AI](https://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](/providers/ai-sdk-providers/ai-gateway) (recommended) or connect directly with `@ai-sdk/mistral`.
 
-## Setup
+```ts provider="mistral" model="mistral/mistral-medium-3.5"
+import { generateText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const { text } = await generateText({
+  model: __MODEL__,
+  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`:
+
+<InstallPackages packages="ai" />
+
+Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment:
+
+```bash
+export AI_GATEWAY_API_KEY=your_api_key_here
+```
+
+Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments).
+See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models.
+
+Gateway feature and provider-option support depends on the model and the provider serving the request. See [Gateway provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options).
+
+## Using `@ai-sdk/mistral`
+
+For direct access to Mistral AI, install `ai` and `@ai-sdk/mistral`:
+
+<InstallPackages packages="ai @ai-sdk/mistral" />
+
+Set your Mistral AI API credential in the `MISTRAL_API_KEY` environment variable:
+
+```bash
+export MISTRAL_API_KEY=your_api_key_here
+```
 
-The Mistral provider is available in the `@ai-sdk/mistral` module. You can install it with
+AI Gateway does not expose every API in `@ai-sdk/mistral`. Use the direct provider for provider-specific APIs or custom connection settings.
 
-<InstallPackages packages="@ai-sdk/mistral" />
+<Note>
+  The following sections document the direct `@ai-sdk/mistral` provider,
+  including its model factories and settings. Gateway model and feature
+  availability can differ.
+</Note>
 
 ## Provider Instance
 
@@ -452,7 +496,7 @@ You can create models that call the
 using the `.transcription()` factory method:
 
 ```ts
-const model = mistral.transcription('voxtral-mini-latest');
+const model = mistral.transcription('voxtral-mini-transcribe-3-0');
 ```
 
 Use Mistral transcription models with [`transcribe`](/docs/reference/ai-sdk-core/transcribe):
@@ -463,7 +507,7 @@ import { transcribe } from 'ai';
 import { readFile } from 'node:fs/promises';
 
 const result = await transcribe({
-  model: mistral.transcription('voxtral-mini-latest'),
+  model: mistral.transcription('voxtral-mini-transcribe-3-0'),
   audio: await readFile('audio.mp3'),
 });
 ```
@@ -481,13 +525,14 @@ import { transcribe } from 'ai';
 import { readFile } from 'node:fs/promises';
 
 const result = await transcribe({
-  model: mistral.transcription('voxtral-mini-latest'),
+  model: mistral.transcription('voxtral-mini-transcribe-3-0'),
   audio: await readFile('audio.mp3'),
   providerOptions: {
     mistral: {
       timestampGranularities: ['segment'],
       diarize: true,
-      contextBias: ['Vercel', 'AI_SDK'],
+      returnLanguage: true,
+      contextBias: ['Vercel', 'AI SDK', 'A discussion about TypeScript.'],
     } satisfies MistralTranscriptionModelOptions,
   },
 });
@@ -499,25 +544,36 @@ The following optional provider options are available:
 
   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&lt;'segment' | 'word'&gt;_
 
-  Timestamp granularities to include in the response. Mistral does not support
-  combining this option with `language`; the SDK throws an
-  `InvalidArgumentError` when both are provided.
+  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.
+  Whether to identify speakers in the transcription. Voxtral 3 requires
+  `timestampGranularities: ['segment']` when this option is `true`.
 
 - **contextBias** _string[]_
 
-  Up to 100 words or phrases that guide spelling for names, technical terms,
-  or domain-specific vocabulary. Items cannot contain commas or whitespace;
-  use underscores for multi-word phrases.
+  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
@@ -533,9 +589,11 @@ speaker IDs from diarization are available under
 
 ### Model Capabilities
 
-| Model                 | Timestamps | Diarization | Context Bias |
-| --------------------- | ---------- | ----------- | ------------ |
-| `voxtral-mini-latest` | <Check />  | <Check />   | <Check />    |
+| Model                          | Timestamps | Diarization | Context Bias |
+| ------------------------------ | ---------- | ----------- | ------------ |
+| `voxtral-mini-transcribe-3-0`  | <Check />  | <Check />   | <Check />    |
+| `voxtral-small-transcribe-3-0` | <Check />  | <Check />   | <Check />    |
+| `voxtral-mini-latest`          | <Check />  | <Check />   | <Check />    |
 
 ## Speech Models
 
@@ -544,7 +602,7 @@ You can create models that call the
 the `.speech()` factory method:
 
 ```ts
-const model = mistral.speech('voxtral-mini-tts-2603');
+const model = mistral.speech('voxtral-mini-tts-3-0');
 ```
 
 Use a preset or saved voice ID with [`generateSpeech`](/docs/reference/ai-sdk-core/generate-speech):
@@ -554,9 +612,9 @@ import { mistral } from '@ai-sdk/mistral';
 import { generateSpeech } from 'ai';
 
 const result = await generateSpeech({
-  model: mistral.speech('voxtral-mini-tts-2603'),
+  model: mistral.speech('voxtral-mini-tts-3-0'),
   text: 'Hello from the AI SDK!',
-  voice: 'en_paul_neutral',
+  voice: 'gb_jane_neutral',
   outputFormat: 'mp3',
 });
 
@@ -566,7 +624,38 @@ 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.
+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&lt;string, string[]&gt;_
+
+  Map words in the input to lists of IPA phonemes. Mistral validates the supported
+  phoneme inventory. See [custom pronunciation](https://docs.mistral.ai/studio/audio/text-to-speech/custom-pronunciation).
+
+```ts
+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
@@ -580,7 +669,7 @@ import { generateSpeech } from 'ai';
 const referenceAudio = await readFile('./reference.mp3');
 
 const result = await generateSpeech({
-  model: mistral.speech('voxtral-mini-tts-2603'),
+  model: mistral.speech('voxtral-mini-tts-3-0'),
   text: 'Hello from the AI SDK!',
   providerOptions: {
     mistral: {
@@ -604,6 +693,7 @@ is redacted from request metadata and API call errors returned by the provider.
 
 | Model                   | Saved Voices | Reference Audio | Non-Streaming |
 | ----------------------- | ------------ | --------------- | ------------- |
+| `voxtral-mini-tts-3-0`  | <Check />    | <Check />       | <Check />     |
 | `voxtral-mini-tts-2603` | <Check />    | <Check />       | <Check />     |
 
 ## Embedding Models

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/mistral",
-  "version": "4.0.68",
+  "version": "4.0.70",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -29,8 +29,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.31",
-    "@ai-sdk/provider-utils": "5.0.64"
+    "@ai-sdk/provider": "4.0.32",
+    "@ai-sdk/provider-utils": "5.0.66"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.4",

package/src/mistral-chat-language-model-options.ts

@@ -1,3 +1,4 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
 // https://docs.mistral.ai/models
@@ -37,54 +38,58 @@ export type MistralChatModelId =
   | 'zai-glm-5-2'
   | (string & {});
 
-export const mistralLanguageModelChatOptions = z.object({
-  /**
-   * Whether to inject a safety prompt before all conversations.
-   *
-   * Defaults to `false`.
-   */
-  safePrompt: z.boolean().optional(),
+export const mistralLanguageModelChatOptions = () =>
+  z.object({
+    /**
+     * Whether to inject a safety prompt before all conversations.
+     *
+     * Defaults to `false`.
+     */
+    safePrompt: z.boolean().optional(),
 
-  documentImageLimit: z.number().optional(),
-  documentPageLimit: z.number().optional(),
+    documentImageLimit: z.number().optional(),
+    documentPageLimit: z.number().optional(),
 
-  /**
-   * Whether to use structured outputs.
-   *
-   * @default true
-   */
-  structuredOutputs: z.boolean().optional(),
+    /**
+     * Whether to use structured outputs.
+     *
+     * @default true
+     */
+    structuredOutputs: z.boolean().optional(),
 
-  /**
-   * Whether to use strict JSON schema validation.
-   *
-   * @default false
-   */
-  strictJsonSchema: z.boolean().optional(),
+    /**
+     * Whether to use strict JSON schema validation.
+     *
+     * @default false
+     */
+    strictJsonSchema: z.boolean().optional(),
 
-  /**
-   * Whether to enable parallel function calling during tool use.
-   * When set to false, the model will use at most one tool per response.
-   *
-   * @default true
-   */
-  parallelToolCalls: z.boolean().optional(),
+    /**
+     * Whether to enable parallel function calling during tool use.
+     * When set to false, the model will use at most one tool per response.
+     *
+     * @default true
+     */
+    parallelToolCalls: z.boolean().optional(),
 
-  /**
-   * A stable identifier used to route requests with shared prompt prefixes to
-   * the same cache.
-   */
-  promptCacheKey: z.string().optional(),
+    /**
+     * A stable identifier used to route requests with shared prompt prefixes to
+     * the same cache.
+     */
+    promptCacheKey: z.string().optional(),
 
-  /**
-   * Controls the reasoning effort for models that support adjustable reasoning.
-   *
-   * - `'high'`: Enable reasoning
-   * - `'none'`: Disable reasoning
-   */
-  reasoningEffort: z.enum(['high', 'none']).optional(),
-});
+    /**
+     * Controls the reasoning effort for models that support adjustable reasoning.
+     *
+     * - `'high'`: Enable reasoning
+     * - `'none'`: Disable reasoning
+     */
+    reasoningEffort: z.enum(['high', 'none']).optional(),
+  });
+export const mistralLanguageModelChatOptionsValidator = lazySchema(() =>
+  zodSchema(mistralLanguageModelChatOptions()),
+);
 
 export type MistralLanguageModelChatOptions = z.infer<
-  typeof mistralLanguageModelChatOptions
+  ReturnType<typeof mistralLanguageModelChatOptions>
 >;

package/src/mistral-chat-language-model.ts

@@ -9,6 +9,9 @@ import type {
   SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
   combineHeaders,
   createEventSourceResponseHandler,
   createJsonResponseHandler,
@@ -36,7 +39,7 @@ import { convertToMistralChatMessages } from './convert-to-mistral-chat-messages
 import { getResponseMetadata } from './get-response-metadata';
 import { mapMistralFinishReason } from './map-mistral-finish-reason';
 import {
-  mistralLanguageModelChatOptions,
+  mistralLanguageModelChatOptionsValidator,
   type MistralChatModelId,
 } from './mistral-chat-language-model-options';
 import { mistralFailedResponseHandler } from './mistral-error';
@@ -127,7 +130,7 @@ export class MistralChatLanguageModel implements LanguageModelV4 {
       (await parseProviderOptions({
         provider: 'mistral',
         providerOptions,
-        schema: mistralLanguageModelChatOptions,
+        schema: mistralLanguageModelChatOptionsValidator,
       })) ?? {};
 
     if (topK != null) {
@@ -349,8 +352,9 @@ export class MistralChatLanguageModel implements LanguageModelV4 {
       fetch: this.config.fetch,
     });
 
+    // A clean end without the provider's completion signal is interrupted.
     let finishReason: LanguageModelV4FinishReason = {
-      unified: 'other',
+      unified: 'interrupted',
       raw: undefined,
     };
     let usage: MistralUsage | undefined = undefined;
@@ -365,7 +369,7 @@ export class MistralChatLanguageModel implements LanguageModelV4 {
     return {
       stream: response.pipeThrough(
         new TransformStream<
-          ParseResult<z.infer<typeof mistralChatChunkSchema>>,
+          ParseResult<InferSchema<typeof mistralChatChunkSchema>>,
           LanguageModelV4StreamPart
         >({
           start(controller) {
@@ -382,6 +386,7 @@ export class MistralChatLanguageModel implements LanguageModelV4 {
             }
 
             if (!chunk.success) {
+              finishReason = { unified: 'error', raw: undefined };
               controller.enqueue({ type: 'error', error: chunk.error });
               return;
             }
@@ -505,7 +510,9 @@ function extractReasoningContent(
     .join('');
 }
 
-function extractTextContent(content: z.infer<typeof mistralContentSchema>) {
+function extractTextContent(
+  content: z.infer<ReturnType<typeof mistralContentSchema>>,
+) {
   if (typeof content === 'string') {
     return content;
   }
@@ -538,98 +545,110 @@ function extractTextContent(content: z.infer<typeof mistralContentSchema>) {
   return textContent.length ? textContent.join('') : undefined;
 }
 
-const mistralContentSchema = z
-  .union([
-    z.string(),
-    z.array(
-      z.discriminatedUnion('type', [
-        z.object({
-          type: z.literal('text'),
-          text: z.string(),
-        }),
-        z.object({
-          type: z.literal('image_url'),
-          image_url: z.union([
-            z.string(),
-            z.object({
-              url: z.string(),
-              detail: z.string().nullable(),
-            }),
-          ]),
-        }),
-        z.object({
-          type: z.literal('reference'),
-          reference_ids: z.array(z.union([z.string(), z.number()])),
-        }),
-        z.object({
-          type: z.literal('thinking'),
-          thinking: z.array(
-            z.object({
-              type: z.literal('text'),
-              text: z.string(),
-            }),
-          ),
-        }),
-      ]),
-    ),
-  ])
-  .nullish();
+const mistralContentSchema = () =>
+  z
+    .union([
+      z.string(),
+      z.array(
+        z.discriminatedUnion('type', [
+          z.object({
+            type: z.literal('text'),
+            text: z.string(),
+          }),
+          z.object({
+            type: z.literal('image_url'),
+            image_url: z.union([
+              z.string(),
+              z.object({
+                url: z.string(),
+                detail: z.string().nullable(),
+              }),
+            ]),
+          }),
+          z.object({
+            type: z.literal('reference'),
+            reference_ids: z.array(z.union([z.string(), z.number()])),
+          }),
+          z.object({
+            type: z.literal('thinking'),
+            thinking: z.array(
+              z.object({
+                type: z.literal('text'),
+                text: z.string(),
+              }),
+            ),
+          }),
+        ]),
+      ),
+    ])
+    .nullish();
 
 // limited version of the schema, focussed on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency
-const mistralChatResponseSchema = z.object({
-  id: z.string().nullish(),
-  created: z.number().nullish(),
-  model: z.string().nullish(),
-  choices: z.array(
+const mistralChatResponseSchema = lazySchema(() =>
+  zodSchema(
     z.object({
-      message: z.object({
-        role: z.literal('assistant'),
-        content: mistralContentSchema,
-        tool_calls: z
-          .array(
-            z.object({
-              id: z.string(),
-              function: z.object({ name: z.string(), arguments: z.string() }),
-            }),
-          )
-          .nullish(),
-      }),
-      index: z.number(),
-      finish_reason: z.string().nullish(),
+      id: z.string().nullish(),
+      created: z.number().nullish(),
+      model: z.string().nullish(),
+      choices: z.array(
+        z.object({
+          message: z.object({
+            role: z.literal('assistant'),
+            content: mistralContentSchema(),
+            tool_calls: z
+              .array(
+                z.object({
+                  id: z.string(),
+                  function: z.object({
+                    name: z.string(),
+                    arguments: z.string(),
+                  }),
+                }),
+              )
+              .nullish(),
+          }),
+          index: z.number(),
+          finish_reason: z.string().nullish(),
+        }),
+      ),
+      object: z.literal('chat.completion'),
+      usage: mistralUsageSchema,
     }),
   ),
-  object: z.literal('chat.completion'),
-  usage: mistralUsageSchema,
-});
+);
 
 // limited version of the schema, focussed on what is needed for the implementation
 // this approach limits breakages when the API changes and increases efficiency
-const mistralChatChunkSchema = z.object({
-  id: z.string().nullish(),
-  created: z.number().nullish(),
-  model: z.string().nullish(),
-  choices: z.array(
+const mistralChatChunkSchema = lazySchema(() =>
+  zodSchema(
     z.object({
-      delta: z.object({
-        role: z.enum(['assistant']).optional(),
-        content: mistralContentSchema,
-        tool_calls: z
-          .array(
-            z.object({
-              index: z.number().nullish(),
-              id: z.string().nullish(),
-              function: z.object({
-                name: z.string().nullish(),
-                arguments: z.string().nullish(),
-              }),
-            }),
-          )
-          .nullish(),
-      }),
-      finish_reason: z.string().nullish(),
-      index: z.number(),
+      id: z.string().nullish(),
+      created: z.number().nullish(),
+      model: z.string().nullish(),
+      choices: z.array(
+        z.object({
+          delta: z.object({
+            role: z.enum(['assistant']).optional(),
+            content: mistralContentSchema(),
+            tool_calls: z
+              .array(
+                z.object({
+                  index: z.number().nullish(),
+                  id: z.string().nullish(),
+                  function: z.object({
+                    name: z.string().nullish(),
+                    arguments: z.string().nullish(),
+                  }),
+                }),
+              )
+              .nullish(),
+          }),
+          finish_reason: z.string().nullish(),
+          index: z.number(),
+        }),
+      ),
+      usage: mistralUsageSchema.nullish(),
     }),
   ),
-  usage: mistralUsageSchema.nullish(),
-});
+);

package/src/mistral-conversation-language-model-options.ts

@@ -1,3 +1,4 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
 import {
   mistralLanguageModelChatOptions,
   type MistralChatModelId,
@@ -6,8 +7,9 @@ import {
 
 export type MistralConversationModelId = MistralChatModelId;
 
-export const mistralLanguageModelConversationOptions =
-  mistralLanguageModelChatOptions;
+export const mistralLanguageModelConversationOptions = lazySchema(() =>
+  zodSchema(mistralLanguageModelChatOptions()),
+);
 
 export type MistralLanguageModelConversationOptions =
   MistralLanguageModelChatOptions;