@ai-sdk/xai 3.0.104 → 3.0.105

package/docs/01-xai.mdx

@@ -184,6 +184,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": "3.0.104",
+  "version": "3.0.105",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "2.0.58",
-    "@ai-sdk/provider": "3.0.13",
-    "@ai-sdk/provider-utils": "4.0.37"
+    "@ai-sdk/provider-utils": "4.0.37",
+    "@ai-sdk/provider": "3.0.13"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

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

@@ -3,13 +3,16 @@ import {
   type SharedV3Warning,
   type LanguageModelV3Prompt,
 } from '@ai-sdk/provider';
-import { convertToBase64 } from '@ai-sdk/provider-utils';
-import type { XaiChatPrompt } from './xai-chat-prompt';
+import { convertToBase64, parseProviderOptions } from '@ai-sdk/provider-utils';
+import type { XaiChatPrompt, XaiUserMessageContent } from './xai-chat-prompt';
+import { xaiFilePartProviderOptions } from './xai-file-part-options';
 
-export function convertToXaiChatMessages(prompt: LanguageModelV3Prompt): {
+export async function convertToXaiChatMessages(
+  prompt: LanguageModelV3Prompt,
+): Promise<{
   messages: XaiChatPrompt;
   warnings: Array<SharedV3Warning>;
-} {
+}> {
   const messages: XaiChatPrompt = [];
   const warnings: Array<SharedV3Warning> = [];
 
@@ -26,38 +29,48 @@ export function convertToXaiChatMessages(prompt: LanguageModelV3Prompt): {
           break;
         }
 
-        messages.push({
-          role: 'user',
-          content: content.map(part => {
-            switch (part.type) {
-              case 'text': {
-                return { type: 'text', text: part.text };
-              }
-              case 'file': {
-                if (part.mediaType.startsWith('image/')) {
-                  const mediaType =
-                    part.mediaType === 'image/*'
-                      ? 'image/jpeg'
-                      : part.mediaType;
-
-                  return {
-                    type: 'image_url',
-                    image_url: {
-                      url:
-                        part.data instanceof URL
-                          ? part.data.toString()
-                          : `data:${mediaType};base64,${convertToBase64(part.data)}`,
-                    },
-                  };
-                } else {
-                  throw new UnsupportedFunctionalityError({
-                    functionality: `file part media type ${part.mediaType}`,
-                  });
-                }
+        const userContent: Array<XaiUserMessageContent> = [];
+
+        for (const part of content) {
+          switch (part.type) {
+            case 'text': {
+              userContent.push({ type: 'text', text: part.text });
+              break;
+            }
+            case 'file': {
+              if (part.mediaType.startsWith('image/')) {
+                const mediaType =
+                  part.mediaType === 'image/*' ? 'image/jpeg' : part.mediaType;
+
+                const filePartOptions = await parseProviderOptions({
+                  provider: 'xai',
+                  providerOptions: part.providerOptions,
+                  schema: xaiFilePartProviderOptions,
+                });
+
+                userContent.push({
+                  type: 'image_url',
+                  image_url: {
+                    url:
+                      part.data instanceof URL
+                        ? part.data.toString()
+                        : `data:${mediaType};base64,${convertToBase64(part.data)}`,
+                    ...(filePartOptions?.imageDetail != null && {
+                      detail: filePartOptions.imageDetail,
+                    }),
+                  },
+                });
+              } else {
+                throw new UnsupportedFunctionalityError({
+                  functionality: `file part media type ${part.mediaType}`,
+                });
               }
+              break;
             }
-          }),
-        });
+          }
+        }
+
+        messages.push({ role: 'user', content: userContent });
 
         break;
       }

package/src/index.ts

@@ -4,6 +4,7 @@ export type {
   XaiLanguageModelChatOptions as XaiProviderOptions,
 } from './xai-chat-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

@@ -3,7 +3,8 @@ import {
   type SharedV3Warning,
   type LanguageModelV3Message,
 } from '@ai-sdk/provider';
-import { convertToBase64 } from '@ai-sdk/provider-utils';
+import { convertToBase64, parseProviderOptions } from '@ai-sdk/provider-utils';
+import { xaiFilePartProviderOptions } from '../xai-file-part-options';
 import type {
   XaiResponsesInput,
   XaiResponsesUserMessageContentPart,
@@ -53,7 +54,19 @@ export async function convertToXaiResponsesInput({
                     ? block.data.toString()
                     : `data:${mediaType};base64,${convertToBase64(block.data)}`;
 
-                contentParts.push({ type: 'input_image', image_url: imageUrl });
+                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 instanceof URL) {
                 // xAI's Responses API accepts non-image documents (PDF, text, CSV, etc.)
                 // via `{ type: 'input_file', file_url }`. See

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_url: string };
 
 export type XaiResponsesUserMessage = {

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

@@ -105,7 +105,7 @@ export class XaiChatLanguageModel implements LanguageModelV3 {
 
     // convert ai sdk messages to xai format
     const { messages, warnings: messageWarnings } =
-      convertToXaiChatMessages(prompt);
+      await convertToXaiChatMessages(prompt);
     warnings.push(...messageWarnings);
 
     // prepare tools for xai

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' };
+    };
 
 export interface XaiAssistantMessage {
   role: 'assistant';

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
+>;