@ai-sdk/xai 4.0.37 → 4.0.39

package/docs/01-xai.mdx

@@ -59,10 +59,10 @@ You can use the following optional settings to customize the xAI provider instan
 ## Language Models
 
 You can create [xAI models](https://console.x.ai) using a provider instance. The
-first argument is the model id, e.g. `grok-4.20-non-reasoning`.
+first argument is the model id, e.g. `grok-4.6`.
 
 ```ts
-const model = xai('grok-4.20-non-reasoning');
+const model = xai('grok-4.6');
 ```
 
 <Note>
@@ -81,7 +81,7 @@ import { xai } from '@ai-sdk/xai';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
-  model: xai('grok-4.20-non-reasoning'),
+  model: xai('grok-4.6'),
   prompt: 'Write a vegetarian lasagna recipe for 4 people.',
 });
 ```
@@ -138,6 +138,37 @@ The AI SDK option accepts these values, but each xAI model supports a subset:
   current details.
 </Note>
 
+### Priority Processing
+
+`providerOptions.xai.serviceTier` requests higher scheduling priority, which
+typically lowers time-to-first-token and speeds up inter-token latency. This
+works for both the Responses API (default) and the Chat Completions API
+(`xai.chat()`).
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { generateText } from 'ai';
+
+const { providerMetadata } = await generateText({
+  model: xai('grok-4.6'),
+  prompt: 'Explain quantum entanglement.',
+  providerOptions: {
+    xai: { serviceTier: 'priority' },
+  },
+});
+
+// 'priority' when the request was served at the priority tier,
+// 'default' when priority capacity was unavailable.
+console.log(providerMetadata?.xai?.serviceTier);
+```
+
+Priority requests are billed at a premium per-token rate, and xAI only charges
+that rate when the response confirms the priority tier — so read the applied
+tier back from `providerMetadata.xai.serviceTier` rather than assuming the
+request you sent is the tier you got. Omitting the option is equivalent to
+`'default'`. See xAI's [priority processing
+docs](https://docs.x.ai/developers/advanced-api-usage/priority-processing).
+
 ## Realtime Models
 
 <Note type="warning">Realtime is an experimental feature.</Note>
@@ -168,7 +199,7 @@ calling pattern.
 The xAI Responses API is the default when using `xai(modelId)` (since AI SDK 7). You can also use `xai.responses(modelId)` explicitly. This enables the model to autonomously orchestrate tool calls and research on xAI's servers.
 
 ```ts
-const model = xai.responses('grok-4.20-non-reasoning');
+const model = xai.responses('grok-4.6');
 ```
 
 The Responses API provides server-side tools that the model can autonomously execute during its reasoning process:
@@ -190,7 +221,7 @@ import { xai } from '@ai-sdk/xai';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
-  model: xai.responses('grok-3'),
+  model: xai.responses('grok-4.6'),
   messages: [
     {
       role: 'user',
@@ -215,7 +246,7 @@ import { xai } from '@ai-sdk/xai';
 import { generateText } from 'ai';
 
 const { text } = await generateText({
-  model: xai('grok-4.3'),
+  model: xai('grok-4.6'),
   messages: [
     {
       role: 'user',
@@ -252,7 +283,7 @@ import { xai } from '@ai-sdk/xai';
 import { generateText } from 'ai';
 
 const { text, sources } = await generateText({
-  model: xai.responses('grok-4.20-non-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt: 'What are the latest developments in AI?',
   tools: {
     web_search: xai.tools.webSearch({
@@ -290,7 +321,7 @@ The X search tool enables searching X (Twitter) for posts, with filtering by han
 
 ```ts
 const { text, sources } = await generateText({
-  model: xai.responses('grok-4.20-non-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt: 'What are people saying about AI on X this week?',
   tools: {
     x_search: xai.tools.xSearch({
@@ -336,7 +367,7 @@ The code execution tool enables the model to write and execute Python code for c
 
 ```ts
 const { text } = await generateText({
-  model: xai.responses('grok-4.20-non-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt:
     'Calculate the compound interest for $10,000 at 5% annually for 10 years',
   tools: {
@@ -351,7 +382,7 @@ The view image tool enables the model to view and analyze images:
 
 ```ts
 const { text } = await generateText({
-  model: xai.responses('grok-4.20-non-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt: 'Describe what you see in the image',
   tools: {
     view_image: xai.tools.viewImage(),
@@ -365,7 +396,7 @@ The view X video tool enables the model to view and analyze videos from X (Twitt
 
 ```ts
 const { text } = await generateText({
-  model: xai.responses('grok-4.20-non-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt: 'Summarize the content of this X video',
   tools: {
     view_x_video: xai.tools.viewXVideo(),
@@ -382,7 +413,7 @@ import { xai } from '@ai-sdk/xai';
 import { generateText } from 'ai';
 
 const result = await generateText({
-  model: xai.responses('grok-4.5'),
+  model: xai.responses('grok-4.6'),
   prompt:
     'Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print',
   tools: {
@@ -420,7 +451,7 @@ The MCP server tool enables the model to connect to remote [Model Context Protoc
 
 ```ts
 const { text } = await generateText({
-  model: xai.responses('grok-4.20-non-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt: 'Use the weather tool to check conditions in San Francisco',
   tools: {
     weather_server: xai.tools.mcpServer({
@@ -468,7 +499,7 @@ import { xai, type XaiLanguageModelResponsesOptions } from '@ai-sdk/xai';
 import { streamText } from 'ai';
 
 const result = streamText({
-  model: xai.responses('grok-4.20-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt: 'What documents do you have access to?',
   tools: {
     file_search: xai.tools.fileSearch({
@@ -515,7 +546,7 @@ import { xai } from '@ai-sdk/xai';
 import { streamText } from 'ai';
 
 const { stream } = streamText({
-  model: xai.responses('grok-4.20-non-reasoning'),
+  model: xai.responses('grok-4.6'),
   prompt: 'Research AI safety developments and calculate risk metrics',
   tools: {
     web_search: xai.tools.webSearch(),
@@ -549,7 +580,7 @@ import { xai, type XaiLanguageModelResponsesOptions } from '@ai-sdk/xai';
 import { generateText } from 'ai';
 
 const result = await generateText({
-  model: xai.responses('grok-4.5'),
+  model: xai.responses('grok-4.6'),
   providerOptions: {
     xai: {
       reasoningEffort: 'high',
@@ -585,6 +616,10 @@ The following provider options are available:
 
   The ID of the previous response from the model. You can use it to continue a conversation.
 
+- **serviceTier** _'default' | 'priority'_
+
+  Scheduling priority for the request. `'priority'` buys lower time-to-first-token and faster inter-token latency at a premium per-token price. The tier xAI actually applied comes back on `providerMetadata.xai.serviceTier`, and is `'default'` when priority capacity was unavailable. See [Priority Processing](https://docs.x.ai/developers/advanced-api-usage/priority-processing).
+
 <Note>
   The Responses API only supports server-side tools. You cannot mix server-side
   tools with client-side function tools in the same request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "4.0.37",
+  "version": "4.0.39",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -37,8 +37,8 @@
     "tsup": "^8.5.1",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@vercel/ai-tsconfig": "0.0.0",
-    "@ai-sdk/test-server": "2.0.1"
+    "@ai-sdk/test-server": "2.0.1",
+    "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

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

@@ -287,6 +287,7 @@ export const xaiResponsesResponseSchema = z.object({
   output: z.array(outputItemSchema),
   usage: xaiResponsesUsageSchema.nullish(),
   status: z.string(),
+  service_tier: z.string().nullish(),
 });
 
 export const xaiResponsesChunkSchema = z.union([
@@ -571,6 +572,7 @@ export const xaiResponsesChunkSchema = z.union([
     response: z.object({
       incomplete_details: z.object({ reason: z.string() }).nullish(),
       usage: xaiResponsesUsageSchema.nullish(),
+      service_tier: z.string().nullish(),
     }),
   }),
   z.object({

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

@@ -28,6 +28,7 @@ export const xaiLanguageModelResponsesOptions = z.object({
   reasoningSummary: z.enum(['auto', 'concise', 'detailed']).optional(),
   logprobs: z.boolean().optional(),
   topLogprobs: z.number().int().min(0).max(8).optional(),
+  serviceTier: z.enum(['default', 'priority']).optional(),
   /**
    * Whether to store the input message(s) and model response for later retrieval.
    * Must be set to `false` for teams with Zero Data Retention (ZDR) enabled,

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

@@ -255,6 +255,9 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       ...(options.previousResponseId != null && {
         previous_response_id: options.previousResponseId,
       }),
+      ...(options.serviceTier != null && {
+        service_tier: options.serviceTier,
+      }),
     };
 
     if (xaiTools && xaiTools.length > 0) {
@@ -526,10 +529,16 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
             inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
             outputTokens: { total: 0, text: 0, reasoning: 0 },
           },
-      ...(response.usage?.cost_in_usd_ticks != null && {
+      ...((response.usage?.cost_in_usd_ticks != null ||
+        response.service_tier != null) && {
         providerMetadata: {
           xai: {
-            costInUsdTicks: response.usage.cost_in_usd_ticks,
+            ...(response.usage?.cost_in_usd_ticks != null && {
+              costInUsdTicks: response.usage.cost_in_usd_ticks,
+            }),
+            ...(response.service_tier != null && {
+              serviceTier: response.service_tier,
+            }),
           },
         },
       }),
@@ -580,6 +589,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
     let hasFunctionCall = false;
     let usage: LanguageModelV4Usage | undefined = undefined;
     let costInUsdTicks: number | undefined = undefined;
+    let serviceTier: string | undefined = undefined;
     let isFirstChunk = true;
     const contentBlocks: Record<string, { type: 'text' }> = {};
     const seenToolCalls = new Set<string>();
@@ -774,6 +784,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
                 costInUsdTicks = response.usage.cost_in_usd_ticks ?? undefined;
               }
 
+              serviceTier = response.service_tier ?? undefined;
+
               if (event.type === 'response.incomplete') {
                 const reason =
                   'incomplete_details' in response
@@ -1222,10 +1234,11 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
                 },
                 outputTokens: { total: 0, text: 0, reasoning: 0 },
               },
-              ...(costInUsdTicks != null && {
+              ...((costInUsdTicks != null || serviceTier != null) && {
                 providerMetadata: {
                   xai: {
-                    costInUsdTicks,
+                    ...(costInUsdTicks != null && { costInUsdTicks }),
+                    ...(serviceTier != null && { serviceTier }),
                   },
                 },
               }),

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

@@ -73,6 +73,8 @@ export const xaiLanguageModelChatOptions = z.object({
   logprobs: z.boolean().optional(),
   topLogprobs: z.number().int().min(0).max(8).optional(),
 
+  serviceTier: z.enum(['default', 'priority']).optional(),
+
   /**
    * Whether to enable parallel function calling during tool use.
    * When true, the model can call multiple functions in parallel.

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

@@ -181,6 +181,9 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
       seed,
       reasoning_effort: reasoningEffort,
 
+      // scheduling priority
+      service_tier: options.serviceTier,
+
       // parallel function calling
       parallel_function_calling: options.parallel_function_calling,
 
@@ -347,6 +350,11 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
             inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
             outputTokens: { total: 0, text: 0, reasoning: 0 },
           },
+      ...(response.service_tier != null && {
+        providerMetadata: {
+          xai: { serviceTier: response.service_tier },
+        },
+      }),
       request: { body },
       response: {
         ...getResponseMetadata(response),
@@ -426,6 +434,7 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
       raw: undefined,
     };
     let usage: LanguageModelV4Usage | undefined = undefined;
+    let serviceTier: string | undefined = undefined;
     let isFirstChunk = true;
     const contentBlocks: Record<
       string,
@@ -485,6 +494,11 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
               usage = convertXaiChatUsage(value.usage);
             }
 
+            // the applied tier is repeated on every chunk; keep the latest
+            if (value.service_tier != null) {
+              serviceTier = value.service_tier;
+            }
+
             const choice = value.choices[0];
 
             // update finish reason if present
@@ -644,6 +658,9 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
                 },
                 outputTokens: { total: 0, text: 0, reasoning: 0 },
               },
+              ...(serviceTier != null && {
+                providerMetadata: { xai: { serviceTier } },
+              }),
             });
           },
         }),
@@ -711,6 +728,7 @@ const xaiChatResponseSchema = z.object({
   object: z.literal('chat.completion').nullish(),
   usage: xaiUsageSchema.nullish(),
   citations: z.array(z.string().url()).nullish(),
+  service_tier: z.string().nullish(),
   code: z.string().nullish(),
   error: z.string().nullish(),
 });
@@ -744,6 +762,7 @@ const xaiChatChunkSchema = z.object({
   ),
   usage: xaiUsageSchema.nullish(),
   citations: z.array(z.string().url()).nullish(),
+  service_tier: z.string().nullish(),
 });
 
 const xaiStreamErrorSchema = z.object({

package/src/xai-video-model.ts

@@ -581,19 +581,30 @@ export class XaiVideoModel implements VideoModelV4 {
       statusResponse.status === 'done' ||
       (statusResponse.status == null && statusResponse.video?.url)
     ) {
+      // Terminal outcomes, so they are reported the same way as an upstream `failed`
       if (statusResponse.video?.respect_moderation === false) {
-        throw new AISDKError({
-          name: 'XAI_VIDEO_MODERATION_ERROR',
-          message:
+        return {
+          status: 'error' as const,
+          error:
             'Video generation was blocked due to a content policy violation.',
-        });
+          response: {
+            timestamp: currentDate,
+            modelId: this.modelId,
+            headers: responseHeaders,
+          },
+        };
       }
 
       if (!statusResponse.video?.url) {
-        throw new AISDKError({
-          name: 'XAI_VIDEO_GENERATION_ERROR',
-          message: 'Video generation completed but no video URL was returned.',
-        });
+        return {
+          status: 'error' as const,
+          error: 'Video generation completed but no video URL was returned.',
+          response: {
+            timestamp: currentDate,
+            modelId: this.modelId,
+            headers: responseHeaders,
+          },
+        };
       }
 
       return {