@ai-sdk/xai 4.0.36 → 4.0.38

package/docs/01-xai.mdx

@@ -121,19 +121,54 @@ The AI SDK option accepts these values, but each xAI model supports a subset:
 - `'high'` — More reasoning tokens for deeper thinking. Suited for very
   challenging problems, complex math, multi-step logic, and competition-level
   tasks.
+- `'xhigh'` — Uses the most reasoning tokens for the most challenging tasks.
+  This level is only supported by `grok-4.6`.
 
 <Note>
   Support and defaults are model-specific. `grok-4.3` supports `'none'`,
   `'low'`, `'medium'`, and `'high'`. `grok-4.5` supports `'low'`, `'medium'`,
-  and `'high'`, defaults to `'high'`, and cannot disable reasoning. The
-  `grok-4.20-reasoning` and `grok-4.20-non-reasoning` variants do not accept
-  this option. For `grok-4.20-multi-agent`, `'low'`, `'medium'`, and `'high'`
-  control the number of agents instead of reasoning depth. See xAI's [reasoning
+  and `'high'`, defaults to `'high'`, and cannot disable reasoning. `grok-4.6`
+  supports `'low'`, `'medium'`, `'high'`, and `'xhigh'`, and defaults to
+  `'high'`. The `grok-4.20-reasoning` and `grok-4.20-non-reasoning` variants do
+  not accept this option. For `grok-4.20-multi-agent`, `'low'`, `'medium'`, and
+  `'high'` control the number of agents instead of reasoning depth. See xAI's
+  [reasoning
   docs](https://docs.x.ai/developers/model-capabilities/text/reasoning) and
-  [Grok 4.3 model page](https://docs.x.ai/developers/models/grok-4.3) for
+  [Grok 4.6 model page](https://docs.x.ai/developers/models/grok-4.6) for
   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>
@@ -581,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.
@@ -590,6 +629,7 @@ The following provider options are available:
 
 | Model                         | Image Input | Object Generation | Tool Usage | Tool Streaming | Reasoning |
 | ----------------------------- | ----------- | ----------------- | ---------- | -------------- | --------- |
+| `grok-4.6`                    | <Check />   | <Check />         | <Check />  | <Check />      | <Check /> |
 | `grok-4.5`                    | <Check />   | <Check />         | <Check />  | <Check />      | <Check /> |
 | `grok-4.20-reasoning`         | <Check />   | <Check />         | <Check />  | <Check />      | <Check /> |
 | `grok-4.20-non-reasoning`     | <Check />   | <Check />         | <Check />  | <Check />      | <Cross /> |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "4.0.36",
+  "version": "4.0.38",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -29,8 +29,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.7",
-    "@ai-sdk/provider-utils": "5.0.27"
+    "@ai-sdk/provider-utils": "5.0.27",
+    "@ai-sdk/provider": "4.0.7"
   },
   "devDependencies": {
     "@types/node": "22.19.19",

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

@@ -5,6 +5,7 @@ export type XaiResponsesModelId =
   | 'grok-4.20-reasoning'
   | 'grok-4.3'
   | 'grok-4.5'
+  | 'grok-4.6'
   | 'grok-latest'
   | (string & {});
 
@@ -16,14 +17,18 @@ export const xaiLanguageModelResponsesOptions = z.object({
    * Constrains how hard a reasoning model thinks before responding.
    * Possible values are `none` (disables reasoning entirely; supported by
    * `grok-4.3` and newer reasoning models), `low` (uses fewer reasoning
-   * tokens), `medium`, and `high` (uses more reasoning tokens).
+   * tokens), `medium`, `high` (uses more reasoning tokens), and `xhigh`
+   * (supported by `grok-4.6`).
    *
    * @see https://docs.x.ai/docs/guides/reasoning
    */
-  reasoningEffort: z.enum(['none', 'low', 'medium', 'high']).optional(),
+  reasoningEffort: z
+    .enum(['none', 'low', 'medium', 'high', 'xhigh'])
+    .optional(),
   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

@@ -202,7 +202,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
             low: 'low',
             medium: 'medium',
             high: 'high',
-            xhigh: 'high',
+            xhigh: this.modelId === 'grok-4.6' ? 'xhigh' : 'high',
           },
           warnings,
         });
@@ -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

@@ -6,6 +6,7 @@ export type XaiChatModelId =
   | 'grok-4.20-reasoning'
   | 'grok-4.3'
   | 'grok-4.5'
+  | 'grok-4.6'
   | 'grok-latest'
   | (string & {});
 
@@ -59,16 +60,21 @@ export const xaiLanguageModelChatOptions = z.object({
    * - `low` (default): Uses some reasoning tokens, but still fast.
    * - `medium`: More thinking for less-latency-sensitive applications.
    * - `high`: Uses more reasoning tokens for deeper thinking.
+   * - `xhigh`: Uses the most reasoning tokens (supported by `grok-4.6`).
    *
    * Note: Not every Grok model accepts every value. Refer to xAI's docs for
    * the values supported by your selected model.
    *
    * @see https://docs.x.ai/docs/guides/reasoning
    */
-  reasoningEffort: z.enum(['none', 'low', 'medium', 'high']).optional(),
+  reasoningEffort: z
+    .enum(['none', 'low', 'medium', 'high', 'xhigh'])
+    .optional(),
   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

@@ -158,7 +158,7 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
             low: 'low',
             medium: 'medium',
             high: 'high',
-            xhigh: 'high',
+            xhigh: this.modelId === 'grok-4.6' ? 'xhigh' : 'high',
           },
           warnings,
         });
@@ -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({