@ai-sdk/xai 5.0.13 → 5.0.15

package/docs/01-xai.mdx

@@ -828,11 +828,13 @@ const { traceId, duration, audioTimestamps } = result.providerMetadata.xai;
 ## Transcription Models
 
 You can create models that call the [xAI Speech to Text API](https://docs.x.ai/developers/model-capabilities/audio/speech-to-text)
-using the `.transcription()` factory method. xAI's batch transcription endpoint
-does not require a model identifier.
+using the `.transcription()` factory method. The model identifier is optional:
+pass `grok-voice-transcribe-2.0` to pin a model, or omit it to use xAI's
+default transcription model. `grok-voice-transcribe-1.0` is retired, and
+requests to it are routed to `grok-voice-transcribe-2.0`.
 
 ```ts
-const model = xai.transcription();
+const model = xai.transcription('grok-voice-transcribe-2.0');
 ```
 
 Use xAI transcription models with the `transcribe` function:
@@ -871,9 +873,13 @@ const result = await transcribe({
 });
 ```
 
-- **audioFormat** _`pcm` | `mulaw` | `alaw`_
+- **audioFormat** _`pcm` | `mulaw` | `alaw` | `opus`_
 
-  Audio encoding for raw, headerless input audio.
+  Input audio encoding for raw, headerless audio (`pcm`, `mulaw`, `alaw`).
+  Container formats such as Ogg/Opus are auto-detected, so do not set
+  `audioFormat` for them. `opus` is supported for streaming transcription only:
+  each audio chunk must be exactly one raw Opus packet (not Ogg), and an
+  `audio/opus` input audio type maps to `opus` automatically.
 
 - **sampleRate** _8000 | 16000 | 22050 | 24000 | 44100 | 48000_
 
@@ -907,6 +913,11 @@ const result = await transcribe({
 
   Includes filler words such as `uh` and `um` in the transcript.
 
+- **vadThreshold** _number_
+
+  Voice activity detection threshold. Range: 0.0-1.0. Defaults to `0.5` for
+  `transcribe` and `0.08` for streaming. `0` disables the filter.
+
 - **streaming** _object_
 
   Options for streaming speech-to-text over WebSocket. Use with `experimental_streamTranscribe`.
@@ -928,9 +939,10 @@ const result = await transcribe({
 
 ### Model Capabilities
 
-| Model     | Request/Response | Streaming | Word Timestamps | Diarization | Multichannel |
-| --------- | ---------------- | --------- | --------------- | ----------- | ------------ |
-| `default` | <Check />        | <Check /> | <Check />       | <Check />   | <Check />    |
+| Model                       | Request/Response | Streaming | Word Timestamps | Diarization | Multichannel |
+| --------------------------- | ---------------- | --------- | --------------- | ----------- | ------------ |
+| `default`                   | <Check />        | <Check /> | <Check />       | <Check />   | <Check />    |
+| `grok-voice-transcribe-2.0` | <Check />        | <Check /> | <Check />       | <Check />   | <Check />    |
 
 <Note>
   Word timestamps, diarization results, and segments are only returned on the
@@ -1053,22 +1065,29 @@ const { images } = await generateImage({
 });
 ```
 
-- **resolution** _'1k' | '2k'_
+- **resolution** _'1k' | '1.5k' | '2k'_
 
-  Output resolution. `1k` produces ~1024×1024 images, `2k` produces ~2048×2048
-  images (actual dimensions vary based on aspect ratio). Available for
-  `grok-imagine-image-pro`.
+  Output resolution: `1k` (default, ~1024×1024), `1.5k` (~1408×1408), or `2k`
+  (~2048×2048). Actual dimensions vary based on aspect ratio.
+  `grok-imagine-image` does not support `1.5k`.
 
-- **quality** _'low' | 'medium' | 'high'_
+- **quality** _'low' | 'medium' | 'high' | 'auto'_
 
-  Image quality level. Higher quality may increase generation time.
+  Image quality level. Only supported by `grok-imagine-image-2.0`, which accepts
+  `low`, `medium`, and `auto`. `auto` is the default when omitted: it serves
+  `low` for generation and `medium` for editing, billed at the quality served.
+  `high` is not documented by xAI but is still accepted by older models, and is
+  kept for backward compatibility.
 
 ### 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 />     |
-| `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 />     |
+| Model                    | Resolution         | Aspect Ratios                                                                                                              | Image Editing |
+| ------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `grok-imagine-image-2.0` | `1k`, `1.5k`, `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`, `21:9`, `5:2`, `auto` | <Check />     |
+| `grok-imagine-image-pro` | `1k`, `1.5k`, `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 />     |
+
+`grok-imagine-image-2.0` is xAI's latest image model.
 
 ## Video Models
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "5.0.13",
+  "version": "5.0.15",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -29,8 +29,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.20",
-    "@ai-sdk/provider-utils": "5.0.52"
+    "@ai-sdk/provider": "4.0.22",
+    "@ai-sdk/provider-utils": "5.0.54"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.3",

package/src/index.ts

@@ -17,7 +17,10 @@ export type {
   XaiVideoModelOptions as XaiVideoProviderOptions,
 } from './xai-video-model-options';
 export type { XaiSpeechModelOptions } from './xai-speech-model-options';
-export type { XaiTranscriptionModelOptions } from './xai-transcription-model-options';
+export type {
+  XaiTranscriptionModelId,
+  XaiTranscriptionModelOptions,
+} from './xai-transcription-model-options';
 export type { XaiFilesOptions } from './files/xai-files-options';
 export { createXai, xai } from './xai-provider';
 export type { XaiProvider, XaiProviderSettings } from './xai-provider';

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

@@ -4,8 +4,8 @@ export const xaiImageModelOptions = z.object({
   aspect_ratio: z.string().optional(),
   output_format: z.string().optional(),
   sync_mode: z.boolean().optional(),
-  resolution: z.enum(['1k', '2k']).optional(),
-  quality: z.enum(['low', 'medium', 'high']).optional(),
+  resolution: z.enum(['1k', '1.5k', '2k']).optional(),
+  quality: z.enum(['low', 'medium', 'high', 'auto']).optional(),
   user: z.string().optional(),
 });
 

package/src/xai-image-model.ts

@@ -28,15 +28,18 @@ interface XaiImageModelConfig {
   };
 }
 
+const fileInputModelIds: ReadonlySet<string> = new Set<XaiImageModelId>([
+  'grok-imagine-image',
+  'grok-imagine-image-2.0',
+  'grok-imagine-image-pro',
+]);
+
 export class XaiImageModel implements ImageModelV4 {
   readonly specificationVersion = 'v4';
   readonly maxImagesPerCall = 3;
 
   get supportsFileInputs(): boolean | undefined {
-    return this.modelId === 'grok-imagine-image' ||
-      this.modelId === 'grok-imagine-image-pro'
-      ? true
-      : undefined;
+    return fileInputModelIds.has(this.modelId) ? true : undefined;
   }
 
   get supportsMaskInputs(): boolean | undefined {

package/src/xai-image-settings.ts

@@ -1,4 +1,5 @@
 export type XaiImageModelId =
   | 'grok-imagine-image'
+  | 'grok-imagine-image-2.0'
   | 'grok-imagine-image-pro'
   | (string & {});

package/src/xai-provider.ts

@@ -32,6 +32,7 @@ import { XaiVideoModel } from './xai-video-model';
 import type { XaiVideoModelId } from './xai-video-settings';
 import { XaiSpeechModel } from './xai-speech-model';
 import { XaiTranscriptionModel } from './xai-transcription-model';
+import type { XaiTranscriptionModelId } from './xai-transcription-model-options';
 
 export interface XaiProvider extends ProviderV4 {
   (modelId: XaiResponsesModelId): LanguageModelV4;
@@ -88,13 +89,15 @@ export interface XaiProvider extends ProviderV4 {
 
   /**
    * Creates an xAI model for speech-to-text transcription.
+   * When `modelId` is omitted, xAI's default transcription model is used.
    */
-  transcription(): TranscriptionModelV4;
+  transcription(modelId?: XaiTranscriptionModelId): TranscriptionModelV4;
 
   /**
    * Creates an xAI model for speech-to-text transcription.
+   * When `modelId` is omitted, xAI's default transcription model is used.
    */
-  transcriptionModel(): TranscriptionModelV4;
+  transcriptionModel(modelId?: XaiTranscriptionModelId): TranscriptionModelV4;
 
   /**
    * Returns the xAI files interface for uploading files.
@@ -204,8 +207,8 @@ export function createXai(options: XaiProviderSettings = {}): XaiProvider {
     });
   };
 
-  const createTranscriptionModel = () => {
-    return new XaiTranscriptionModel('', {
+  const createTranscriptionModel = (modelId: XaiTranscriptionModelId = '') => {
+    return new XaiTranscriptionModel(modelId, {
       provider: 'xai.transcription',
       baseURL,
       headers: getHeaders,

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

@@ -5,13 +5,20 @@ import {
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
+export type XaiTranscriptionModelId =
+  | 'grok-voice-transcribe-2.0'
+  | (string & {});
+
 export const xaiTranscriptionModelOptionsSchema = lazySchema(() =>
   zodSchema(
     z.object({
       /**
-       * Audio encoding for raw, headerless input audio.
+       * Input audio encoding for raw, headerless audio: `pcm`, `mulaw`, or
+       * `alaw`. Container formats such as Ogg/Opus are auto-detected, so do
+       * not set this for them. `opus` is for streaming only, with one raw Opus
+       * packet per chunk.
        */
-      audioFormat: z.enum(['pcm', 'mulaw', 'alaw']).nullish(),
+      audioFormat: z.enum(['pcm', 'mulaw', 'alaw', 'opus']).nullish(),
 
       /**
        * Sample rate of the input audio in Hz.
@@ -62,6 +69,12 @@ export const xaiTranscriptionModelOptionsSchema = lazySchema(() =>
        */
       fillerWords: z.boolean().nullish(),
 
+      /**
+       * Voice activity detection threshold between 0 and 1. Defaults to 0.5
+       * for `transcribe` and 0.08 for streaming. 0 disables the filter.
+       */
+      vadThreshold: z.number().min(0).max(1).optional(),
+
       /**
        * Options for streaming speech-to-text over WebSocket.
        */

package/src/xai-transcription-model.ts

@@ -27,6 +27,7 @@ import { z } from 'zod/v4';
 import { xaiFailedResponseHandler } from './xai-error';
 import {
   xaiTranscriptionModelOptionsSchema,
+  type XaiTranscriptionModelId,
   type XaiTranscriptionModelOptions,
 } from './xai-transcription-model-options';
 
@@ -64,7 +65,7 @@ export class XaiTranscriptionModel implements TranscriptionModelV4 {
   }
 
   static [WORKFLOW_DESERIALIZE](options: {
-    modelId: '';
+    modelId: XaiTranscriptionModelId;
     config: XaiTranscriptionModelConfig;
   }) {
     return new XaiTranscriptionModel(options.modelId, options.config);
@@ -75,7 +76,7 @@ export class XaiTranscriptionModel implements TranscriptionModelV4 {
   }
 
   constructor(
-    readonly modelId: '',
+    readonly modelId: XaiTranscriptionModelId,
     private readonly config: XaiTranscriptionModelConfig,
   ) {}
 
@@ -92,32 +93,11 @@ export class XaiTranscriptionModel implements TranscriptionModelV4 {
     });
 
     const formData = new FormData();
-    const transcriptionOptions = {
+    appendXaiSttParams(formData, {
+      ...getXaiSttParams(this.modelId, xaiOptions),
       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
@@ -208,20 +188,21 @@ export class XaiTranscriptionModel implements TranscriptionModelV4 {
 
     if (
       xaiOptions?.audioFormat == null &&
-      !isKnownInputAudioFormat(options.inputAudioFormat.type)
+      !inputAudioFormatEncodings.has(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, ` +
+          `Use ${[...inputAudioFormatEncodings.keys()].join(', ')}, ` +
           `or set providerOptions.xai.audioFormat explicitly.`,
       });
     }
 
     const url = buildXaiStreamingTranscriptionUrl({
       baseURL: this.config.baseURL ?? 'https://api.x.ai/v1',
+      modelId: this.modelId,
       inputAudioFormat: options.inputAudioFormat,
       providerOptions: xaiOptions,
     });
@@ -466,85 +447,77 @@ function createXaiStreamingTranscriptionStream({
 
 function buildXaiStreamingTranscriptionUrl({
   baseURL,
+  modelId,
   inputAudioFormat,
   providerOptions,
 }: {
   baseURL: string;
+  modelId: XaiTranscriptionModelId;
   inputAudioFormat: TranscriptionModelV4StreamOptions['inputAudioFormat'];
   providerOptions: XaiTranscriptionModelOptions | undefined;
 }) {
   const url = toWebSocketUrl(`${baseURL}/stt`);
-
-  appendSearchParam(
-    url,
-    'sample_rate',
-    providerOptions?.sampleRate ?? inputAudioFormat.rate,
-  );
-  appendSearchParam(
-    url,
-    'encoding',
-    providerOptions?.audioFormat ??
-      encodingFromInputAudioFormat(inputAudioFormat.type),
-  );
-  appendSearchParam(url, 'language', providerOptions?.language);
-  appendSearchParam(url, 'diarize', providerOptions?.diarize);
-  appendSearchParam(url, 'filler_words', providerOptions?.fillerWords);
-  appendSearchParam(url, 'multichannel', providerOptions?.multichannel);
-  appendSearchParam(url, 'channels', providerOptions?.channels);
-  appendSearchParam(
-    url,
-    'interim_results',
-    providerOptions?.streaming?.interimResults,
-  );
-  appendSearchParam(
-    url,
-    'endpointing',
-    providerOptions?.streaming?.endpointing,
-  );
-  appendSearchParam(url, 'smart_turn', providerOptions?.streaming?.smartTurn);
-  appendSearchParam(
-    url,
-    'smart_turn_timeout',
-    providerOptions?.streaming?.smartTurnTimeout,
-  );
-
-  if (providerOptions?.keyterm != null) {
-    const keyterms = Array.isArray(providerOptions.keyterm)
-      ? providerOptions.keyterm
-      : [providerOptions.keyterm];
-    for (const keyterm of keyterms) {
-      url.searchParams.append('keyterm', keyterm);
-    }
-  }
+  const params = getXaiSttParams(modelId, providerOptions);
+
+  appendXaiSttParams(url.searchParams, {
+    ...params,
+    sample_rate: params.sample_rate ?? inputAudioFormat.rate,
+    encoding:
+      providerOptions?.audioFormat ??
+      inputAudioFormatEncodings.get(inputAudioFormat.type) ??
+      'pcm',
+    interim_results: providerOptions?.streaming?.interimResults,
+    endpointing: providerOptions?.streaming?.endpointing,
+    smart_turn: providerOptions?.streaming?.smartTurn,
+    smart_turn_timeout: providerOptions?.streaming?.smartTurnTimeout,
+  });
 
   return url;
 }
 
-function appendSearchParam(
-  url: URL,
-  key: string,
-  value: string | number | boolean | null | undefined,
+function getXaiSttParams(
+  modelId: XaiTranscriptionModelId,
+  options: XaiTranscriptionModelOptions | undefined,
 ) {
-  if (value != null) {
-    url.searchParams.set(key, String(value));
-  }
-}
-
-function isKnownInputAudioFormat(type: string): boolean {
-  return type === 'audio/pcm' || type === 'audio/pcmu' || type === 'audio/pcma';
+  return {
+    model: modelId || undefined,
+    sample_rate: options?.sampleRate,
+    language: options?.language,
+    multichannel: options?.multichannel,
+    channels: options?.channels,
+    diarize: options?.diarize,
+    filler_words: options?.fillerWords,
+    vad_threshold: options?.vadThreshold,
+    keyterm: options?.keyterm,
+  };
 }
 
-function encodingFromInputAudioFormat(type: string): 'pcm' | 'mulaw' | 'alaw' {
-  switch (type) {
-    case 'audio/pcmu':
-      return 'mulaw';
-    case 'audio/pcma':
-      return 'alaw';
-    default:
-      return 'pcm';
+function appendXaiSttParams(
+  target: { append(name: string, value: string): void },
+  params: Record<
+    string,
+    string | number | boolean | string[] | null | undefined
+  >,
+) {
+  for (const [key, value] of Object.entries(params)) {
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (item != null) {
+        target.append(key, String(item));
+      }
+    }
   }
 }
 
+const inputAudioFormatEncodings = new Map<
+  string,
+  NonNullable<XaiTranscriptionModelOptions['audioFormat']>
+>([
+  ['audio/pcm', 'pcm'],
+  ['audio/pcmu', 'mulaw'],
+  ['audio/pcma', 'alaw'],
+  ['audio/opus', 'opus'],
+]);
+
 function channelId(channelIndex: number | undefined): string | undefined {
   return channelIndex == null ? undefined : `channel-${channelIndex}`;
 }