TanStack
diff --git a/‎.changeset/grok-audio-speech-support.md‎
Lines changed: 13 additions & 0 deletions b/‎.changeset/grok-audio-speech-support.md‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎examples/ts-react-chat/src/lib/audio-providers.ts‎
Lines changed: 21 additions & 2 deletions b/‎examples/ts-react-chat/src/lib/audio-providers.ts‎
Lines changed: 21 additions & 2 deletions
diff --git a/‎examples/ts-react-chat/src/lib/server-audio-adapters.ts‎
Lines changed: 67 additions & 7 deletions b/‎examples/ts-react-chat/src/lib/server-audio-adapters.ts‎
Lines changed: 67 additions & 7 deletions
diff --git a/‎examples/ts-react-chat/src/lib/server-fns.ts‎
Lines changed: 108 additions & 7 deletions b/‎examples/ts-react-chat/src/lib/server-fns.ts‎
Lines changed: 108 additions & 7 deletions
@@ -0,0 +1,13 @@
+---
+'@tanstack/ai-grok': minor
+---
+
+feat(ai-grok): add audio and speech adapters for xAI
+
+Add three new tree-shakeable adapters that wrap xAI's audio APIs:
+
+- `grokSpeech` / `createGrokSpeech` — text-to-speech via `POST /v1/tts`. Supports the 5 xAI voices (`eve`, `ara`, `rex`, `sal`, `leo`), MP3/WAV/PCM/μ-law/A-law codecs, and the `language`, `sample_rate`, `bit_rate`, `optimize_streaming_latency`, `text_normalization` provider options.
+- `grokTranscription` / `createGrokTranscription` — speech-to-text via `POST /v1/stt`. Passes through `language`, `diarize`, `multichannel`, `channels`, `audio_format`, and `sample_rate`; maps xAI's word-level timestamps to `TranscriptionResult.words`.
+- `grokRealtime` / `grokRealtimeToken` — Voice Agent (realtime) adapter for `wss://api.x.ai/v1/realtime` with ephemeral tokens via `/v1/realtime/client_secrets`. Supports the `grok-voice-fast-1.0` and `grok-voice-think-fast-1.0` models.
+
+New model identifier exports: `GROK_TTS_MODELS`, `GROK_TRANSCRIPTION_MODELS`, `GROK_REALTIME_MODELS` and their corresponding types.
@@ -6,7 +6,7 @@
  * and audio generation flows.
  */
 
-export type SpeechProviderId = 'openai' | 'gemini' | 'fal'
+export type SpeechProviderId = 'openai' | 'gemini' | 'fal' | 'grok'
 
 export interface SpeechProviderConfig {
   id: SpeechProviderId
@@ -55,9 +55,22 @@ export const SPEECH_PROVIDERS: ReadonlyArray<SpeechProviderConfig> = [
     ],
     placeholder: 'Enter text to synthesize with Fal Kokoro…',
   },
+  {
+    id: 'grok',
+    label: 'Grok TTS',
+    model: 'grok-tts',
+    voices: [
+      { id: 'eve', label: 'Eve' },
+      { id: 'ara', label: 'Ara' },
+      { id: 'rex', label: 'Rex' },
+      { id: 'sal', label: 'Sal' },
+      { id: 'leo', label: 'Leo' },
+    ],
+    placeholder: 'Enter text for Grok speech…',
+  },
 ]
 
-export type TranscriptionProviderId = 'openai' | 'fal'
+export type TranscriptionProviderId = 'openai' | 'fal' | 'grok'
 
 export interface TranscriptionProviderConfig {
   id: TranscriptionProviderId
@@ -80,6 +93,12 @@ export const TRANSCRIPTION_PROVIDERS: ReadonlyArray<TranscriptionProviderConfig>
       model: 'fal-ai/whisper',
       description: 'Fal-hosted Whisper with word-level timestamps.',
     },
+    {
+      id: 'grok',
+      label: 'Grok STT',
+      model: 'grok-stt',
+      description: 'xAI speech-to-text with word-level timestamps.',
+    },
   ]
 
 export type AudioProviderId = 'gemini-lyria' | 'fal-audio' | 'fal-sfx'
 
@@ -8,6 +8,7 @@
 import { openaiSpeech, openaiTranscription } from '@tanstack/ai-openai'
 import { geminiAudio, geminiSpeech } from '@tanstack/ai-gemini'
 import { falAudio, falSpeech, falTranscription } from '@tanstack/ai-fal'
+import { grokSpeech, grokTranscription } from '@tanstack/ai-grok'
 import type {
   AnyAudioAdapter,
   AnyTranscriptionAdapter,
@@ -27,7 +28,12 @@ function findConfig<T extends { id: string }>(
   id: string,
 ): T {
   const match = list.find((entry) => entry.id === id)
-  if (!match) throw new Error(`Unknown provider: ${id}`)
+  if (!match) {
+    throw new UnknownProviderError(
+      id,
+      list.map((entry) => entry.id),
+    )
+  }
   return match
 }
 
@@ -40,6 +46,8 @@ export function buildSpeechAdapter(provider: SpeechProviderId): AnyTTSAdapter {
       return geminiSpeech(config.model as 'gemini-2.5-flash-preview-tts')
     case 'fal':
       return falSpeech(config.model)
+    case 'grok':
+      return grokSpeech(config.model as 'grok-tts')
   }
 }
 
@@ -52,6 +60,8 @@ export function buildTranscriptionAdapter(
       return openaiTranscription(config.model as 'whisper-1')
     case 'fal':
       return falTranscription(config.model)
+    case 'grok':
+      return grokTranscription(config.model as 'grok-stt')
   }
 }
 
@@ -72,15 +82,65 @@ export function buildAudioAdapter(
   }
 }
 
+/**
+ * Thrown when a caller supplies a `modelOverride` that is not present in the
+ * provider's allowed model list. HTTP routes map this to a 400 response so the
+ * user sees a clear rejection instead of silently getting output from the
+ * default model.
+ */
+export class InvalidModelOverrideError extends Error {
+  readonly code = 'invalid_model_override' as const
+  readonly providerId: string
+  readonly requestedModel: string
+  readonly allowedModels: ReadonlyArray<string>
+
+  constructor(
+    providerId: string,
+    requestedModel: string,
+    allowedModels: ReadonlyArray<string>,
+  ) {
+    super(
+      `Invalid model override "${requestedModel}" for provider "${providerId}". Allowed models: ${
+        allowedModels.length > 0 ? allowedModels.join(', ') : '(none)'
+      }`,
+    )
+    this.name = 'InvalidModelOverrideError'
+    this.providerId = providerId
+    this.requestedModel = requestedModel
+    this.allowedModels = allowedModels
+  }
+}
+
+/**
+ * Thrown when `findConfig` is called with a provider id that isn't in the
+ * allowed list. In practice the route-level Zod enum schema already rejects
+ * unknown providers before we ever reach this builder, so this is
+ * defense-in-depth for callers that bypass Zod validation (e.g. server-fns
+ * whose input schemas could drift from the provider registries).
+ */
+export class UnknownProviderError extends Error {
+  readonly code = 'unknown_provider' as const
+  readonly providerId: string
+  readonly allowedProviders: ReadonlyArray<string>
+
+  constructor(providerId: string, allowedProviders: ReadonlyArray<string>) {
+    super(
+      `Unknown provider "${providerId}". Allowed providers: ${
+        allowedProviders.length > 0 ? allowedProviders.join(', ') : '(none)'
+      }`,
+    )
+    this.name = 'UnknownProviderError'
+    this.providerId = providerId
+    this.allowedProviders = allowedProviders
+  }
+}
+
 function resolveModel(
   config: (typeof AUDIO_PROVIDERS)[number],
   modelOverride: string | undefined,
 ): string {
   if (!modelOverride) return config.model
-  const allowed = config.models?.some((m) => m.id === modelOverride)
-  if (allowed) return modelOverride
-  console.warn(
-    `[audio] rejected model override "${modelOverride}" for provider "${config.id}"; falling back to "${config.model}"`,
-  )
-  return config.model
+  const allowedModels = config.models?.map((m) => m.id) ?? []
+  if (allowedModels.includes(modelOverride)) return modelOverride
+  throw new InvalidModelOverrideError(config.id, modelOverride, allowedModels)
 }
@@ -12,14 +12,67 @@ import {
 } from '@tanstack/ai'
 import { openaiImage, openaiSummarize, openaiVideo } from '@tanstack/ai-openai'
 import {
+  InvalidModelOverrideError,
+  UnknownProviderError,
   buildAudioAdapter,
   buildSpeechAdapter,
   buildTranscriptionAdapter,
 } from './server-audio-adapters'
 
-const SPEECH_PROVIDER_SCHEMA = z.enum(['openai', 'gemini', 'fal']).optional()
+/**
+ * Server-fn error with a stable `code` property clients can switch on.
+ *
+ * TanStack Start's `createServerFn` surfaces thrown errors as a generic 500
+ * without a structured payload. We can't influence the status code from here,
+ * so we attach a `code` field the client can read to distinguish well-known
+ * failure modes (invalid_model_override, unknown_provider) from truly
+ * unexpected errors.
+ */
+class ServerFnError extends Error {
+  readonly code: string
+  readonly details?: Record<string, unknown>
 
-const TRANSCRIPTION_PROVIDER_SCHEMA = z.enum(['openai', 'fal']).optional()
+  constructor(
+    code: string,
+    message: string,
+    details?: Record<string, unknown>,
+  ) {
+    super(message)
+    this.name = 'ServerFnError'
+    this.code = code
+    this.details = details
+  }
+}
+
+/**
+ * Translate the typed audio-adapter errors into a `ServerFnError` with a stable
+ * `code`. Any other error is re-thrown untouched so the framework's default
+ * 500 path handles it.
+ */
+function rethrowAudioAdapterError(err: unknown): never {
+  if (err instanceof InvalidModelOverrideError) {
+    throw new ServerFnError('invalid_model_override', err.message, {
+      providerId: err.providerId,
+      requestedModel: err.requestedModel,
+      allowedModels: err.allowedModels,
+    })
+  }
+  if (err instanceof UnknownProviderError) {
+    throw new ServerFnError('unknown_provider', err.message, {
+      providerId: err.providerId,
+      allowedProviders: err.allowedProviders,
+    })
+  }
+  throw err
+}
+
+const SPEECH_PROVIDER_SCHEMA = z
+  .enum(['openai', 'gemini', 'fal', 'grok'])
+  .optional()
+
+const TRANSCRIPTION_PROVIDER_SCHEMA = z
+  .enum(['openai', 'fal', 'grok'])
+  .optional()
 
 const AUDIO_PROVIDER_SCHEMA = z
   .enum(['gemini-lyria', 'fal-audio', 'fal-sfx'])
@@ -56,8 +109,17 @@ export const generateSpeechFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(async ({ data }) => {
+    // `buildSpeechAdapter` can throw `UnknownProviderError` (defense-in-depth;
+    // Zod should catch this first). Translate into a `ServerFnError` so
+    // clients can distinguish it from a generic failure via the stable `code`.
+    let adapter
+    try {
+      adapter = buildSpeechAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return generateSpeech({
-      adapter: buildSpeechAdapter(data.provider ?? 'openai'),
+      adapter,
       text: data.text,
       voice: data.voice,
       format: data.format,
@@ -73,8 +135,18 @@ export const transcribeFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(async ({ data }) => {
+    // `buildTranscriptionAdapter` can throw `UnknownProviderError`
+    // (defense-in-depth; Zod should catch this first). Translate into a
+    // `ServerFnError` so clients can distinguish it from a generic failure
+    // via the stable `code`.
+    let adapter
+    try {
+      adapter = buildTranscriptionAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return generateTranscription({
-      adapter: buildTranscriptionAdapter(data.provider ?? 'openai'),
+      adapter,
       audio: data.audio,
       language: data.language,
     })
@@ -90,8 +162,18 @@ export const generateAudioFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(async ({ data }) => {
+    // `buildAudioAdapter` can throw `InvalidModelOverrideError` (unknown
+    // model id) or `UnknownProviderError` (defense-in-depth; Zod should
+    // catch this first). Translate both into a `ServerFnError` so clients
+    // can distinguish them from a generic failure via the stable `code`.
+    let adapter
+    try {
+      adapter = buildAudioAdapter(data.provider ?? 'gemini-lyria', data.model)
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return generateAudio({
-      adapter: buildAudioAdapter(data.provider ?? 'gemini-lyria', data.model),
+      adapter,
       prompt: data.prompt,
       duration: data.duration,
     })
@@ -195,9 +277,18 @@ export const generateSpeechStreamFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(({ data }) => {
+    // `buildSpeechAdapter` can throw `UnknownProviderError` (defense-in-depth;
+    // Zod should catch this first). Translate into a `ServerFnError` so
+    // clients can distinguish it from a generic failure via the stable `code`.
+    let adapter
+    try {
+      adapter = buildSpeechAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return toServerSentEventsResponse(
       generateSpeech({
-        adapter: buildSpeechAdapter(data.provider ?? 'openai'),
+        adapter,
         text: data.text,
         voice: data.voice,
         format: data.format,
@@ -215,9 +306,19 @@ export const transcribeStreamFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(({ data }) => {
+    // `buildTranscriptionAdapter` can throw `UnknownProviderError`
+    // (defense-in-depth; Zod should catch this first). Translate into a
+    // `ServerFnError` so clients can distinguish it from a generic failure
+    // via the stable `code`.
+    let adapter
+    try {
+      adapter = buildTranscriptionAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return toServerSentEventsResponse(
       generateTranscription({
-        adapter: buildTranscriptionAdapter(data.provider ?? 'openai'),
+        adapter,
         audio: data.audio,
         language: data.language,
         stream: true,