@ai-sdk/xai 4.0.4 → 4.0.6

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @ai-sdk/xai
 
+## 4.0.6
+
+### Patch Changes
+
+- 5c5c0f5: Add experimental streaming transcription support for transcription models, including OpenAI `gpt-realtime-whisper` and xAI WebSocket STT.
+- Updated dependencies [5c5c0f5]
+  - @ai-sdk/provider@4.0.2
+  - @ai-sdk/provider-utils@5.0.5
+  - @ai-sdk/openai-compatible@3.0.5
+
+## 4.0.5
+
+### Patch Changes
+
+- Updated dependencies [c6f5e62]
+  - @ai-sdk/provider-utils@5.0.4
+  - @ai-sdk/openai-compatible@3.0.4
+
 ## 4.0.4
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod/v4';
 import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
-import { InferSchema, FetchFunction } from '@ai-sdk/provider-utils';
+import { InferSchema, FetchFunction, WebSocketConstructor } from '@ai-sdk/provider-utils';
 import { ProviderV4, LanguageModelV4, ImageModelV4, Experimental_VideoModelV4, Experimental_RealtimeFactoryV4, SpeechModelV4, TranscriptionModelV4, FilesV4, Experimental_RealtimeModelV4, Experimental_RealtimeModelV4ClientSecretOptions, Experimental_RealtimeModelV4ClientSecretResult, Experimental_RealtimeModelV4ServerEvent, Experimental_RealtimeModelV4ClientEvent, Experimental_RealtimeModelV4SessionConfig } from '@ai-sdk/provider';
 
 type XaiChatModelId = 'grok-4.20-non-reasoning' | 'grok-4.20-reasoning' | 'grok-4.3' | 'grok-latest' | (string & {});
@@ -197,6 +197,12 @@ declare const xaiTranscriptionModelOptionsSchema: _ai_sdk_provider_utils.LazySch
     diarize?: boolean | null | undefined;
     keyterm?: string | string[] | null | undefined;
     fillerWords?: boolean | null | undefined;
+    streaming?: {
+        interimResults?: boolean | undefined;
+        endpointing?: number | undefined;
+        smartTurn?: number | undefined;
+        smartTurnTimeout?: number | undefined;
+    } | undefined;
 }>;
 type XaiTranscriptionModelOptions = InferSchema<typeof xaiTranscriptionModelOptionsSchema>;
 
@@ -488,6 +494,11 @@ interface XaiProviderSettings {
      * or to provide a custom fetch implementation for e.g. testing.
      */
     fetch?: FetchFunction;
+    /**
+     * Custom WebSocket implementation. Required in runtimes whose native
+     * WebSocket constructor does not support headers for xAI streaming STT.
+     */
+    webSocket?: WebSocketConstructor;
 }
 declare function createXai(options?: XaiProviderSettings): XaiProvider;
 declare const xai: XaiProvider;

package/dist/index.js

@@ -3393,7 +3393,7 @@ var xaiTools = {
 };
 
 // src/version.ts
-var VERSION = true ? "4.0.4" : "0.0.0-test";
+var VERSION = true ? "4.0.6" : "0.0.0-test";
 
 // src/files/xai-files.ts
 import {
@@ -4058,14 +4058,21 @@ var XaiSpeechModel = class _XaiSpeechModel {
 };
 
 // src/xai-transcription-model.ts
+import {
+  InvalidArgumentError
+} from "@ai-sdk/provider";
 import {
   combineHeaders as combineHeaders7,
   convertBase64ToUint8Array,
   createJsonResponseHandler as createJsonResponseHandler6,
+  getWebSocketConstructor,
   mediaTypeToExtension,
   parseProviderOptions as parseProviderOptions7,
   postFormDataToApi as postFormDataToApi2,
+  readWebSocketMessageText,
+  safeParseJSON as safeParseJSON2,
   serializeModelOptions as serializeModelOptions5,
+  toWebSocketUrl,
   WORKFLOW_DESERIALIZE as WORKFLOW_DESERIALIZE5,
   WORKFLOW_SERIALIZE as WORKFLOW_SERIALIZE5
 } from "@ai-sdk/provider-utils";
@@ -4122,7 +4129,28 @@ var xaiTranscriptionModelOptionsSchema = lazySchema9(
       /**
        * Include filler words such as "uh" and "um" in the transcript.
        */
-      fillerWords: z20.boolean().nullish()
+      fillerWords: z20.boolean().nullish(),
+      /**
+       * Options for streaming speech-to-text over WebSocket.
+       */
+      streaming: z20.object({
+        /**
+         * Emit interim transcript results while speech is being processed.
+         */
+        interimResults: z20.boolean().optional(),
+        /**
+         * Silence duration in milliseconds before an utterance-final event.
+         */
+        endpointing: z20.number().int().min(0).max(5e3).optional(),
+        /**
+         * End-of-turn detection threshold. When set, enables Smart Turn.
+         */
+        smartTurn: z20.number().min(0).max(1).optional(),
+        /**
+         * Maximum silence duration in milliseconds before forcing speech_final.
+         */
+        smartTurnTimeout: z20.number().int().min(1).max(5e3).optional()
+      }).optional()
     })
   )
 );
@@ -4225,7 +4253,282 @@ var XaiTranscriptionModel = class _XaiTranscriptionModel {
       }
     };
   }
+  async doStream(options) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const currentDate = (_c = (_b = (_a = this.config._internal) == null ? void 0 : _a.currentDate) == null ? void 0 : _b.call(_a)) != null ? _c : /* @__PURE__ */ new Date();
+    const warnings = [];
+    const xaiOptions = await parseProviderOptions7({
+      provider: "xai",
+      providerOptions: options.providerOptions,
+      schema: xaiTranscriptionModelOptionsSchema
+    });
+    if ((xaiOptions == null ? void 0 : xaiOptions.multichannel) === true && xaiOptions.channels == null) {
+      throw new InvalidArgumentError({
+        argument: "providerOptions",
+        message: "providerOptions.xai.channels is required when providerOptions.xai.multichannel is true"
+      });
+    }
+    if ((xaiOptions == null ? void 0 : xaiOptions.format) != null) {
+      warnings.push({
+        type: "unsupported",
+        feature: "providerOptions.xai.format",
+        details: "xAI streaming transcription does not support format."
+      });
+    }
+    if ((xaiOptions == null ? void 0 : xaiOptions.audioFormat) == null && !isKnownInputAudioFormat(options.inputAudioFormat.type)) {
+      warnings.push({
+        type: "other",
+        message: `Unrecognized inputAudioFormat.type "${options.inputAudioFormat.type}"; falling back to raw PCM encoding. Use audio/pcm, audio/pcmu, or audio/pcma, or set providerOptions.xai.audioFormat explicitly.`
+      });
+    }
+    const url = buildXaiStreamingTranscriptionUrl({
+      baseURL: (_d = this.config.baseURL) != null ? _d : "https://api.x.ai/v1",
+      inputAudioFormat: options.inputAudioFormat,
+      providerOptions: xaiOptions
+    });
+    const headers = combineHeaders7((_f = (_e = this.config).headers) == null ? void 0 : _f.call(_e), options.headers);
+    return {
+      request: { body: url.toString() },
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId
+      },
+      stream: createXaiStreamingTranscriptionStream({
+        webSocket: this.config.webSocket,
+        url,
+        headers,
+        warnings,
+        language: (_g = xaiOptions == null ? void 0 : xaiOptions.language) != null ? _g : void 0,
+        expectedDoneCount: (xaiOptions == null ? void 0 : xaiOptions.multichannel) === true ? xaiOptions.channels : 1,
+        audio: options.audio,
+        abortSignal: options.abortSignal,
+        includeRawChunks: options.includeRawChunks
+      })
+    };
+  }
 };
+function createXaiStreamingTranscriptionStream({
+  webSocket,
+  url,
+  headers,
+  warnings,
+  language,
+  expectedDoneCount,
+  audio,
+  abortSignal,
+  includeRawChunks
+}) {
+  let finished = false;
+  let cleanup = () => {
+  };
+  return new ReadableStream({
+    start: (controller) => {
+      const WebSocketConstructor = getWebSocketConstructor(webSocket);
+      const ws = new WebSocketConstructor(url, void 0, { headers });
+      const doneTexts = /* @__PURE__ */ new Map();
+      let doneDuration;
+      let audioReader;
+      cleanup = (closeCode) => {
+        abortSignal == null ? void 0 : abortSignal.removeEventListener("abort", abort);
+        void (audioReader == null ? void 0 : audioReader.cancel().catch(() => {
+        }));
+        try {
+          ws.close(closeCode);
+        } catch (e) {
+        }
+      };
+      const finishWithError = (error) => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        controller.error(error);
+      };
+      const maybeFinish = () => {
+        if (finished || doneTexts.size < expectedDoneCount) return;
+        finished = true;
+        const text = [...doneTexts.entries()].sort(([a], [b]) => a - b).map(([, value]) => value).join("\n");
+        controller.enqueue({
+          type: "finish",
+          text,
+          segments: [],
+          language,
+          durationInSeconds: doneDuration
+        });
+        controller.close();
+        cleanup(1e3);
+      };
+      const abort = () => {
+        var _a;
+        finishWithError((_a = abortSignal == null ? void 0 : abortSignal.reason) != null ? _a : new Error("Aborted"));
+      };
+      if (abortSignal == null ? void 0 : abortSignal.aborted) {
+        abort();
+        return;
+      }
+      abortSignal == null ? void 0 : abortSignal.addEventListener("abort", abort, { once: true });
+      const sendAudio = async () => {
+        audioReader = audio.getReader();
+        try {
+          while (true) {
+            const { done, value } = await audioReader.read();
+            if (done || finished) break;
+            ws.send(
+              value instanceof Uint8Array ? value : convertBase64ToUint8Array(value)
+            );
+          }
+        } finally {
+          audioReader.releaseLock();
+        }
+        if (!finished) {
+          ws.send(JSON.stringify({ type: "audio.done" }));
+        }
+      };
+      ws.onmessage = (event) => {
+        void readWebSocketMessageText(event.data).then(async (text) => {
+          var _a, _b, _c, _d, _e, _f;
+          const parsed = await safeParseJSON2({ text });
+          if (!parsed.success) return;
+          const raw = parsed.value;
+          if (includeRawChunks) {
+            controller.enqueue({ type: "raw", rawValue: raw });
+          }
+          switch (raw.type) {
+            case "transcript.created": {
+              controller.enqueue({ type: "stream-start", warnings });
+              void sendAudio().catch(finishWithError);
+              break;
+            }
+            case "transcript.partial": {
+              const id = channelId(raw.channel_index);
+              const timing = timingFromXaiEvent(raw);
+              if (raw.is_final) {
+                controller.enqueue({
+                  type: "transcript-final",
+                  id,
+                  text: (_a = raw.text) != null ? _a : "",
+                  ...timing,
+                  channelIndex: raw.channel_index
+                });
+              } else {
+                controller.enqueue({
+                  type: "transcript-partial",
+                  id,
+                  text: (_b = raw.text) != null ? _b : "",
+                  startSecond: raw.start,
+                  durationInSeconds: raw.duration,
+                  channelIndex: raw.channel_index
+                });
+              }
+              break;
+            }
+            case "transcript.done": {
+              const channelIndex = (_c = raw.channel_index) != null ? _c : 0;
+              doneTexts.set(channelIndex, (_d = raw.text) != null ? _d : "");
+              doneDuration = (_e = raw.duration) != null ? _e : doneDuration;
+              maybeFinish();
+              break;
+            }
+            case "error": {
+              finishWithError(new Error((_f = raw.message) != null ? _f : "xAI STT error"));
+              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 })." : "")
+          )
+        );
+      };
+      ws.onclose = () => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        controller.close();
+      };
+    },
+    cancel: () => {
+      if (finished) return;
+      finished = true;
+      cleanup();
+    }
+  });
+}
+function buildXaiStreamingTranscriptionUrl({
+  baseURL,
+  inputAudioFormat,
+  providerOptions
+}) {
+  var _a, _b, _c, _d, _e, _f;
+  const url = toWebSocketUrl(`${baseURL}/stt`);
+  appendSearchParam(
+    url,
+    "sample_rate",
+    (_a = providerOptions == null ? void 0 : providerOptions.sampleRate) != null ? _a : inputAudioFormat.rate
+  );
+  appendSearchParam(
+    url,
+    "encoding",
+    (_b = providerOptions == null ? void 0 : providerOptions.audioFormat) != null ? _b : encodingFromInputAudioFormat(inputAudioFormat.type)
+  );
+  appendSearchParam(url, "language", providerOptions == null ? void 0 : providerOptions.language);
+  appendSearchParam(url, "diarize", providerOptions == null ? void 0 : providerOptions.diarize);
+  appendSearchParam(url, "filler_words", providerOptions == null ? void 0 : providerOptions.fillerWords);
+  appendSearchParam(url, "multichannel", providerOptions == null ? void 0 : providerOptions.multichannel);
+  appendSearchParam(url, "channels", providerOptions == null ? void 0 : providerOptions.channels);
+  appendSearchParam(
+    url,
+    "interim_results",
+    (_c = providerOptions == null ? void 0 : providerOptions.streaming) == null ? void 0 : _c.interimResults
+  );
+  appendSearchParam(
+    url,
+    "endpointing",
+    (_d = providerOptions == null ? void 0 : providerOptions.streaming) == null ? void 0 : _d.endpointing
+  );
+  appendSearchParam(url, "smart_turn", (_e = providerOptions == null ? void 0 : providerOptions.streaming) == null ? void 0 : _e.smartTurn);
+  appendSearchParam(
+    url,
+    "smart_turn_timeout",
+    (_f = providerOptions == null ? void 0 : providerOptions.streaming) == null ? void 0 : _f.smartTurnTimeout
+  );
+  if ((providerOptions == null ? void 0 : providerOptions.keyterm) != null) {
+    const keyterms = Array.isArray(providerOptions.keyterm) ? providerOptions.keyterm : [providerOptions.keyterm];
+    for (const keyterm of keyterms) {
+      url.searchParams.append("keyterm", keyterm);
+    }
+  }
+  return url;
+}
+function appendSearchParam(url, key, value) {
+  if (value != null) {
+    url.searchParams.set(key, String(value));
+  }
+}
+function isKnownInputAudioFormat(type) {
+  return type === "audio/pcm" || type === "audio/pcmu" || type === "audio/pcma";
+}
+function encodingFromInputAudioFormat(type) {
+  switch (type) {
+    case "audio/pcmu":
+      return "mulaw";
+    case "audio/pcma":
+      return "alaw";
+    default:
+      return "pcm";
+  }
+}
+function channelId(channelIndex) {
+  return channelIndex == null ? void 0 : `channel-${channelIndex}`;
+}
+function timingFromXaiEvent(event) {
+  return {
+    ...event.start != null ? { startSecond: event.start } : {},
+    ...event.start != null && event.duration != null ? { endSecond: event.start + event.duration } : {}
+  };
+}
 var xaiTranscriptionResponseSchema = z21.object({
   text: z21.string(),
   language: z21.string().nullish(),
@@ -4311,7 +4614,8 @@ function createXai(options = {}) {
       provider: "xai.transcription",
       baseURL,
       headers: getHeaders,
-      fetch: options.fetch
+      fetch: options.fetch,
+      webSocket: options.webSocket
     });
   };
   const experimentalRealtimeFactory = Object.assign(