@ai-sdk/xai 4.0.39 → 4.0.40

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @ai-sdk/xai
 
+## 4.0.40
+
+### Patch Changes
+
+- 1ffa1d2: feat(xai): speech timestamps, pronunciation replacements, provider metadata, and error parsing
+
+  - Add `withTimestamps` and `replace` provider options for text to speech. With
+    `withTimestamps`, the JSON envelope is decoded and the audio returned as
+    usual, while duration, content type, and character-level alignment are
+    exposed via `providerMetadata.xai`.
+  - Return `providerMetadata.xai.traceId` (from the `x-trace-id` response
+    header) on every speech response.
+  - Parse the text to speech error shape (`{"error":"..."}`) so `APICallError`
+    messages carry xAI's real error detail instead of the HTTP reason phrase.
+
 ## 4.0.39
 
 ### Patch Changes

package/dist/index.d.ts

@@ -65,6 +65,8 @@ declare const xaiErrorDataSchema: z.ZodUnion<readonly [z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     code: z.ZodString;
     error: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodString;
 }, z.core.$strip>]>;
 type XaiErrorData = z.infer<typeof xaiErrorDataSchema>;
 
@@ -218,6 +220,8 @@ declare const xaiSpeechModelOptionsSchema: _ai_sdk_provider_utils.LazySchema<{
     bitRate?: 32000 | 64000 | 96000 | 128000 | 192000 | null | undefined;
     optimizeStreamingLatency?: 0 | 1 | 2 | null | undefined;
     textNormalization?: boolean | null | undefined;
+    withTimestamps?: boolean | null | undefined;
+    replace?: Record<string, string> | null | undefined;
 }>;
 type XaiSpeechModelOptions = InferSchema<typeof xaiSpeechModelOptionsSchema>;
 

package/dist/index.js

@@ -384,13 +384,22 @@ var responsesErrorSchema = z3.object({
   code: z3.string(),
   error: z3.string()
 });
+var speechErrorSchema = z3.object({
+  error: z3.string()
+});
 var xaiErrorDataSchema = z3.union([
   chatCompletionsErrorSchema,
-  responsesErrorSchema
+  responsesErrorSchema,
+  speechErrorSchema
 ]);
 var xaiFailedResponseHandler = createJsonErrorResponseHandler({
   errorSchema: xaiErrorDataSchema,
-  errorToMessage: (data) => "code" in data ? `${data.code}: ${data.error}` : data.error.message
+  errorToMessage: (data) => {
+    if (typeof data.error === "string") {
+      return "code" in data ? `${data.code}: ${data.error}` : data.error;
+    }
+    return data.error.message;
+  }
 });
 
 // src/xai-prepare-tools.ts
@@ -3720,7 +3729,7 @@ var xaiTools = {
 };
 
 // src/version.ts
-var VERSION = true ? "4.0.39" : "0.0.0-test";
+var VERSION = true ? "4.0.40" : "0.0.0-test";
 
 // src/files/xai-files.ts
 import {
@@ -4360,7 +4369,9 @@ var xaiVideoStatusResponseHandler = async (options) => {
 // src/xai-speech-model.ts
 import {
   combineHeaders as combineHeaders6,
+  convertBase64ToUint8Array,
   createBinaryResponseHandler as createBinaryResponseHandler2,
+  createJsonResponseHandler as createJsonResponseHandler6,
   parseProviderOptions as parseProviderOptions8,
   postJsonToApi as postJsonToApi5,
   resolve,
@@ -4368,6 +4379,7 @@ import {
   WORKFLOW_DESERIALIZE as WORKFLOW_DESERIALIZE4,
   WORKFLOW_SERIALIZE as WORKFLOW_SERIALIZE4
 } from "@ai-sdk/provider-utils";
+import { z as z22 } from "zod/v4";
 
 // src/xai-speech-model-options.ts
 import {
@@ -4406,7 +4418,19 @@ var xaiSpeechModelOptionsSchema = lazySchema9(
       /**
        * Normalize written-form text into spoken-form text before synthesis.
        */
-      textNormalization: z21.boolean().nullish()
+      textNormalization: z21.boolean().nullish(),
+      /**
+       * Return character-level timing metadata alongside the audio. When
+       * enabled, the response carries per-character start/end times and the
+       * total duration, exposed via `providerMetadata.xai`.
+       */
+      withTimestamps: z21.boolean().nullish(),
+      /**
+       * Map of phrases to spoken substitutions applied before synthesis.
+       * Values may be respellings (`{ 'Acme Mobile': 'Acme Mobull' }`) or IPA
+       * phonetics (`{ nginx: '/ˈɛndʒɪn ˈɛks/' }`).
+       */
+      replace: z21.record(z21.string(), z21.string()).nullish()
     })
   )
 );
@@ -4486,19 +4510,21 @@ var XaiSpeechModel = class _XaiSpeechModel {
       output_format,
       speed,
       optimize_streaming_latency: xaiOptions == null ? void 0 : xaiOptions.optimizeStreamingLatency,
-      text_normalization: xaiOptions == null ? void 0 : xaiOptions.textNormalization
+      text_normalization: xaiOptions == null ? void 0 : xaiOptions.textNormalization,
+      with_timestamps: xaiOptions == null ? void 0 : xaiOptions.withTimestamps,
+      replace: xaiOptions == null ? void 0 : xaiOptions.replace
+    };
+    return {
+      requestBody,
+      warnings,
+      withTimestamps: (xaiOptions == null ? void 0 : xaiOptions.withTimestamps) === true
     };
-    return { requestBody, warnings };
   }
   async doGenerate(options) {
     var _a, _b, _c;
     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 { requestBody, warnings } = await this.getArgs(options);
-    const {
-      value: audio,
-      responseHeaders,
-      rawValue: rawResponse
-    } = await postJsonToApi5({
+    const { requestBody, warnings, withTimestamps } = await this.getArgs(options);
+    const { value, responseHeaders, rawValue } = await postJsonToApi5({
       url: `${this.config.baseURL}/tts`,
       headers: combineHeaders6(
         this.config.headers ? await resolve(this.config.headers) : void 0,
@@ -4506,10 +4532,19 @@ var XaiSpeechModel = class _XaiSpeechModel {
       ),
       body: requestBody,
       failedResponseHandler: xaiFailedResponseHandler,
-      successfulResponseHandler: createBinaryResponseHandler2(),
+      successfulResponseHandler: withTimestamps ? createJsonResponseHandler6(xaiSpeechTimestampsResponseSchema) : createBinaryResponseHandler2(),
       abortSignal: options.abortSignal,
       fetch: this.config.fetch
     });
+    let audio;
+    let envelope;
+    if (value instanceof Uint8Array) {
+      audio = value;
+    } else {
+      envelope = value;
+      audio = envelope.audio != null ? convertBase64ToUint8Array(envelope.audio) : new Uint8Array(0);
+    }
+    const traceId = responseHeaders == null ? void 0 : responseHeaders["x-trace-id"];
     return {
       audio,
       warnings,
@@ -4520,11 +4555,33 @@ var XaiSpeechModel = class _XaiSpeechModel {
         timestamp: currentDate,
         modelId: this.modelId,
         headers: responseHeaders,
-        body: rawResponse
+        body: rawValue
+      },
+      providerMetadata: {
+        xai: {
+          ...traceId != null ? { traceId } : {},
+          ...(envelope == null ? void 0 : envelope.duration) != null ? { duration: envelope.duration } : {},
+          ...(envelope == null ? void 0 : envelope.content_type) != null ? { contentType: envelope.content_type } : {},
+          ...(envelope == null ? void 0 : envelope.audio_timestamps) != null ? {
+            audioTimestamps: {
+              graphChars: envelope.audio_timestamps.graph_chars,
+              graphTimes: envelope.audio_timestamps.graph_times
+            }
+          } : {}
+        }
       }
     };
   }
 };
+var xaiSpeechTimestampsResponseSchema = z22.object({
+  audio: z22.string().nullish(),
+  content_type: z22.string().nullish(),
+  duration: z22.number().nullish(),
+  audio_timestamps: z22.object({
+    graph_chars: z22.array(z22.string()),
+    graph_times: z22.array(z22.tuple([z22.number(), z22.number()]))
+  }).nullish()
+});
 
 // src/xai-transcription-model.ts
 import {
@@ -4532,8 +4589,8 @@ import {
 } from "@ai-sdk/provider";
 import {
   combineHeaders as combineHeaders7,
-  convertBase64ToUint8Array,
-  createJsonResponseHandler as createJsonResponseHandler6,
+  convertBase64ToUint8Array as convertBase64ToUint8Array2,
+  createJsonResponseHandler as createJsonResponseHandler7,
   connectToWebSocket,
   mediaTypeToExtension,
   parseProviderOptions as parseProviderOptions9,
@@ -4545,80 +4602,80 @@ import {
   WORKFLOW_DESERIALIZE as WORKFLOW_DESERIALIZE5,
   WORKFLOW_SERIALIZE as WORKFLOW_SERIALIZE5
 } from "@ai-sdk/provider-utils";
-import { z as z23 } from "zod/v4";
+import { z as z24 } from "zod/v4";
 
 // src/xai-transcription-model-options.ts
 import {
   lazySchema as lazySchema10,
   zodSchema as zodSchema10
 } from "@ai-sdk/provider-utils";
-import { z as z22 } from "zod/v4";
+import { z as z23 } from "zod/v4";
 var xaiTranscriptionModelOptionsSchema = lazySchema10(
   () => zodSchema10(
-    z22.object({
+    z23.object({
       /**
        * Audio encoding for raw, headerless input audio.
        */
-      audioFormat: z22.enum(["pcm", "mulaw", "alaw"]).nullish(),
+      audioFormat: z23.enum(["pcm", "mulaw", "alaw"]).nullish(),
       /**
        * Sample rate of the input audio in Hz.
        */
-      sampleRate: z22.union([
-        z22.literal(8e3),
-        z22.literal(16e3),
-        z22.literal(22050),
-        z22.literal(24e3),
-        z22.literal(44100),
-        z22.literal(48e3)
+      sampleRate: z23.union([
+        z23.literal(8e3),
+        z23.literal(16e3),
+        z23.literal(22050),
+        z23.literal(24e3),
+        z23.literal(44100),
+        z23.literal(48e3)
       ]).nullish(),
       /**
        * Language code used for inverse text normalization.
        */
-      language: z22.string().nullish(),
+      language: z23.string().nullish(),
       /**
        * Enable inverse text normalization. Requires `language`.
        */
-      format: z22.boolean().nullish(),
+      format: z23.boolean().nullish(),
       /**
        * Enable per-channel transcription for multichannel audio.
        */
-      multichannel: z22.boolean().nullish(),
+      multichannel: z23.boolean().nullish(),
       /**
        * Number of interleaved audio channels.
        */
-      channels: z22.number().int().min(2).max(8).nullish(),
+      channels: z23.number().int().min(2).max(8).nullish(),
       /**
        * Enable speaker diarization.
        */
-      diarize: z22.boolean().nullish(),
+      diarize: z23.boolean().nullish(),
       /**
        * Terms to bias transcription toward.
        */
-      keyterm: z22.union([z22.string(), z22.array(z22.string())]).nullish(),
+      keyterm: z23.union([z23.string(), z23.array(z23.string())]).nullish(),
       /**
        * Include filler words such as "uh" and "um" in the transcript.
        */
-      fillerWords: z22.boolean().nullish(),
+      fillerWords: z23.boolean().nullish(),
       /**
        * Options for streaming speech-to-text over WebSocket.
        */
-      streaming: z22.object({
+      streaming: z23.object({
         /**
          * Emit interim transcript results while speech is being processed.
          */
-        interimResults: z22.boolean().optional(),
+        interimResults: z23.boolean().optional(),
         /**
          * Silence duration in milliseconds before an utterance-final event.
          */
-        endpointing: z22.number().int().min(0).max(5e3).optional(),
+        endpointing: z23.number().int().min(0).max(5e3).optional(),
         /**
          * End-of-turn detection threshold. When set, enables Smart Turn.
          */
-        smartTurn: z22.number().min(0).max(1).optional(),
+        smartTurn: z23.number().min(0).max(1).optional(),
         /**
          * Maximum silence duration in milliseconds before forcing speech_final.
          */
-        smartTurnTimeout: z22.number().int().min(1).max(5e3).optional()
+        smartTurnTimeout: z23.number().int().min(1).max(5e3).optional()
       }).optional()
     })
   )
@@ -4676,7 +4733,7 @@ var XaiTranscriptionModel = class _XaiTranscriptionModel {
         formData.append("keyterm", keyterm);
       }
     }
-    const blob = audio instanceof Uint8Array ? new Blob([audio]) : new Blob([convertBase64ToUint8Array(audio)]);
+    const blob = audio instanceof Uint8Array ? new Blob([audio]) : new Blob([convertBase64ToUint8Array2(audio)]);
     const fileExtension = mediaTypeToExtension(mediaType);
     formData.append(
       "file",
@@ -4698,7 +4755,7 @@ var XaiTranscriptionModel = class _XaiTranscriptionModel {
       headers: combineHeaders7((_f = (_e = this.config).headers) == null ? void 0 : _f.call(_e), options.headers),
       formData,
       failedResponseHandler: xaiFailedResponseHandler,
-      successfulResponseHandler: createJsonResponseHandler6(
+      successfulResponseHandler: createJsonResponseHandler7(
         xaiTranscriptionResponseSchema
       ),
       abortSignal: options.abortSignal,
@@ -4835,7 +4892,7 @@ function createXaiStreamingTranscriptionStream({
             const { done, value } = await audioReader.read();
             if (done || finished) break;
             socket.send(
-              value instanceof Uint8Array ? value : convertBase64ToUint8Array(value)
+              value instanceof Uint8Array ? value : convertBase64ToUint8Array2(value)
             );
             await waitForWebSocketBufferDrain(socket);
           }
@@ -5017,15 +5074,15 @@ function timingFromXaiEvent(event) {
     ...event.start != null && event.duration != null ? { endSecond: event.start + event.duration } : {}
   };
 }
-var xaiTranscriptionResponseSchema = z23.object({
-  text: z23.string(),
-  language: z23.string().nullish(),
-  duration: z23.number().nullish(),
-  words: z23.array(
-    z23.object({
-      text: z23.string(),
-      start: z23.number(),
-      end: z23.number()
+var xaiTranscriptionResponseSchema = z24.object({
+  text: z24.string(),
+  language: z24.string().nullish(),
+  duration: z24.number().nullish(),
+  words: z24.array(
+    z24.object({
+      text: z24.string(),
+      start: z24.number(),
+      end: z24.number()
     })
   ).nullish()
 });