@ai-sdk/xai 4.0.0-beta.7 → 4.0.0-beta.75

package/src/xai-speech-model-options.ts

@@ -0,0 +1,55 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const xaiSpeechModelOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * Sample rate of the generated audio in Hz.
+       */
+      sampleRate: z
+        .union([
+          z.literal(8000),
+          z.literal(16000),
+          z.literal(22050),
+          z.literal(24000),
+          z.literal(44100),
+          z.literal(48000),
+        ])
+        .nullish(),
+
+      /**
+       * MP3 bit rate in bits per second. Only applies when outputFormat is mp3.
+       */
+      bitRate: z
+        .union([
+          z.literal(32000),
+          z.literal(64000),
+          z.literal(96000),
+          z.literal(128000),
+          z.literal(192000),
+        ])
+        .nullish(),
+
+      /**
+       * Reduce time to first audio chunk, trading some quality for latency.
+       */
+      optimizeStreamingLatency: z
+        .union([z.literal(0), z.literal(1), z.literal(2)])
+        .nullish(),
+
+      /**
+       * Normalize written-form text into spoken-form text before synthesis.
+       */
+      textNormalization: z.boolean().nullish(),
+    }),
+  ),
+);
+
+export type XaiSpeechModelOptions = InferSchema<
+  typeof xaiSpeechModelOptionsSchema
+>;

package/src/xai-speech-model.ts

@@ -0,0 +1,167 @@
+import type { SharedV4Warning, SpeechModelV4 } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createBinaryResponseHandler,
+  parseProviderOptions,
+  postJsonToApi,
+  resolve,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
+  type FetchFunction,
+  type Resolvable,
+} from '@ai-sdk/provider-utils';
+import { xaiFailedResponseHandler } from './xai-error';
+import { xaiSpeechModelOptionsSchema } from './xai-speech-model-options';
+
+interface XaiSpeechModelConfig {
+  provider: string;
+  baseURL: string | undefined;
+  headers?: Resolvable<Record<string, string | undefined>>;
+  fetch?: FetchFunction;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+type XaiSpeechCodec = 'mp3' | 'wav' | 'pcm' | 'mulaw' | 'alaw';
+
+export class XaiSpeechModel implements SpeechModelV4 {
+  readonly specificationVersion = 'v4';
+
+  static [WORKFLOW_SERIALIZE](model: XaiSpeechModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: '';
+    config: XaiSpeechModelConfig;
+  }) {
+    return new XaiSpeechModel(options.modelId, options.config);
+  }
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: '',
+    private readonly config: XaiSpeechModelConfig,
+  ) {}
+
+  private async getArgs({
+    text,
+    voice = 'eve',
+    outputFormat = 'mp3',
+    instructions,
+    speed,
+    language = 'auto',
+    providerOptions,
+  }: Parameters<SpeechModelV4['doGenerate']>[0]) {
+    const warnings: SharedV4Warning[] = [];
+    const xaiOptions = await parseProviderOptions({
+      provider: 'xai',
+      providerOptions,
+      schema: xaiSpeechModelOptionsSchema,
+    });
+
+    let codec: XaiSpeechCodec = 'mp3';
+    if (['mp3', 'wav', 'pcm', 'mulaw', 'alaw'].includes(outputFormat)) {
+      codec = outputFormat as XaiSpeechCodec;
+    } else {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'outputFormat',
+        details: `Unsupported output format: ${outputFormat}. Using mp3 instead.`,
+      });
+    }
+
+    if (instructions != null) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'instructions',
+        details:
+          'xAI speech models do not support the `instructions` option. ' +
+          'Use xAI speech tags in `text` to control delivery.',
+      });
+    }
+
+    const output_format: {
+      codec: XaiSpeechCodec;
+      sample_rate?: number;
+      bit_rate?: number;
+    } = {
+      codec,
+    };
+
+    if (xaiOptions?.sampleRate != null) {
+      output_format.sample_rate = xaiOptions.sampleRate;
+    }
+
+    if (xaiOptions?.bitRate != null) {
+      if (codec === 'mp3') {
+        output_format.bit_rate = xaiOptions.bitRate;
+      } else {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'providerOptions',
+          details:
+            'xAI `bitRate` is supported only for mp3 output. It was ignored.',
+        });
+      }
+    }
+
+    const requestBody = {
+      text,
+      voice_id: voice,
+      language,
+      output_format,
+      speed,
+      optimize_streaming_latency: xaiOptions?.optimizeStreamingLatency,
+      text_normalization: xaiOptions?.textNormalization,
+    };
+
+    return { requestBody, warnings };
+  }
+
+  async doGenerate(
+    options: Parameters<SpeechModelV4['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<SpeechModelV4['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { requestBody, warnings } = await this.getArgs(options);
+
+    const {
+      value: audio,
+      responseHeaders,
+      rawValue: rawResponse,
+    } = await postJsonToApi({
+      url: `${this.config.baseURL}/tts`,
+      headers: combineHeaders(
+        this.config.headers ? await resolve(this.config.headers) : undefined,
+        options.headers,
+      ),
+      body: requestBody,
+      failedResponseHandler: xaiFailedResponseHandler,
+      successfulResponseHandler: createBinaryResponseHandler(),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      audio,
+      warnings,
+      request: {
+        body: JSON.stringify(requestBody),
+      },
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawResponse,
+      },
+    };
+  }
+}

package/src/xai-transcription-model-options.ts

@@ -0,0 +1,70 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const xaiTranscriptionModelOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * Audio encoding for raw, headerless input audio.
+       */
+      audioFormat: z.enum(['pcm', 'mulaw', 'alaw']).nullish(),
+
+      /**
+       * Sample rate of the input audio in Hz.
+       */
+      sampleRate: z
+        .union([
+          z.literal(8000),
+          z.literal(16000),
+          z.literal(22050),
+          z.literal(24000),
+          z.literal(44100),
+          z.literal(48000),
+        ])
+        .nullish(),
+
+      /**
+       * Language code used for inverse text normalization.
+       */
+      language: z.string().nullish(),
+
+      /**
+       * Enable inverse text normalization. Requires `language`.
+       */
+      format: z.boolean().nullish(),
+
+      /**
+       * Enable per-channel transcription for multichannel audio.
+       */
+      multichannel: z.boolean().nullish(),
+
+      /**
+       * Number of interleaved audio channels.
+       */
+      channels: z.number().int().min(2).max(8).nullish(),
+
+      /**
+       * Enable speaker diarization.
+       */
+      diarize: z.boolean().nullish(),
+
+      /**
+       * Terms to bias transcription toward.
+       */
+      keyterm: z.union([z.string(), z.array(z.string())]).nullish(),
+
+      /**
+       * Include filler words such as "uh" and "um" in the transcript.
+       */
+      fillerWords: z.boolean().nullish(),
+    }),
+  ),
+);
+
+export type XaiTranscriptionModelOptions = InferSchema<
+  typeof xaiTranscriptionModelOptionsSchema
+>;

package/src/xai-transcription-model.ts

@@ -0,0 +1,166 @@
+import type { SharedV4Warning, TranscriptionModelV4 } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createJsonResponseHandler,
+  mediaTypeToExtension,
+  parseProviderOptions,
+  postFormDataToApi,
+  serializeModelOptions,
+  WORKFLOW_DESERIALIZE,
+  WORKFLOW_SERIALIZE,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { xaiFailedResponseHandler } from './xai-error';
+import { xaiTranscriptionModelOptionsSchema } from './xai-transcription-model-options';
+
+interface XaiTranscriptionModelConfig {
+  provider: string;
+  baseURL: string | undefined;
+  headers?: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class XaiTranscriptionModel implements TranscriptionModelV4 {
+  readonly specificationVersion = 'v4';
+
+  static [WORKFLOW_SERIALIZE](model: XaiTranscriptionModel) {
+    return serializeModelOptions({
+      modelId: model.modelId,
+      config: model.config,
+    });
+  }
+
+  static [WORKFLOW_DESERIALIZE](options: {
+    modelId: '';
+    config: XaiTranscriptionModelConfig;
+  }) {
+    return new XaiTranscriptionModel(options.modelId, options.config);
+  }
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: '',
+    private readonly config: XaiTranscriptionModelConfig,
+  ) {}
+
+  private async getArgs({
+    audio,
+    mediaType,
+    providerOptions,
+  }: Parameters<TranscriptionModelV4['doGenerate']>[0]) {
+    const warnings: SharedV4Warning[] = [];
+    const xaiOptions = await parseProviderOptions({
+      provider: 'xai',
+      providerOptions,
+      schema: xaiTranscriptionModelOptionsSchema,
+    });
+
+    const formData = new FormData();
+    const transcriptionOptions = {
+      audio_format: xaiOptions?.audioFormat,
+      sample_rate: xaiOptions?.sampleRate,
+      language: xaiOptions?.language,
+      format: xaiOptions?.format,
+      multichannel: xaiOptions?.multichannel,
+      channels: xaiOptions?.channels,
+      diarize: xaiOptions?.diarize,
+      filler_words: xaiOptions?.fillerWords,
+    };
+
+    for (const [key, value] of Object.entries(transcriptionOptions)) {
+      if (value != null) {
+        formData.append(key, String(value));
+      }
+    }
+
+    if (xaiOptions?.keyterm != null) {
+      const keyterms = Array.isArray(xaiOptions.keyterm)
+        ? xaiOptions.keyterm
+        : [xaiOptions.keyterm];
+
+      for (const keyterm of keyterms) {
+        formData.append('keyterm', keyterm);
+      }
+    }
+
+    const blob =
+      audio instanceof Uint8Array
+        ? new Blob([audio])
+        : new Blob([convertBase64ToUint8Array(audio)]);
+    const fileExtension = mediaTypeToExtension(mediaType);
+
+    // xAI requires `file` to be the final multipart field.
+    formData.append(
+      'file',
+      new File([blob], 'audio', { type: mediaType }),
+      `audio.${fileExtension}`,
+    );
+
+    return { formData, warnings };
+  }
+
+  async doGenerate(
+    options: Parameters<TranscriptionModelV4['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<TranscriptionModelV4['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { formData, warnings } = await this.getArgs(options);
+
+    const {
+      value: response,
+      responseHeaders,
+      rawValue: rawResponse,
+    } = await postFormDataToApi({
+      url: `${this.config.baseURL ?? 'https://api.x.ai/v1'}/stt`,
+      headers: combineHeaders(this.config.headers?.(), options.headers),
+      formData,
+      failedResponseHandler: xaiFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        xaiTranscriptionResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      text: response.text,
+      segments:
+        response.words?.map(word => ({
+          text: word.text,
+          startSecond: word.start,
+          endSecond: word.end,
+        })) ?? [],
+      language: response.language || undefined,
+      durationInSeconds: response.duration ?? undefined,
+      warnings,
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawResponse,
+      },
+    };
+  }
+}
+
+const xaiTranscriptionResponseSchema = z.object({
+  text: z.string(),
+  language: z.string().nullish(),
+  duration: z.number().nullish(),
+  words: z
+    .array(
+      z.object({
+        text: z.string(),
+        start: z.number(),
+        end: z.number(),
+      }),
+    )
+    .nullish(),
+});

package/src/xai-video-model-options.ts

@@ -0,0 +1,145 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+const nonEmptyStringSchema = z.string().min(1);
+const resolutionSchema = z.enum(['480p', '720p']);
+const modeSchema = z.enum(['edit-video', 'extend-video', 'reference-to-video']);
+
+export type XaiVideoMode = z.infer<typeof modeSchema>;
+type XaiVideoResolution = z.infer<typeof resolutionSchema>;
+
+interface XaiVideoSharedOptions {
+  pollIntervalMs?: number | null;
+  pollTimeoutMs?: number | null;
+  resolution?: XaiVideoResolution | null;
+}
+
+interface XaiVideoEditModeOptions extends XaiVideoSharedOptions {
+  /**
+   * Select edit-video mode explicitly for best autocomplete and narrowing.
+   */
+  mode: 'edit-video';
+  /** Source video URL to edit. */
+  videoUrl: string;
+}
+
+interface XaiVideoExtendModeOptions extends XaiVideoSharedOptions {
+  /**
+   * Select extend-video mode explicitly for best autocomplete and narrowing.
+   */
+  mode: 'extend-video';
+  /** Source video URL to extend from its last frame. */
+  videoUrl: string;
+}
+
+interface XaiVideoReferenceToVideoOptions extends XaiVideoSharedOptions {
+  /**
+   * Select reference-to-video mode explicitly for best autocomplete and narrowing.
+   */
+  mode: 'reference-to-video';
+  /** Reference image URLs (1-7) for R2V generation. */
+  referenceImageUrls: string[];
+}
+
+interface XaiVideoGenerationOptions extends XaiVideoSharedOptions {
+  mode?: undefined;
+  videoUrl?: undefined;
+  referenceImageUrls?: undefined;
+}
+
+interface XaiLegacyEditVideoOptions extends XaiVideoSharedOptions {
+  /**
+   * Legacy backward-compatible shape: omitting `mode` while providing
+   * `videoUrl` behaves like edit-video.
+   */
+  mode?: undefined;
+  videoUrl: string;
+}
+
+interface XaiLegacyReferenceToVideoOptions extends XaiVideoSharedOptions {
+  /**
+   * Legacy backward-compatible shape: omitting `mode` while providing
+   * `referenceImageUrls` behaves like reference-to-video.
+   */
+  mode?: undefined;
+  referenceImageUrls: string[];
+}
+
+/**
+ * Provider options for xAI video generation.
+ *
+ * Use the `mode` option to select the operation:
+ *
+ * - `'edit-video'`         + `videoUrl`           -- video editing   (`POST /v1/videos/edits`)
+ * - `'extend-video'`       + `videoUrl`           -- video extension (`POST /v1/videos/extensions`)
+ * - `'reference-to-video'` + `referenceImageUrls` -- R2V generation  (`POST /v1/videos/generations`)
+ * - no `mode`                                     -- standard generation from text prompts or image input
+ *
+ * Runtime remains backward compatible with legacy auto-detected provider
+ * options, but the public TypeScript type is intentionally explicit so editors
+ * can suggest valid modes and flag invalid field combinations.
+ */
+export type XaiVideoModelOptions =
+  | XaiVideoGenerationOptions
+  | XaiVideoEditModeOptions
+  | XaiVideoExtendModeOptions
+  | XaiVideoReferenceToVideoOptions
+  | XaiLegacyEditVideoOptions
+  | XaiLegacyReferenceToVideoOptions;
+
+// ── Runtime schemas ───────────────────────────────────────────────────
+const baseFields = {
+  pollIntervalMs: z.number().positive().nullish(),
+  pollTimeoutMs: z.number().positive().nullish(),
+  resolution: resolutionSchema.nullish(),
+};
+
+const editVideoSchema = z.object({
+  ...baseFields,
+  mode: z.literal('edit-video'),
+  videoUrl: nonEmptyStringSchema,
+  referenceImageUrls: z.undefined().optional(),
+});
+
+const extendVideoSchema = z.object({
+  ...baseFields,
+  mode: z.literal('extend-video'),
+  videoUrl: nonEmptyStringSchema,
+  referenceImageUrls: z.undefined().optional(),
+});
+
+const referenceToVideoSchema = z.object({
+  ...baseFields,
+  mode: z.literal('reference-to-video'),
+  referenceImageUrls: z.array(nonEmptyStringSchema).min(1).max(7),
+  videoUrl: z.undefined().optional(),
+});
+
+const autoDetectSchema = z.object({
+  ...baseFields,
+  mode: z.undefined().optional(),
+  videoUrl: nonEmptyStringSchema.optional(),
+  referenceImageUrls: z.array(nonEmptyStringSchema).min(1).max(7).optional(),
+});
+
+export const xaiVideoModelOptions = z.union([
+  editVideoSchema,
+  extendVideoSchema,
+  referenceToVideoSchema,
+  autoDetectSchema,
+]);
+
+const runtimeSchema = z
+  .object({
+    mode: modeSchema.optional(),
+    videoUrl: nonEmptyStringSchema.optional(),
+    referenceImageUrls: z.array(nonEmptyStringSchema).min(1).max(7).optional(),
+    ...baseFields,
+  })
+  .passthrough();
+
+export type XaiParsedVideoModelOptions = z.infer<typeof runtimeSchema>;
+
+export const xaiVideoModelOptionsSchema = lazySchema(() =>
+  zodSchema(runtimeSchema),
+);