@ai-sdk/xai 4.0.7 → 4.0.9

package/docs/01-xai.mdx

@@ -212,6 +212,42 @@ const { text } = await generateText({
 });
 ```
 
+You can control the resolution at which the model processes an image with
+the `imageDetail` provider option on the image part:
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: xai('grok-4.3'),
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What do you see in this image?' },
+        {
+          type: 'file',
+          mediaType: 'image/png',
+          data: fs.readFileSync('./image.png'),
+          providerOptions: {
+            xai: { imageDetail: 'low' },
+          },
+        },
+      ],
+    },
+  ],
+});
+```
+
+The following image detail values are supported:
+
+- **low**: processes the image at reduced resolution and consumes fewer input tokens.
+- **high**: processes the image at full resolution.
+- **auto**: lets the xAI API decide.
+
+When not set, the image is processed at full resolution.
+
 ### Web Search Tool
 
 The web search tool enables autonomous web research with optional domain filtering and image understanding:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "4.0.7",
+  "version": "4.0.9",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -29,17 +29,17 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "3.0.5",
+    "@ai-sdk/openai-compatible": "3.0.6",
     "@ai-sdk/provider": "4.0.2",
-    "@ai-sdk/provider-utils": "5.0.5"
+    "@ai-sdk/provider-utils": "5.0.6"
   },
   "devDependencies": {
     "@types/node": "22.19.19",
     "tsup": "^8.5.1",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.0",
-    "@vercel/ai-tsconfig": "0.0.0"
+    "@vercel/ai-tsconfig": "0.0.0",
+    "@ai-sdk/test-server": "2.0.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

package/src/convert-to-xai-chat-messages.ts

@@ -6,15 +6,19 @@ import {
 import {
   convertToBase64,
   getTopLevelMediaType,
+  parseProviderOptions,
   resolveFullMediaType,
   resolveProviderReference,
 } from '@ai-sdk/provider-utils';
-import type { XaiChatPrompt } from './xai-chat-prompt';
+import type { XaiChatPrompt, XaiUserMessageContent } from './xai-chat-prompt';
+import { xaiFilePartProviderOptions } from './xai-file-part-options';
 
-export function convertToXaiChatMessages(prompt: LanguageModelV4Prompt): {
+export async function convertToXaiChatMessages(
+  prompt: LanguageModelV4Prompt,
+): Promise<{
   messages: XaiChatPrompt;
   warnings: Array<SharedV4Warning>;
-} {
+}> {
   const messages: XaiChatPrompt = [];
   const warnings: Array<SharedV4Warning> = [];
 
@@ -31,54 +35,68 @@ export function convertToXaiChatMessages(prompt: LanguageModelV4Prompt): {
           break;
         }
 
-        messages.push({
-          role: 'user',
-          content: content.map(part => {
-            switch (part.type) {
-              case 'text': {
-                return { type: 'text', text: part.text };
-              }
-              case 'file': {
-                switch (part.data.type) {
-                  case 'reference': {
-                    return {
-                      type: 'file',
-                      file: {
-                        file_id: resolveProviderReference({
-                          reference: part.data.reference,
-                          provider: 'xai',
+        const userContent: Array<XaiUserMessageContent> = [];
+
+        for (const part of content) {
+          switch (part.type) {
+            case 'text': {
+              userContent.push({ type: 'text', text: part.text });
+              break;
+            }
+            case 'file': {
+              switch (part.data.type) {
+                case 'reference': {
+                  userContent.push({
+                    type: 'file',
+                    file: {
+                      file_id: resolveProviderReference({
+                        reference: part.data.reference,
+                        provider: 'xai',
+                      }),
+                    },
+                  });
+                  break;
+                }
+                case 'text': {
+                  throw new UnsupportedFunctionalityError({
+                    functionality: 'text file parts',
+                  });
+                }
+                case 'url':
+                case 'data': {
+                  if (getTopLevelMediaType(part.mediaType) === 'image') {
+                    const filePartOptions = await parseProviderOptions({
+                      provider: 'xai',
+                      providerOptions: part.providerOptions,
+                      schema: xaiFilePartProviderOptions,
+                    });
+
+                    userContent.push({
+                      type: 'image_url',
+                      image_url: {
+                        url:
+                          part.data.type === 'url'
+                            ? part.data.url.toString()
+                            : `data:${resolveFullMediaType({ part })};base64,${convertToBase64(part.data.data)}`,
+                        ...(filePartOptions?.imageDetail != null && {
+                          detail: filePartOptions.imageDetail,
                         }),
                       },
-                    };
-                  }
-                  case 'text': {
+                    });
+                  } else {
                     throw new UnsupportedFunctionalityError({
-                      functionality: 'text file parts',
+                      functionality: `file part media type ${part.mediaType}`,
                     });
                   }
-                  case 'url':
-                  case 'data': {
-                    if (getTopLevelMediaType(part.mediaType) === 'image') {
-                      return {
-                        type: 'image_url',
-                        image_url: {
-                          url:
-                            part.data.type === 'url'
-                              ? part.data.url.toString()
-                              : `data:${resolveFullMediaType({ part })};base64,${convertToBase64(part.data.data)}`,
-                        },
-                      };
-                    } else {
-                      throw new UnsupportedFunctionalityError({
-                        functionality: `file part media type ${part.mediaType}`,
-                      });
-                    }
-                  }
+                  break;
                 }
               }
+              break;
             }
-          }),
-        });
+          }
+        }
+
+        messages.push({ role: 'user', content: userContent });
 
         break;
       }

package/src/index.ts

@@ -4,6 +4,7 @@ export type {
   XaiLanguageModelChatOptions as XaiProviderOptions,
 } from './xai-chat-language-model-options';
 export type { XaiErrorData } from './xai-error';
+export type { XaiFilePartProviderOptions } from './xai-file-part-options';
 export type {
   XaiLanguageModelResponsesOptions,
   /** @deprecated Use `XaiLanguageModelResponsesOptions` instead. */

package/src/responses/convert-to-xai-responses-input.ts

@@ -6,9 +6,11 @@ import {
 import {
   convertToBase64,
   getTopLevelMediaType,
+  parseProviderOptions,
   resolveFullMediaType,
   resolveProviderReference,
 } from '@ai-sdk/provider-utils';
+import { xaiFilePartProviderOptions } from '../xai-file-part-options';
 import type {
   XaiResponsesInput,
   XaiResponsesUserMessageContentPart,
@@ -71,9 +73,18 @@ export async function convertToXaiResponsesInput({
                         ? block.data.url.toString()
                         : `data:${resolveFullMediaType({ part: block })};base64,${convertToBase64(block.data.data)}`;
 
+                    const filePartOptions = await parseProviderOptions({
+                      provider: 'xai',
+                      providerOptions: block.providerOptions,
+                      schema: xaiFilePartProviderOptions,
+                    });
+
                     contentParts.push({
                       type: 'input_image',
                       image_url: imageUrl,
+                      ...(filePartOptions?.imageDetail != null && {
+                        detail: filePartOptions.imageDetail,
+                      }),
                     });
                   } else if (block.data.type === 'url') {
                     // xAI's Responses API accepts non-image documents (PDF, text, CSV, etc.)

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

@@ -26,7 +26,11 @@ export type XaiResponsesSystemMessage = {
 
 export type XaiResponsesUserMessageContentPart =
   | { type: 'input_text'; text: string }
-  | { type: 'input_image'; image_url: string }
+  | {
+      type: 'input_image';
+      image_url: string;
+      detail?: 'low' | 'high' | 'auto';
+    }
   | { type: 'input_file'; file_id: string }
   | { type: 'input_file'; file_url: string };
 

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

@@ -25,6 +25,7 @@ import {
 } from '@ai-sdk/provider-utils';
 import type { z } from 'zod/v4';
 import { getResponseMetadata } from '../get-response-metadata';
+import { supportsReasoningEffort } from '../supports-reasoning-effort';
 import { xaiFailedResponseHandler } from '../xai-error';
 import { convertToXaiResponsesInput } from './convert-to-xai-responses-input';
 import { convertXaiResponsesUsage } from './convert-xai-responses-usage';
@@ -164,23 +165,30 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       }
     }
 
-    const resolvedReasoningEffort =
-      options.reasoningEffort ??
-      (isCustomReasoning(reasoning)
-        ? reasoning === 'none'
-          ? undefined
-          : mapReasoningToProviderEffort({
-              reasoning,
-              effortMap: {
-                minimal: 'low',
-                low: 'low',
-                medium: 'medium',
-                high: 'high',
-                xhigh: 'high',
-              },
-              warnings,
-            })
-        : undefined);
+    let resolvedReasoningEffort = options.reasoningEffort;
+    if (resolvedReasoningEffort == null && isCustomReasoning(reasoning)) {
+      if (!supportsReasoningEffort(this.modelId)) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'reasoning',
+          details: `reasoning "${reasoning}" is not supported by this model.`,
+        });
+      } else if (reasoning === 'none') {
+        resolvedReasoningEffort = 'none';
+      } else {
+        resolvedReasoningEffort = mapReasoningToProviderEffort({
+          reasoning,
+          effortMap: {
+            minimal: 'low',
+            low: 'low',
+            medium: 'medium',
+            high: 'high',
+            xhigh: 'high',
+          },
+          warnings,
+        });
+      }
+    }
 
     const baseArgs: Record<string, unknown> = {
       model: this.modelId,

package/src/supports-reasoning-effort.ts

@@ -0,0 +1,12 @@
+/**
+ * The grok-4.20 reasoning and non-reasoning models (including dated variants
+ * such as `grok-4.20-0309-reasoning`) reject the reasoning effort parameter
+ * with an invalid-argument error for every value, including `none`.
+ * Other models such as `grok-4.3`, `grok-latest`, and
+ * `grok-4.20-multi-agent` accept it.
+ */
+const modelsWithoutReasoningEffort = /^grok-4\.20(-\d{4})?-(non-)?reasoning$/;
+
+export function supportsReasoningEffort(modelId: string): boolean {
+  return !modelsWithoutReasoningEffort.test(modelId);
+}

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

@@ -31,6 +31,7 @@ import { convertToXaiChatMessages } from './convert-to-xai-chat-messages';
 import { convertXaiChatUsage } from './convert-xai-chat-usage';
 import { getResponseMetadata } from './get-response-metadata';
 import { mapXaiFinishReason } from './map-xai-finish-reason';
+import { supportsReasoningEffort } from './supports-reasoning-effort';
 import {
   xaiLanguageModelChatOptions,
   type XaiChatModelId,
@@ -125,7 +126,7 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
 
     // convert ai sdk messages to xai format
     const { messages, warnings: messageWarnings } =
-      convertToXaiChatMessages(prompt);
+      await convertToXaiChatMessages(prompt);
     warnings.push(...messageWarnings);
 
     // prepare tools for xai
@@ -139,6 +140,31 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
     });
     warnings.push(...toolWarnings);
 
+    let reasoningEffort = options.reasoningEffort;
+    if (reasoningEffort == null && isCustomReasoning(reasoning)) {
+      if (!supportsReasoningEffort(this.modelId)) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'reasoning',
+          details: `reasoning "${reasoning}" is not supported by this model.`,
+        });
+      } else if (reasoning === 'none') {
+        reasoningEffort = 'none';
+      } else {
+        reasoningEffort = mapReasoningToProviderEffort({
+          reasoning,
+          effortMap: {
+            minimal: 'low',
+            low: 'low',
+            medium: 'medium',
+            high: 'high',
+            xhigh: 'high',
+          },
+          warnings,
+        });
+      }
+    }
+
     const baseArgs = {
       // model id
       model: this.modelId,
@@ -153,23 +179,7 @@ export class XaiChatLanguageModel implements LanguageModelV4 {
       temperature,
       top_p: topP,
       seed,
-      reasoning_effort:
-        options.reasoningEffort ??
-        (isCustomReasoning(reasoning)
-          ? reasoning === 'none'
-            ? undefined
-            : mapReasoningToProviderEffort({
-                reasoning,
-                effortMap: {
-                  minimal: 'low',
-                  low: 'low',
-                  medium: 'medium',
-                  high: 'high',
-                  xhigh: 'high',
-                },
-                warnings,
-              })
-          : undefined),
+      reasoning_effort: reasoningEffort,
 
       // parallel function calling
       parallel_function_calling: options.parallel_function_calling,

package/src/xai-chat-prompt.ts

@@ -18,7 +18,10 @@ export interface XaiUserMessage {
 
 export type XaiUserMessageContent =
   | { type: 'text'; text: string }
-  | { type: 'image_url'; image_url: { url: string } }
+  | {
+      type: 'image_url';
+      image_url: { url: string; detail?: 'low' | 'high' | 'auto' };
+    }
   | { type: 'file'; file: { file_id: string } };
 
 export interface XaiAssistantMessage {

package/src/xai-file-part-options.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod/v4';
+
+// provider options for file parts (images) in user messages
+export const xaiFilePartProviderOptions = z.object({
+  /**
+   * Controls the resolution at which the model processes the image.
+   * `low` processes the image at reduced resolution and consumes fewer
+   * input tokens, `high` processes the image at full resolution, and
+   * `auto` lets the API decide. Defaults to full resolution when not set.
+   *
+   * Note: the xAI API silently ignores invalid values, so the value is
+   * validated client-side.
+   *
+   * @see https://docs.x.ai/developers/model-capabilities/images/understanding
+   */
+  imageDetail: z.enum(['low', 'high', 'auto']).optional(),
+});
+
+export type XaiFilePartProviderOptions = z.infer<
+  typeof xaiFilePartProviderOptions
+>;