@ai-sdk/mistral 4.0.68 → 4.0.69

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`:
 
-The Mistral provider is available in the `@ai-sdk/mistral` module. You can install it with
+<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
+```
 
-<InstallPackages packages="@ai-sdk/mistral" />
+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
+```
+
+AI Gateway does not expose every API in `@ai-sdk/mistral`. Use the direct provider for provider-specific APIs or custom connection settings.
+
+<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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/mistral",
-  "version": "4.0.68",
+  "version": "4.0.69",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.31",
-    "@ai-sdk/provider-utils": "5.0.64"
+    "@ai-sdk/provider-utils": "5.0.65"
   },
   "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) {
@@ -365,7 +368,7 @@ export class MistralChatLanguageModel implements LanguageModelV4 {
     return {
       stream: response.pipeThrough(
         new TransformStream<
-          ParseResult<z.infer<typeof mistralChatChunkSchema>>,
+          ParseResult<InferSchema<typeof mistralChatChunkSchema>>,
           LanguageModelV4StreamPart
         >({
           start(controller) {
@@ -505,7 +508,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 +543,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;