@ai-sdk/xai 4.0.9 → 4.0.12

package/docs/01-xai.mdx

@@ -12,21 +12,7 @@ The [xAI Grok](https://x.ai) provider contains language model support for the [x
 The xAI Grok provider is available via the `@ai-sdk/xai` module. You can
 install it with
 
-<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
-  <Tab>
-    <Snippet text="pnpm add @ai-sdk/xai" dark />
-  </Tab>
-  <Tab>
-    <Snippet text="npm install @ai-sdk/xai" dark />
-  </Tab>
-  <Tab>
-    <Snippet text="yarn add @ai-sdk/xai" dark />
-  </Tab>
-
-  <Tab>
-    <Snippet text="bun add @ai-sdk/xai" dark />
-  </Tab>
-</Tabs>
+<InstallPackages packages="@ai-sdk/xai" />
 
 ## Provider Instance
 
@@ -556,18 +542,19 @@ The following provider options are available:
 
 ## Model Capabilities
 
-| Model                         | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      | Reasoning           |
-| ----------------------------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
-| `grok-4.20-reasoning`         | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
-| `grok-4.20-non-reasoning`     | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
-| `grok-4-1-fast-reasoning`     | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
-| `grok-4-1-fast-non-reasoning` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
-| `grok-4-1`                    | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
-| `grok-4-fast-reasoning`       | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
-| `grok-4-fast-non-reasoning`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
-| `grok-code-fast-1`            | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
-| `grok-3`                      | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
-| `grok-3-mini`                 | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| Model                         | Image Input | Object Generation | Tool Usage | Tool Streaming | Reasoning |
+| ----------------------------- | ----------- | ----------------- | ---------- | -------------- | --------- |
+| `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 /> |
+| `grok-4-1-fast-reasoning`     | <Check />   | <Check />         | <Check />  | <Check />      | <Check /> |
+| `grok-4-1-fast-non-reasoning` | <Check />   | <Check />         | <Check />  | <Check />      | <Cross /> |
+| `grok-4-1`                    | <Cross />   | <Check />         | <Check />  | <Check />      | <Cross /> |
+| `grok-4-fast-reasoning`       | <Check />   | <Check />         | <Check />  | <Check />      | <Check /> |
+| `grok-4-fast-non-reasoning`   | <Check />   | <Check />         | <Check />  | <Check />      | <Cross /> |
+| `grok-code-fast-1`            | <Cross />   | <Check />         | <Check />  | <Check />      | <Check /> |
+| `grok-3`                      | <Cross />   | <Check />         | <Check />  | <Check />      | <Cross /> |
+| `grok-3-mini`                 | <Cross />   | <Check />         | <Check />  | <Check />      | <Check /> |
 
 <Note>
   The table above lists popular models. Please see the [xAI
@@ -675,9 +662,9 @@ const result = await generateSpeech({
 
 ### Model Capabilities
 
-| Model     | Language            | Speed               | Output Formats             |
-| --------- | ------------------- | ------------------- | -------------------------- |
-| `default` | <Check size={18} /> | <Check size={18} /> | mp3, wav, pcm, mulaw, alaw |
+| Model     | Language  | Speed     | Output Formats             |
+| --------- | --------- | --------- | -------------------------- |
+| `default` | <Check /> | <Check /> | mp3, wav, pcm, mulaw, alaw |
 
 ## Transcription Models
 
@@ -782,9 +769,9 @@ const result = await transcribe({
 
 ### Model Capabilities
 
-| Model     | Request/Response    | Streaming           | Word Timestamps     | Diarization         | Multichannel        |
-| --------- | ------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
-| `default` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| Model     | Request/Response | Streaming | Word Timestamps | Diarization | Multichannel |
+| --------- | ---------------- | --------- | --------------- | ----------- | ------------ |
+| `default` | <Check />        | <Check /> | <Check />       | <Check />   | <Check />    |
 
 <Note>
   Word timestamps, diarization results, and segments are only returned on the
@@ -919,10 +906,10 @@ const { images } = await generateImage({
 
 ### Image Model Capabilities
 
-| Model                    | Resolution | Aspect Ratios                                                                                               | Image Editing       |
-| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------- | ------------------- |
-| `grok-imagine-image-pro` | `1k`, `2k` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto` | <Check size={18} /> |
-| `grok-imagine-image`     | `1k`       | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto` | <Check size={18} /> |
+| Model                    | Resolution | Aspect Ratios                                                                                               | Image Editing |
+| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------- | ------------- |
+| `grok-imagine-image-pro` | `1k`, `2k` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto` | <Check />     |
+| `grok-imagine-image`     | `1k`       | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto` | <Check />     |
 
 ## Video Models
 
@@ -1268,9 +1255,9 @@ and `resolution` just like text-to-video.
 
 ### Video Model Capabilities
 
-| Model                | Duration | Aspect Ratios                                     | Resolution     | Image-to-Video      | Editing             | Extension           | R2V                 |
-| -------------------- | -------- | ------------------------------------------------- | -------------- | ------------------- | ------------------- | ------------------- | ------------------- |
-| `grok-imagine-video` | 1–15s    | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` | `480p`, `720p` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| Model                | Duration | Aspect Ratios                                     | Resolution     | Image-to-Video | Editing   | Extension | R2V       |
+| -------------------- | -------- | ------------------------------------------------- | -------------- | -------------- | --------- | --------- | --------- |
+| `grok-imagine-video` | 1–15s    | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` | `480p`, `720p` | <Check />      | <Check /> | <Check /> | <Check /> |
 
 <Note>
   You can also pass any available provider model ID as a string if needed.

package/package.json

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

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

@@ -4,6 +4,7 @@ export type XaiResponsesModelId =
   | 'grok-4.20-non-reasoning'
   | 'grok-4.20-reasoning'
   | 'grok-4.3'
+  | 'grok-4.5'
   | 'grok-latest'
   | (string & {});
 

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

@@ -5,6 +5,7 @@ export type XaiChatModelId =
   | 'grok-4.20-non-reasoning'
   | 'grok-4.20-reasoning'
   | 'grok-4.3'
+  | 'grok-4.5'
   | 'grok-latest'
   | (string & {});
 

package/src/xai-image-model.ts

@@ -201,6 +201,9 @@ export class XaiImageModel implements ImageModelV4 {
   ): Promise<Uint8Array> {
     const { value } = await getFromApi({
       url,
+      // url is a generated-image URL from the provider response; validate it.
+      validateUrl: true,
+      trustedOrigin: this.config.baseURL,
       abortSignal,
       failedResponseHandler: createStatusCodeErrorResponseHandler(),
       successfulResponseHandler: createBinaryResponseHandler(),

package/src/xai-transcription-model.ts

@@ -8,18 +8,20 @@ import {
   combineHeaders,
   convertBase64ToUint8Array,
   createJsonResponseHandler,
-  getWebSocketConstructor,
+  connectToWebSocket,
   mediaTypeToExtension,
   parseProviderOptions,
   postFormDataToApi,
-  readWebSocketMessageText,
   safeParseJSON,
   serializeModelOptions,
   toWebSocketUrl,
+  waitForWebSocketBufferDrain,
   WORKFLOW_DESERIALIZE,
   WORKFLOW_SERIALIZE,
   type FetchFunction,
+  type WebSocketConnection,
   type WebSocketConstructor,
+  type WebSocketLike,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import { xaiFailedResponseHandler } from './xai-error';
@@ -273,20 +275,26 @@ function createXaiStreamingTranscriptionStream({
 
   return new ReadableStream({
     start: controller => {
-      const WebSocketConstructor = getWebSocketConstructor(webSocket);
-      const ws = new WebSocketConstructor(url, undefined, { headers });
       const doneTexts = new Map<number, string>();
+      // per-channel finalized utterances + latest revisable text, used to
+      // reconstruct the finish text (xAI's `transcript.done` has empty text):
+      const finalizedTexts = new Map<number, string[]>();
+      const pendingTexts = new Map<number, string>();
       let doneDuration: number | undefined;
       let audioReader:
         | ReadableStreamDefaultReader<Uint8Array | string>
         | undefined;
+      let connection: WebSocketConnection | undefined;
 
       cleanup = (closeCode?: number) => {
-        abortSignal?.removeEventListener('abort', abort);
-        void audioReader?.cancel().catch(() => {});
-        try {
-          ws.close(closeCode);
-        } catch {}
+        if (audioReader != null) {
+          void audioReader.cancel().catch(() => {});
+        } else {
+          // pre-open failure or abort: cancel the caller's audio stream so an
+          // upstream producer piping into it does not hang:
+          void audio.cancel().catch(() => {});
+        }
+        connection?.close(closeCode);
       };
 
       const finishWithError = (error: unknown) => {
@@ -314,117 +322,138 @@ function createXaiStreamingTranscriptionStream({
         cleanup(1000);
       };
 
-      const abort = () => {
-        finishWithError(abortSignal?.reason ?? new Error('Aborted'));
-      };
-      if (abortSignal?.aborted) {
-        abort();
-        return;
-      }
-      abortSignal?.addEventListener('abort', abort, { once: true });
-
-      const sendAudio = async () => {
+      const sendAudio = async (socket: WebSocketLike) => {
         audioReader = audio.getReader();
         try {
           while (true) {
             const { done, value } = await audioReader.read();
             if (done || finished) break;
-            ws.send(
+            socket.send(
               value instanceof Uint8Array
                 ? value
                 : convertBase64ToUint8Array(value),
             );
+            // backpressure: pause reads while the socket buffer is full
+            await waitForWebSocketBufferDrain(socket);
           }
         } finally {
           audioReader.releaseLock();
+          // unlocked again: cleanup must cancel `audio`, not the reader
+          audioReader = undefined;
         }
         if (!finished) {
-          ws.send(JSON.stringify({ type: 'audio.done' }));
+          socket.send(JSON.stringify({ type: 'audio.done' }));
         }
       };
 
-      ws.onmessage = event => {
-        void readWebSocketMessageText(event.data)
-          .then(async text => {
-            const parsed = await safeParseJSON({ text });
-            if (!parsed.success) return;
-            const raw = parsed.value as XaiStreamingTranscriptionEvent;
-
-            if (includeRawChunks) {
-              controller.enqueue({ type: 'raw', rawValue: raw });
-            }
+      connection = connectToWebSocket({
+        url,
+        headers,
+        webSocket,
+        abortSignal,
+        onAbort: finishWithError,
+        onProcessingError: finishWithError,
+        onMessageText: async text => {
+          const parsed = await safeParseJSON({ text });
+          if (!parsed.success) return;
+          const raw = parsed.value as XaiStreamingTranscriptionEvent;
+
+          if (includeRawChunks) {
+            controller.enqueue({ type: 'raw', rawValue: raw });
+          }
 
-            switch (raw.type) {
-              case 'transcript.created': {
-                controller.enqueue({ type: 'stream-start', warnings });
-                void sendAudio().catch(finishWithError);
+          switch (raw.type) {
+            case 'transcript.created': {
+              controller.enqueue({ type: 'stream-start', warnings });
+              const socket = connection?.socket;
+              if (socket == null) {
+                finishWithError(new Error('WebSocket is not connected.'));
                 break;
               }
+              void sendAudio(socket).catch(finishWithError);
+              break;
+            }
 
-              case 'transcript.partial': {
-                const id = channelId(raw.channel_index);
+            case 'transcript.partial': {
+              const id = channelId(raw.channel_index);
+              const channelIndex = raw.channel_index ?? 0;
+              // only `speech_final` completes an utterance; `is_final`
+              // fragments are re-sent/revised later, so they stay partials:
+              if (raw.is_final && raw.speech_final) {
                 const timing = timingFromXaiEvent(raw);
-                if (raw.is_final) {
-                  controller.enqueue({
-                    type: 'transcript-final',
-                    id,
-                    text: raw.text ?? '',
-                    ...timing,
-                    channelIndex: raw.channel_index,
-                  });
-                } else {
-                  controller.enqueue({
-                    type: 'transcript-partial',
-                    id,
-                    text: raw.text ?? '',
-                    startSecond: raw.start,
-                    durationInSeconds: raw.duration,
-                    channelIndex: raw.channel_index,
-                  });
+                if (raw.text) {
+                  finalizedTexts.set(channelIndex, [
+                    ...(finalizedTexts.get(channelIndex) ?? []),
+                    raw.text,
+                  ]);
                 }
-                break;
-              }
-
-              case 'transcript.done': {
-                const channelIndex = raw.channel_index ?? 0;
-                doneTexts.set(channelIndex, raw.text ?? '');
-                doneDuration = raw.duration ?? doneDuration;
-                maybeFinish();
-                break;
-              }
-
-              case 'error': {
-                // xAI STT errors are terminal: surface the server message
-                // instead of letting the socket close mask it.
-                finishWithError(new Error(raw.message ?? 'xAI STT error'));
-                break;
+                pendingTexts.delete(channelIndex);
+                controller.enqueue({
+                  type: 'transcript-final',
+                  id,
+                  text: raw.text ?? '',
+                  ...timing,
+                  channelIndex: raw.channel_index,
+                });
+              } else {
+                pendingTexts.set(channelIndex, raw.text ?? '');
+                controller.enqueue({
+                  type: 'transcript-partial',
+                  id,
+                  text: raw.text ?? '',
+                  startSecond: raw.start,
+                  durationInSeconds: raw.duration,
+                  channelIndex: raw.channel_index,
+                });
               }
+              break;
             }
-          })
-          .catch(finishWithError);
-      };
 
-      ws.onerror = () => {
-        finishWithError(
-          new Error(
-            'xAI streaming transcription error.' +
-              (webSocket == null
-                ? ' Note: the native WebSocket implementation in browsers,' +
-                  ' Node.js, Deno, and Bun cannot send the Authorization' +
-                  ' header required by xAI. Pass a header-capable WebSocket' +
-                  " implementation (e.g. the 'ws' package) via" +
-                  ' createXai({ webSocket }).'
-                : ''),
-          ),
-        );
-      };
+            case 'transcript.done': {
+              const channelIndex = raw.channel_index ?? 0;
+              // `transcript.done` text is empty; fall back to the
+              // accumulated utterances plus any trailing unfinalized text:
+              const accumulated = [
+                ...(finalizedTexts.get(channelIndex) ?? []),
+                ...(pendingTexts.get(channelIndex)
+                  ? [pendingTexts.get(channelIndex) as string]
+                  : []),
+              ].join(' ');
+              doneTexts.set(channelIndex, raw.text || accumulated);
+              doneDuration = raw.duration ?? doneDuration;
+              maybeFinish();
+              break;
+            }
 
-      ws.onclose = () => {
-        if (finished) return;
-        finished = true;
-        cleanup();
-        controller.close();
-      };
+            case 'error': {
+              // xAI STT errors are terminal: surface the server message
+              // instead of letting the socket close mask it.
+              finishWithError(new Error(raw.message ?? 'xAI STT error'));
+              break;
+            }
+          }
+        },
+        onSocketError: () => {
+          finishWithError(
+            new Error(
+              'xAI streaming transcription error.' +
+                (webSocket == null
+                  ? ' Note: the native WebSocket implementation in browsers,' +
+                    ' Node.js, Deno, and Bun cannot send the Authorization' +
+                    ' header required by xAI. Pass a header-capable WebSocket' +
+                    " implementation (e.g. the 'ws' package) via" +
+                    ' createXai({ webSocket }).'
+                  : ''),
+            ),
+          );
+        },
+        onClose: () => {
+          if (finished) return;
+          finished = true;
+          cleanup();
+          controller.close();
+        },
+      });
     },
 
     cancel: () => {

package/src/xai-video-model.ts

@@ -10,6 +10,7 @@ import {
   createJsonResponseHandler,
   delay,
   getFromApi,
+  getTopLevelMediaType,
   parseProviderOptions,
   postJsonToApi,
   type FetchFunction,
@@ -62,6 +63,9 @@ function resolveStartImage(
   return getFirstFrameImage(options) ?? options.image;
 }
 
+const isVideoFile = (file: Experimental_VideoModelV4File): boolean =>
+  file.mediaType != null && getTopLevelMediaType(file.mediaType) === 'video';
+
 function fileToXaiImageUrl(file: Experimental_VideoModelV4File): string {
   if (file.type === 'url') {
     return file.url;
@@ -71,17 +75,35 @@ function fileToXaiImageUrl(file: Experimental_VideoModelV4File): string {
     typeof file.data === 'string'
       ? file.data
       : convertUint8ArrayToBase64(file.data);
-  return `data:${file.mediaType ?? 'image/png'};base64,${base64Data}`;
+  return `data:${file.mediaType};base64,${base64Data}`;
 }
 
 // Resolves the reference images for R2V generation. First-class
 // `inputReferences` win over the legacy `referenceImageUrls` provider option.
+// Video references are not supported for reference-to-video and are skipped
+// with a warning.
 function resolveReferenceImages(
   options: XaiVideoDoGenerateOptions,
   xaiOptions: XaiParsedVideoModelOptions | undefined,
+  warnings: SharedV4Warning[],
 ): Array<{ url: string }> | undefined {
   if (options.inputReferences != null && options.inputReferences.length > 0) {
-    return options.inputReferences.map(reference => ({
+    const imageReferences = options.inputReferences.filter(reference => {
+      if (isVideoFile(reference)) {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'inputReferences',
+          details:
+            'xAI reference-to-video accepts image references only. The video ' +
+            'reference was ignored. Use providerOptions.xai.mode ' +
+            '"extend-video" to continue from a video.',
+        });
+        return false;
+      }
+      return true;
+    });
+
+    return imageReferences.map(reference => ({
       url: fileToXaiImageUrl(reference),
     }));
   }
@@ -278,24 +300,44 @@ export class XaiVideoModel implements Experimental_VideoModelV4 {
     // nested xAI request image object.
     const startImage = resolveStartImage(options);
     if (startImage != null) {
-      body.image = { url: fileToXaiImageUrl(startImage) };
+      if (isVideoFile(startImage)) {
+        const fromFrameImages = getFirstFrameImage(options) != null;
+        warnings.push({
+          type: 'unsupported',
+          feature: fromFrameImages ? 'frameImages' : 'image',
+          details:
+            'xAI does not accept a video as a start/frame image. The video ' +
+            'was ignored. Use providerOptions.xai.mode "extend-video" to ' +
+            'continue from a video instead.',
+        });
+      } else {
+        body.image = { url: fileToXaiImageUrl(startImage) };
+      }
     }
 
     // xAI has no first-last-frame interpolation; warn and ignore last_frame.
-    if (getLastFrameImage(options) != null) {
+    const lastFrameImage = getLastFrameImage(options);
+    if (lastFrameImage != null) {
       warnings.push({
         type: 'unsupported',
         feature: 'frameImages',
-        details:
-          'xAI video models do not support last_frame. Use ' +
-          'providerOptions.xai.mode "extend-video" to continue from a ' +
-          "video's last frame. The last frame image was ignored.",
+        details: isVideoFile(lastFrameImage)
+          ? 'xAI does not accept a video as a start/frame image. The video ' +
+            'last frame was ignored. Use providerOptions.xai.mode ' +
+            '"extend-video" to continue from a video instead.'
+          : 'xAI video models do not support last_frame. Use ' +
+            'providerOptions.xai.mode "extend-video" to continue from a ' +
+            "video's last frame. The last frame image was ignored.",
       });
     }
 
     // Reference images for R2V (reference-to-video) generation
     if (hasReferenceImages) {
-      const referenceImages = resolveReferenceImages(options, xaiOptions);
+      const referenceImages = resolveReferenceImages(
+        options,
+        xaiOptions,
+        warnings,
+      );
       if (referenceImages != null) {
         body.reference_images = referenceImages;
       }
@@ -386,6 +428,7 @@ export class XaiVideoModel implements Experimental_VideoModelV4 {
       const { value: statusResponse, responseHeaders: pollHeaders } =
         await getFromApi({
           url: `${baseURL}/videos/${requestId}`,
+          validateUrl: false,
           headers: combineHeaders(this.config.headers(), options.headers),
           successfulResponseHandler: createJsonResponseHandler(
             xaiVideoStatusResponseSchema,