@ai-sdk/xai 5.0.7 → 5.0.10

package/docs/01-xai.mdx

@@ -588,15 +588,39 @@ The following provider options are available:
 
 - **logprobs** _boolean_
 
-  Return log probabilities for output tokens.
+  Return log probabilities for output tokens. This is silently ignored by `grok-4.20` and newer models.
 
 - **topLogprobs** _number_
 
-  Number of most likely tokens to return per token position (0-8). When set, `logprobs` is automatically enabled.
+  Number of most likely tokens to return per token position (0-8). When set, `logprobs` is automatically enabled. This is silently ignored by `grok-4.20` and newer models.
 
-- **include** _Array<'file_search_call.results'>_
+- **minP** _number_
+
+  Set the min-p sampling threshold between 0 and 1. Tokens whose probability is below `minP` times the most likely token's probability are excluded. Unlike the standard AI SDK `topK` option, `minP` is xAI-specific and must be set in `providerOptions.xai`.
+
+- **maxTurns** _number_
+
+  Set the maximum number of assistant/server-side tool turns xAI may perform within one API request. This limits xAI's internal loop for provider-executed tools such as web search; it is separate from AI SDK's `stopWhen`, which limits the outer loop of AI SDK steps and API requests.
+
+- **parallelToolCalls** _boolean_
+
+  Allow the model to call tools in parallel. Defaults to `true`.
+
+- **promptCacheKey** _string_
+
+  Route requests with shared prompt prefixes to improve cache reuse.
+
+- **safetyIdentifier** _string_
+
+  Provide a stable, preferably hashed end-user identifier for safety monitoring.
 
-  Specify additional output data to include in the model response. Use `['file_search_call.results']` to include file search results with scores and content.
+- **user** _string_
+
+  Provide an end-user identifier for abuse monitoring.
+
+- **include** _Array<'file_search_call.results' | 'web_search_call.action.sources' | 'code_interpreter_call.outputs' | 'reasoning.encrypted_content' | 'no_inline_citations'>_
+
+  Include file-search results, web-search sources, code-interpreter outputs, or encrypted reasoning content, or disable inline citations.
 
 - **store** _boolean_
 
@@ -1062,7 +1086,7 @@ import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
 import { experimental_generateVideo as generateVideo } from 'ai';
 
 const { video } = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt: 'A chicken flying into the sunset in the style of 90s anime.',
   aspectRatio: '16:9',
   duration: 5,
@@ -1084,7 +1108,7 @@ import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
 import { experimental_generateVideo as generateVideo } from 'ai';
 
 const { video } = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt: {
     image: 'https://example.com/start-frame.png',
     text: 'The cat slowly turns its head and blinks',
@@ -1106,7 +1130,7 @@ import { experimental_generateVideo as generateVideo } from 'ai';
 import fs from 'node:fs';
 
 const { video } = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt: 'The cat slowly turns its head and blinks',
   frameImages: [
     {
@@ -1124,9 +1148,9 @@ const { video } = await generateVideo({
 ```
 
 <Note>
-  xAI does not support first-last-frame interpolation. A `last_frame` entry in
-  `frameImages` is ignored with a warning — use the `extend-video` mode to
-  continue from a video's last frame instead.
+  `grok-imagine-video-1.5` supports first-last-frame interpolation. Earlier
+  models ignore a `last_frame` entry with a warning. Use `extend-video` when you
+  want to continue an existing video rather than pin its final frame.
 </Note>
 
 ### Video Editing
@@ -1138,7 +1162,7 @@ import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
 import { experimental_generateVideo as generateVideo } from 'ai';
 
 const { video } = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt: 'Give the person sunglasses and a hat',
   providerOptions: {
     xai: {
@@ -1176,7 +1200,7 @@ const providerOptions = {
 
 // Step 1: Apply an initial edit
 const step1 = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt: 'Add a party hat to the person',
   providerOptions,
 });
@@ -1187,7 +1211,7 @@ const step1VideoUrl = step1.providerMetadata?.xai?.videoUrl as string;
 // Step 2: Apply two more edits concurrently, building on step 1
 const [withSunglasses, withScarf] = await Promise.all([
   generateVideo({
-    model: xai.video('grok-imagine-video'),
+    model: xai.video('grok-imagine-video-1.5'),
     prompt: 'Add sunglasses',
     providerOptions: {
       xai: {
@@ -1198,7 +1222,7 @@ const [withSunglasses, withScarf] = await Promise.all([
     },
   }),
   generateVideo({
-    model: xai.video('grok-imagine-video'),
+    model: xai.video('grok-imagine-video-1.5'),
     prompt: 'Add a scarf',
     providerOptions: {
       xai: {
@@ -1221,7 +1245,7 @@ import { experimental_generateVideo as generateVideo } from 'ai';
 
 // Step 1: Generate a source video
 const source = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt: 'A cat sitting on a sunlit windowsill, tail gently swishing.',
   duration: 5,
   aspectRatio: '16:9',
@@ -1236,7 +1260,7 @@ const sourceUrl = source.providerMetadata?.xai?.videoUrl as string;
 
 // Step 2: Extend the video with a new scene
 const extended = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt: 'The cat turns its head, notices a butterfly, and leaps off.',
   duration: 6,
   providerOptions: {
@@ -1264,7 +1288,7 @@ import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
 import { experimental_generateVideo as generateVideo } from 'ai';
 
 const { video } = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt:
     'The comic cat from <IMAGE_1> and the comic dog from <IMAGE_2> ' +
     'are having a playful chase through a sunlit park. ' +
@@ -1294,7 +1318,7 @@ import { experimental_generateVideo as generateVideo } from 'ai';
 import fs from 'node:fs';
 
 const { video } = await generateVideo({
-  model: xai.video('grok-imagine-video'),
+  model: xai.video('grok-imagine-video-1.5'),
   prompt:
     'The comic cat and the comic dog are having a playful chase ' +
     'through a sunlit park. Cinematic slow-motion, warm afternoon light.',
@@ -1312,17 +1336,17 @@ const { video } = await generateVideo({
 });
 ```
 
-`inputReferences` accepts image references only. A reference with a non-image
-media type (for example a video or audio clip) is ignored with a warning, and a
-reference with no media type is treated as an image. If no image reference
-remains, reference-to-video is not selected and no reference images are sent.
+`inputReferences` accepts image and audio references. Audio references must
+declare an audio media type and can be supplied alone or together with images;
+they are sent through `reference_audios`. A reference with no media type is
+treated as an image. Video references are ignored with a warning.
 
 #### Reference Audio
 
-Reference-to-video can also give the subject a voice. `referenceVoiceIds` takes
-up to 3 xAI **preset** voice ids — you cannot upload your own audio clips.
-Reference the voices from the prompt with `<AUDIO_0>`, `<AUDIO_1>`, and
-`<AUDIO_2>`, in the order the voices are passed.
+Reference-to-video can also give the subject a voice. Use `inputReferences` for
+caller-supplied audio clips, or `referenceVoiceIds` for up to 3 xAI preset voice
+ids. Reference them from the prompt with `<AUDIO_0>`, `<AUDIO_1>`, and
+`<AUDIO_2>`, in the order they are passed.
 
 ```ts
 import { xai, type XaiVideoModelOptions } from '@ai-sdk/xai';
@@ -1357,19 +1381,18 @@ available voices. `referenceVoiceIds` is ignored with a warning when the
 resolved operation is not reference-to-video.
 
 <Note>
-  xAI documents reference audio as available in the United States only, for
-  trusted partners. Requests from accounts without access are rejected by the
-  xAI API.
+  Preset voices are generally available. Caller-supplied voice clips are
+  available to trusted partners on request. xAI accepts at most three audio
+  references per request.
 </Note>
 
 <Note>
   Reference-to-video supports `duration`, `aspectRatio`, and `resolution`. Use
-  `mode` to select the operation — each mode is mutually exclusive. When both
-  are provided, `frameImages` takes precedence over `inputReferences`, and
+  `mode` to select the operation — each mode is mutually exclusive.
   `inputReferences` takes precedence over the legacy `referenceImageUrls`
-  provider option. Reference-to-video is supported by the `grok-imagine-video`
-  and `grok-imagine-video-1.5` models; native 1080p requires
-  `grok-imagine-video-1.5`.
+  provider option and can be combined with pinned frames. Reference-to-video is
+  supported by the `grok-imagine-video` and `grok-imagine-video-1.5` models;
+  native 1080p requires `grok-imagine-video-1.5`.
 </Note>
 
 ### Video Provider Options
@@ -1435,6 +1458,42 @@ You can validate the provider options using the `XaiVideoModelOptions` type.
   Ignored with a warning outside reference-to-video. Reference audio is
   documented as US-only and limited to trusted partners.
 
+- **storageOptions** _object_
+
+  Stores the generated video in the xAI Files API. Set `filename` and
+  optionally `expiresAfter` (up to 30 days) and `publicUrl`. Stored-file
+  details and storage errors are returned in `providerMetadata.xai.fileOutput`
+  and `providerMetadata.xai.storageError`.
+
+- **keyframes** _Array\<\{ imageUrl: string; timestampSeconds: number \}\>_
+
+  Up to four mid-video image anchors. Each timestamp must fall strictly inside
+  the video duration. Keyframes are supported by `grok-imagine-video-1.5` and
+  are ignored with a warning for editing and extension operations.
+
+### Audio and Frame Controls
+
+Use the provider-neutral `generateAudio` option to request or disable generated
+audio. Use `frameImages` for exact endpoint frames:
+
+```ts
+const { video } = await generateVideo({
+  model: xai.video('grok-imagine-video-1.5'),
+  prompt: 'A paper boat drifting down a rain-soaked street',
+  generateAudio: false,
+  frameImages: [
+    {
+      frameType: 'last_frame',
+      image: 'https://example.com/final-frame.png',
+    },
+  ],
+});
+```
+
+`last_frame` is supported only by `grok-imagine-video-1.5`. The provider emits
+an unsupported-feature warning and omits the field for other model IDs. A
+`first_frame` is sent as xAI's standard `image` input.
+
 <Note>
   Video generation is an asynchronous process that can take several minutes.
   Consider setting `pollTimeoutMs` to at least 10 minutes (600000ms) for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "5.0.7",
+  "version": "5.0.10",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,10 +30,10 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.18",
-    "@ai-sdk/provider-utils": "5.0.47"
+    "@ai-sdk/provider-utils": "5.0.49"
   },
   "devDependencies": {
-    "@ai-sdk/test-server": "2.0.1",
+    "@ai-sdk/test-server": "2.0.2",
     "@types/node": "22.19.19",
     "@vercel/ai-tsconfig": "0.0.0",
     "tsup": "^8.5.1",

package/src/responses/xai-responses-api.ts

@@ -2,7 +2,10 @@ import { z } from 'zod/v4';
 
 export type XaiResponsesIncludeValue =
   | 'file_search_call.results'
-  | 'reasoning.encrypted_content';
+  | 'web_search_call.action.sources'
+  | 'code_interpreter_call.outputs'
+  | 'reasoning.encrypted_content'
+  | 'no_inline_citations';
 
 export type XaiResponsesIncludeOptions =
   | Array<XaiResponsesIncludeValue>
@@ -317,6 +320,8 @@ export const xaiResponsesResponseSchema = z.object({
   usage: xaiResponsesUsageSchema.nullish(),
   status: z.string(),
   service_tier: z.string().nullish(),
+  prompt_cache_key: z.string().nullish(),
+  safety_identifier: z.string().nullish(),
 });
 
 export const xaiResponsesChunkSchema = z.union([
@@ -602,6 +607,8 @@ export const xaiResponsesChunkSchema = z.union([
       incomplete_details: z.object({ reason: z.string() }).nullish(),
       usage: xaiResponsesUsageSchema.nullish(),
       service_tier: z.string().nullish(),
+      prompt_cache_key: z.string().nullish(),
+      safety_identifier: z.string().nullish(),
     }),
   }),
   z.object({

package/src/responses/xai-responses-language-model-options.ts

@@ -26,9 +26,23 @@ export const xaiLanguageModelResponsesOptions = z.object({
   reasoningEffort: z
     .enum(['none', 'low', 'medium', 'high', 'xhigh'])
     .optional(),
+  /**
+   * @deprecated xAI ignores the requested summary level and always returns a
+   * detailed reasoning summary.
+   */
   reasoningSummary: z.enum(['auto', 'concise', 'detailed']).optional(),
   logprobs: z.boolean().optional(),
   topLogprobs: z.number().int().min(0).max(8).optional(),
+  /** Min-p sampling threshold between 0 and 1. */
+  minP: z.number().min(0).max(1).optional(),
+  /** Maximum number of agentic tool-calling turns. */
+  maxTurns: z.number().int().optional(),
+  /** Whether the model may call tools in parallel. @default true */
+  parallelToolCalls: z.boolean().optional(),
+  /** Cache key used to route requests with shared prompt prefixes. */
+  promptCacheKey: z.string().optional(),
+  /** Stable identifier used to attribute policy violations to an end user. */
+  safetyIdentifier: z.string().optional(),
   serviceTier: z.enum(['default', 'priority']).optional(),
   /**
    * Whether to store the input message(s) and model response for later retrieval.
@@ -41,11 +55,23 @@ export const xaiLanguageModelResponsesOptions = z.object({
    * The ID of the previous response from the model.
    */
   previousResponseId: z.string().optional(),
+  /** A unique identifier for the end user, used for abuse monitoring. */
+  user: z.string().optional(),
   /**
    * Specify additional output data to include in the model response.
    * Example values: 'file_search_call.results'.
    */
-  include: z.array(z.enum(['file_search_call.results'])).nullish(),
+  include: z
+    .array(
+      z.enum([
+        'file_search_call.results',
+        'web_search_call.action.sources',
+        'code_interpreter_call.outputs',
+        'reasoning.encrypted_content',
+        'no_inline_citations',
+      ]),
+    )
+    .nullish(),
 });
 
 export type XaiLanguageModelResponsesOptions = z.infer<

package/src/responses/xai-responses-language-model.ts

@@ -211,10 +211,6 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
         schema: xaiLanguageModelResponsesOptions,
       })) ?? {};
 
-    if (topK != null) {
-      warnings.push({ type: 'unsupported', feature: 'topK' });
-    }
-
     if (frequencyPenalty != null) {
       warnings.push({ type: 'unsupported', feature: 'frequencyPenalty' });
     }
@@ -318,6 +314,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       max_output_tokens: maxOutputTokens,
       temperature,
       top_p: topP,
+      top_k: topK,
+      min_p: options.minP,
       seed,
       ...(responseFormat?.type === 'json' && {
         text: {
@@ -333,15 +331,9 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
               : { type: 'json_object' },
         },
       }),
-      ...((resolvedReasoningEffort != null ||
-        options.reasoningSummary != null) && {
+      ...(resolvedReasoningEffort != null && {
         reasoning: {
-          ...(resolvedReasoningEffort != null && {
-            effort: resolvedReasoningEffort,
-          }),
-          ...(options.reasoningSummary != null && {
-            summary: options.reasoningSummary,
-          }),
+          effort: resolvedReasoningEffort,
         },
       }),
       ...(options.store === false && {
@@ -353,9 +345,24 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       ...(options.previousResponseId != null && {
         previous_response_id: options.previousResponseId,
       }),
+      ...(options.maxTurns != null && {
+        max_turns: options.maxTurns,
+      }),
+      ...(options.parallelToolCalls != null && {
+        parallel_tool_calls: options.parallelToolCalls,
+      }),
+      ...(options.promptCacheKey != null && {
+        prompt_cache_key: options.promptCacheKey,
+      }),
+      ...(options.safetyIdentifier != null && {
+        safety_identifier: options.safetyIdentifier,
+      }),
       ...(options.serviceTier != null && {
         service_tier: options.serviceTier,
       }),
+      ...(options.user != null && {
+        user: options.user,
+      }),
     };
 
     if (xaiTools && xaiTools.length > 0) {
@@ -644,7 +651,9 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
             outputTokens: { total: 0, text: 0, reasoning: 0 },
           },
       ...((response.usage?.cost_in_usd_ticks != null ||
-        response.service_tier != null) && {
+        response.service_tier != null ||
+        response.prompt_cache_key != null ||
+        response.safety_identifier != null) && {
         providerMetadata: {
           xai: {
             ...(response.usage?.cost_in_usd_ticks != null && {
@@ -653,6 +662,12 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
             ...(response.service_tier != null && {
               serviceTier: response.service_tier,
             }),
+            ...(response.prompt_cache_key != null && {
+              promptCacheKey: response.prompt_cache_key,
+            }),
+            ...(response.safety_identifier != null && {
+              safetyIdentifier: response.safety_identifier,
+            }),
           },
         },
       }),
@@ -704,6 +719,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
     let usage: LanguageModelV4Usage | undefined = undefined;
     let costInUsdTicks: number | undefined = undefined;
     let serviceTier: string | undefined = undefined;
+    let promptCacheKey: string | undefined = undefined;
+    let safetyIdentifier: string | undefined = undefined;
     let isFirstChunk = true;
     const contentBlocks: Record<string, { type: 'text' }> = {};
     const seenToolCalls = new Set<string>();
@@ -899,6 +916,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
               }
 
               serviceTier = response.service_tier ?? undefined;
+              promptCacheKey = response.prompt_cache_key ?? undefined;
+              safetyIdentifier = response.safety_identifier ?? undefined;
 
               if (event.type === 'response.incomplete') {
                 const reason =
@@ -1371,11 +1390,16 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
                 },
                 outputTokens: { total: 0, text: 0, reasoning: 0 },
               },
-              ...((costInUsdTicks != null || serviceTier != null) && {
+              ...((costInUsdTicks != null ||
+                serviceTier != null ||
+                promptCacheKey != null ||
+                safetyIdentifier != null) && {
                 providerMetadata: {
                   xai: {
                     ...(costInUsdTicks != null && { costInUsdTicks }),
                     ...(serviceTier != null && { serviceTier }),
+                    ...(promptCacheKey != null && { promptCacheKey }),
+                    ...(safetyIdentifier != null && { safetyIdentifier }),
                   },
                 },
               }),

package/src/xai-video-model-options.ts

@@ -8,10 +8,33 @@ const modeSchema = z.enum(['edit-video', 'extend-video', 'reference-to-video']);
 export type XaiVideoMode = z.infer<typeof modeSchema>;
 type XaiVideoResolution = z.infer<typeof resolutionSchema>;
 
+const keyframeSchema = z.object({
+  imageUrl: nonEmptyStringSchema,
+  timestampSeconds: z.number().positive(),
+});
+
+const storageOptionsSchema = z.object({
+  filename: nonEmptyStringSchema,
+  expiresAfter: z.number().int().positive().max(2_592_000).optional(),
+  publicUrl: z
+    .union([
+      z.boolean(),
+      z.object({
+        expiresAfter: z.number().int().min(3_600).max(2_592_000).optional(),
+      }),
+    ])
+    .optional(),
+});
+
+export type XaiVideoKeyframe = z.infer<typeof keyframeSchema>;
+export type XaiVideoStorageOptions = z.infer<typeof storageOptionsSchema>;
+
 interface XaiVideoSharedOptions {
   pollIntervalMs?: number | null;
   pollTimeoutMs?: number | null;
   resolution?: XaiVideoResolution | null;
+  /** Store the generated video in the xAI Files API. */
+  storageOptions?: XaiVideoStorageOptions;
 }
 
 interface XaiVideoUserOptions {
@@ -59,6 +82,8 @@ interface XaiVideoGenerationOptions
   mode?: undefined;
   videoUrl?: undefined;
   referenceImageUrls?: undefined;
+  /** Mid-video image anchors (up to 4). */
+  keyframes?: XaiVideoKeyframe[];
 }
 
 interface XaiLegacyEditVideoOptions
@@ -119,6 +144,8 @@ const runtimeSchema = z.looseObject({
   videoUrl: nonEmptyStringSchema.optional(),
   referenceImageUrls: z.array(nonEmptyStringSchema).min(1).max(7).optional(),
   referenceVoiceIds: z.array(nonEmptyStringSchema).max(3).optional(),
+  keyframes: z.array(keyframeSchema).max(4).optional(),
+  storageOptions: storageOptionsSchema.optional(),
   user: z.string().optional(),
   ...baseFields,
 });