@tanstack/ai-fal 0.6.17 → 0.7.0

package/dist/esm/utils/client.js

@@ -22,25 +22,91 @@ function getFalApiKeyFromEnv() {
   return key;
 }
 function configureFalClient(config) {
-  if (config?.proxyUrl) {
-    fal.config({
-      proxyUrl: config.proxyUrl
-    });
-  } else {
-    const apiKey = config?.apiKey ?? getFalApiKeyFromEnv();
-    if (!apiKey) {
-      throw new Error("API key is required");
+  const apiKey = config?.apiKey ?? getFalApiKeyFromEnv();
+  fal.config({
+    credentials: apiKey,
+    ...config?.proxyUrl ? { proxyUrl: config.proxyUrl } : {}
+  });
+}
+function generateId(prefix) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(2)}`;
+}
+function extractUrlExtension(url) {
+  let pathname;
+  try {
+    const parsed = new URL(url);
+    pathname = parsed.pathname;
+  } catch {
+    pathname = url.split("?")[0].split("#")[0];
+  }
+  const normalized = pathname.replace(/\/+$/, "");
+  if (!normalized.includes("/")) return void 0;
+  const lastSegment = normalized.split("/").pop();
+  if (!lastSegment) return void 0;
+  const extension = lastSegment.split(".").pop();
+  if (!extension || extension === lastSegment) return void 0;
+  return /^[a-z0-9]{2,5}$/i.test(extension) ? extension : void 0;
+}
+function deriveAudioContentType(explicitContentType, url) {
+  const stripped = explicitContentType?.split(";")[0]?.trim();
+  if (stripped) return stripped;
+  const ext = extractUrlExtension(url)?.toLowerCase();
+  switch (ext) {
+    case "mp3":
+      return "audio/mpeg";
+    case "wav":
+      return "audio/wav";
+    case "ogg":
+    case "oga":
+      return "audio/ogg";
+    case "flac":
+      return "audio/flac";
+    case "aac":
+      return "audio/aac";
+    case "m4a":
+    case "mp4":
+      return "audio/mp4";
+    case "webm":
+      return "audio/webm";
+    default:
+      return "audio/mpeg";
+  }
+}
+function dataUrlToBlob(value) {
+  if (!value.startsWith("data:")) return void 0;
+  const commaIndex = value.indexOf(",");
+  if (commaIndex === -1) return void 0;
+  const header = value.slice(5, commaIndex);
+  const payload = value.slice(commaIndex + 1);
+  const isBase64 = /;base64$/i.test(header);
+  const mimeType = header.split(";")[0] || "application/octet-stream";
+  if (isBase64) {
+    const binary = atob(payload);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) {
+      bytes[i] = binary.charCodeAt(i);
     }
-    fal.config({
-      credentials: apiKey
-    });
+    return new Blob([bytes], { type: mimeType });
   }
+  return new Blob([decodeURIComponent(payload)], { type: mimeType });
 }
-function generateId(prefix) {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+function arrayBufferToBase64(bytes) {
+  if (typeof Buffer !== "undefined" && typeof Buffer.from === "function") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  const view = new Uint8Array(bytes);
+  let binary = "";
+  for (let i = 0; i < view.byteLength; i += 1) {
+    binary += String.fromCharCode(view[i]);
+  }
+  return btoa(binary);
 }
 export {
+  arrayBufferToBase64,
   configureFalClient,
+  dataUrlToBlob,
+  deriveAudioContentType,
+  extractUrlExtension,
   generateId,
   getFalApiKeyFromEnv
 };

package/dist/esm/utils/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sources":["../../../src/utils/client.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\n\nexport interface FalClientConfig {\n  apiKey: string\n  proxyUrl?: string\n}\n\ninterface EnvObject {\n  FAL_KEY?: string\n}\n\ninterface WindowWithEnv {\n  env?: EnvObject\n}\n\nfunction getEnvironment(): EnvObject | undefined {\n  if (typeof globalThis !== 'undefined') {\n    const win = (globalThis as { window?: WindowWithEnv }).window\n    if (win?.env) {\n      return win.env\n    }\n  }\n  if (typeof process !== 'undefined') {\n    return process.env as EnvObject\n  }\n  return undefined\n}\n\nexport function getFalApiKeyFromEnv(): string {\n  const env = getEnvironment()\n  const key = env?.FAL_KEY\n\n  if (!key) {\n    throw new Error(\n      'FAL_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',\n    )\n  }\n\n  return key\n}\n\nexport function configureFalClient(config?: FalClientConfig): void {\n  if (config?.proxyUrl) {\n    fal.config({\n      proxyUrl: config.proxyUrl,\n    })\n  } else {\n    const apiKey = config?.apiKey ?? getFalApiKeyFromEnv()\n    if (!apiKey) {\n      throw new Error('API key is required')\n    }\n    fal.config({\n      credentials: apiKey,\n    })\n  }\n}\n\nexport function generateId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n}\n"],"names":[],"mappings":";AAeA,SAAS,iBAAwC;AAC/C,MAAI,OAAO,eAAe,aAAa;AACrC,UAAM,MAAO,WAA0C;AACvD,QAAI,KAAK,KAAK;AACZ,aAAO,IAAI;AAAA,IACb;AAAA,EACF;AACA,MAAI,OAAO,YAAY,aAAa;AAClC,WAAO,QAAQ;AAAA,EACjB;AACA,SAAO;AACT;AAEO,SAAS,sBAA8B;AAC5C,QAAM,MAAM,eAAA;AACZ,QAAM,MAAM,KAAK;AAEjB,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAEO,SAAS,mBAAmB,QAAgC;AACjE,MAAI,QAAQ,UAAU;AACpB,QAAI,OAAO;AAAA,MACT,UAAU,OAAO;AAAA,IAAA,CAClB;AAAA,EACH,OAAO;AACL,UAAM,SAAS,QAAQ,UAAU,oBAAA;AACjC,QAAI,CAAC,QAAQ;AACX,YAAM,IAAI,MAAM,qBAAqB;AAAA,IACvC;AACA,QAAI,OAAO;AAAA,MACT,aAAa;AAAA,IAAA,CACd;AAAA,EACH;AACF;AAEO,SAAS,WAAW,QAAwB;AACjD,SAAO,GAAG,MAAM,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAC3E;"}
+{"version":3,"file":"client.js","sources":["../../../src/utils/client.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\n\nexport interface FalClientConfig {\n  apiKey: string\n  proxyUrl?: string\n}\n\ninterface EnvObject {\n  FAL_KEY?: string\n}\n\ninterface WindowWithEnv {\n  env?: EnvObject\n}\n\nfunction getEnvironment(): EnvObject | undefined {\n  if (typeof globalThis !== 'undefined') {\n    const win = (globalThis as { window?: WindowWithEnv }).window\n    if (win?.env) {\n      return win.env\n    }\n  }\n  if (typeof process !== 'undefined') {\n    return process.env as EnvObject\n  }\n  return undefined\n}\n\nexport function getFalApiKeyFromEnv(): string {\n  const env = getEnvironment()\n  const key = env?.FAL_KEY\n\n  if (!key) {\n    throw new Error(\n      'FAL_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',\n    )\n  }\n\n  return key\n}\n\nexport function configureFalClient(config?: FalClientConfig): void {\n  const apiKey = config?.apiKey ?? getFalApiKeyFromEnv()\n  fal.config({\n    credentials: apiKey,\n    ...(config?.proxyUrl ? { proxyUrl: config.proxyUrl } : {}),\n  })\n}\n\nexport function generateId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(2)}`\n}\n\n/**\n * Extract a safe file extension from a URL. Strips query strings, URL\n * fragments, and any trailing slashes, and only returns the extension when\n * it looks like a real one (2-5 alphanumeric chars). Returns undefined\n * otherwise so callers can fall back to a default.\n */\nexport function extractUrlExtension(url: string): string | undefined {\n  // Parse via URL when possible so we only look at the pathname and never\n  // mistake a TLD (e.g. the `.com` in `https://x.com/`) for a file extension.\n  let pathname: string\n  try {\n    const parsed = new URL(url)\n    pathname = parsed.pathname\n  } catch {\n    // Fall back to treating the input as a raw path when URL parsing fails\n    // (e.g. the caller passed a bare path). Still strip ?query and #fragment.\n    pathname = url.split('?')[0]!.split('#')[0]!\n  }\n  // Drop trailing slashes so `/path/audio.mp3/` still yields `mp3`.\n  const normalized = pathname.replace(/\\/+$/, '')\n  // Require at least one `/` — otherwise we're looking at an empty pathname\n  // (bare-host URLs like `https://x.com/` land here after stripping the\n  // trailing slash).\n  if (!normalized.includes('/')) return undefined\n  const lastSegment = normalized.split('/').pop()\n  if (!lastSegment) return undefined\n  const extension = lastSegment.split('.').pop()\n  if (!extension || extension === lastSegment) return undefined\n  return /^[a-z0-9]{2,5}$/i.test(extension) ? extension : undefined\n}\n\n/**\n * Derive a reasonable audio content-type. Prefers the explicit MIME (stripped\n * of parameters), then an extension-based lookup for common audio formats,\n * otherwise falls back to audio/mpeg — fal URLs virtually always serve mp3.\n */\nexport function deriveAudioContentType(\n  explicitContentType: string | undefined,\n  url: string,\n): string {\n  const stripped = explicitContentType?.split(';')[0]?.trim()\n  if (stripped) return stripped\n\n  const ext = extractUrlExtension(url)?.toLowerCase()\n  switch (ext) {\n    case 'mp3':\n      return 'audio/mpeg'\n    case 'wav':\n      return 'audio/wav'\n    case 'ogg':\n    case 'oga':\n      return 'audio/ogg'\n    case 'flac':\n      return 'audio/flac'\n    case 'aac':\n      return 'audio/aac'\n    case 'm4a':\n    case 'mp4':\n      return 'audio/mp4'\n    case 'webm':\n      return 'audio/webm'\n    default:\n      return 'audio/mpeg'\n  }\n}\n\n/**\n * Decode a `data:` URL into a Blob so fal-client can auto-upload it via\n * `fal.storage.upload`. fal's inference API rejects data URLs with a 422\n * \"Unsupported data URL\", so we convert them before handing them off.\n *\n * Supports both base64 and URL-encoded data URLs. Returns `undefined` for\n * anything that isn't a data URL, so callers can fall through to other\n * handling (http URLs are passed to fal as-is).\n */\nexport function dataUrlToBlob(value: string): Blob | undefined {\n  if (!value.startsWith('data:')) return undefined\n  const commaIndex = value.indexOf(',')\n  if (commaIndex === -1) return undefined\n\n  const header = value.slice(5, commaIndex)\n  const payload = value.slice(commaIndex + 1)\n  const isBase64 = /;base64$/i.test(header)\n  const mimeType = header.split(';')[0] || 'application/octet-stream'\n\n  if (isBase64) {\n    const binary = atob(payload)\n    const bytes = new Uint8Array(binary.length)\n    for (let i = 0; i < binary.length; i += 1) {\n      bytes[i] = binary.charCodeAt(i)\n    }\n    return new Blob([bytes], { type: mimeType })\n  }\n\n  return new Blob([decodeURIComponent(payload)], { type: mimeType })\n}\n\n/**\n * Convert an ArrayBuffer to base64 in a cross-runtime way.\n *\n * The naive `btoa(String.fromCharCode(...bytes))` form blows up V8's argument\n * limit (~65k) on realistic audio payloads, so we either use `Buffer` (Node /\n * Bun) or walk the byte array in a single loop (browser).\n */\nexport function arrayBufferToBase64(bytes: ArrayBuffer): string {\n  if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {\n    return Buffer.from(bytes).toString('base64')\n  }\n  const view = new Uint8Array(bytes)\n  let binary = ''\n  for (let i = 0; i < view.byteLength; i += 1) {\n    binary += String.fromCharCode(view[i]!)\n  }\n  return btoa(binary)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/utils/index.d.ts

@@ -1 +1 @@
-export { getFalApiKeyFromEnv, configureFalClient, generateId, type FalClientConfig, } from './client.js';
+export { getFalApiKeyFromEnv, configureFalClient, generateId, arrayBufferToBase64, dataUrlToBlob, extractUrlExtension, deriveAudioContentType, type FalClientConfig, } from './client.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-fal",
-  "version": "0.6.17",
+  "version": "0.7.0",
   "description": "fal.ai adapter for TanStack AI",
   "author": "",
   "license": "MIT",
@@ -28,7 +28,12 @@
     "tanstack",
     "adapter",
     "image-generation",
-    "video-generation"
+    "video-generation",
+    "audio-generation",
+    "text-to-speech",
+    "speech-to-text",
+    "tts",
+    "transcription"
   ],
   "dependencies": {
     "@fal-ai/client": "^1.9.4"
@@ -36,10 +41,10 @@
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.2.7",
-    "@tanstack/ai": "0.13.0"
+    "@tanstack/ai": "0.14.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "0.13.0"
+    "@tanstack/ai": "0.14.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/audio.ts

@@ -0,0 +1,148 @@
+import { fal } from '@fal-ai/client'
+import { BaseAudioAdapter } from '@tanstack/ai/adapters'
+import {
+  configureFalClient,
+  deriveAudioContentType,
+  generateId as utilGenerateId,
+} from '../utils'
+import type { OutputType, Result } from '@fal-ai/client'
+import type {
+  AudioGenerationOptions,
+  AudioGenerationResult,
+} from '@tanstack/ai'
+import type { FalClientConfig } from '../utils'
+import type { FalModel, FalModelInput } from '../model-meta'
+
+/**
+ * Provider options for audio generation, excluding fields TanStack AI handles.
+ */
+export type FalAudioProviderOptions<TModel extends string> = Omit<
+  FalModelInput<TModel>,
+  'prompt'
+>
+
+/**
+ * Fal audio models don't agree on the name for "how long should this be."
+ * Most accept seconds via `duration`, but a few use model-specific fields —
+ * e.g. ElevenLabs wants milliseconds via `music_length_ms`, Stable Audio wants
+ * `seconds_total`. Explicit per-model entries override the default; user
+ * `modelOptions` still win over either.
+ */
+const DURATION_FRAGMENT_BUILDERS: Record<
+  string,
+  (seconds: number) => Record<string, unknown>
+> = {
+  'fal-ai/elevenlabs/music': (seconds) => ({ music_length_ms: seconds * 1000 }),
+  'fal-ai/stable-audio-25/text-to-audio': (seconds) => ({
+    seconds_total: seconds,
+  }),
+}
+
+function buildDurationFragment(
+  model: string,
+  duration: number | undefined,
+): Record<string, unknown> {
+  if (duration == null) return {}
+  const builder = DURATION_FRAGMENT_BUILDERS[model]
+  return builder ? builder(duration) : { duration }
+}
+
+/**
+ * fal.ai audio generation adapter.
+ *
+ * Supports fal.ai audio models like diffrhythm (music), sound effects, etc.
+ *
+ * @example
+ * ```typescript
+ * const adapter = falAudio('fal-ai/diffrhythm')
+ * const result = await generateAudio({
+ *   adapter,
+ *   prompt: 'An upbeat electronic track with synths',
+ *   duration: 10,
+ * })
+ * ```
+ */
+export class FalAudioAdapter<TModel extends FalModel> extends BaseAudioAdapter<
+  TModel,
+  FalAudioProviderOptions<TModel>
+> {
+  readonly name = 'fal' as const
+
+  constructor(model: TModel, config?: FalClientConfig) {
+    super(model, {})
+    configureFalClient(config)
+  }
+
+  async generateAudio(
+    options: AudioGenerationOptions<FalAudioProviderOptions<TModel>>,
+  ): Promise<AudioGenerationResult> {
+    const { logger } = options
+    logger.request(`activity=generateAudio provider=fal model=${this.model}`, {
+      provider: 'fal',
+      model: this.model,
+    })
+    try {
+      const input = this.buildInput(options)
+      const result = await fal.subscribe(this.model, { input })
+      return this.transformResponse(result)
+    } catch (error) {
+      logger.errors('fal.generateAudio fatal', {
+        error,
+        source: 'fal.generateAudio',
+      })
+      throw error
+    }
+  }
+
+  private buildInput(
+    options: AudioGenerationOptions<FalAudioProviderOptions<TModel>>,
+  ): FalModelInput<TModel> {
+    return {
+      ...buildDurationFragment(this.model, options.duration),
+      ...options.modelOptions,
+      prompt: options.prompt,
+    } as FalModelInput<TModel>
+  }
+
+  protected override generateId(): string {
+    return utilGenerateId(this.name)
+  }
+
+  private transformResponse(
+    response: Result<OutputType<TModel>>,
+  ): AudioGenerationResult {
+    const data = response.data as Record<string, unknown>
+
+    // fal returns { audio: { url, content_type } } or { audio_url: string }
+    let audioUrl: string | undefined
+    let contentType: string | undefined
+
+    if (data.audio && typeof data.audio === 'object' && 'url' in data.audio) {
+      const audioObj = data.audio as { url: string; content_type?: string }
+      audioUrl = audioObj.url
+      contentType = audioObj.content_type
+    } else if (typeof data.audio_url === 'string') {
+      audioUrl = data.audio_url
+    }
+
+    if (!audioUrl) {
+      throw new Error('Audio URL not found in fal audio generation response')
+    }
+
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      audio: {
+        url: audioUrl,
+        contentType: deriveAudioContentType(contentType, audioUrl),
+      },
+    }
+  }
+}
+
+export function falAudio<TModel extends FalModel>(
+  model: TModel,
+  config?: FalClientConfig,
+): FalAudioAdapter<TModel> {
+  return new FalAudioAdapter(model, config)
+}

package/src/adapters/image.ts

@@ -46,7 +46,7 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
   readonly name = 'fal' as const
 
   constructor(model: TModel, config?: FalClientConfig) {
-    super({}, model)
+    super(model, {})
     configureFalClient(config)
   }
 
@@ -110,6 +110,13 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
       images.push(this.parseImage(data.image))
     }
 
+    if (images.length === 0) {
+      throw new Error(
+        'Unexpected fal image response shape. Expected images[] or image{}. Got keys: ' +
+          Object.keys(data).join(','),
+      )
+    }
+
     return {
       id: response.requestId || this.generateId(),
       model: this.model,
@@ -117,16 +124,29 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
     }
   }
 
-  private parseImage(img: { url: string }): GeneratedImage {
-    const url = img.url
-    // Check if it's a base64 data URL
+  private parseImage(img: unknown): GeneratedImage {
+    let url: string
+    if (typeof img === 'string') {
+      url = img
+    } else if (
+      img &&
+      typeof img === 'object' &&
+      'url' in img &&
+      typeof (img as { url: unknown }).url === 'string'
+    ) {
+      url = (img as { url: string }).url
+    } else {
+      throw new Error(
+        `Invalid image payload from fal response: expected string or { url: string }, received ${
+          img === null ? 'null' : typeof img
+        }`,
+      )
+    }
+
     if (url.startsWith('data:')) {
       const base64Match = url.match(/^data:image\/[^;]+;base64,(.+)$/)
-      if (base64Match) {
-        return {
-          b64Json: base64Match[1],
-          url,
-        }
+      if (base64Match && base64Match[1]) {
+        return { b64Json: base64Match[1] }
       }
     }
     return { url }

package/src/adapters/speech.ts

@@ -0,0 +1,147 @@
+import { fal } from '@fal-ai/client'
+import { BaseTTSAdapter } from '@tanstack/ai/adapters'
+import {
+  arrayBufferToBase64,
+  configureFalClient,
+  extractUrlExtension,
+  generateId as utilGenerateId,
+} from '../utils'
+import type { OutputType, Result } from '@fal-ai/client'
+import type { TTSOptions, TTSResult } from '@tanstack/ai'
+import type { FalClientConfig } from '../utils'
+import type { FalModel, FalModelInput } from '../model-meta'
+
+/**
+ * Provider options for TTS, excluding fields TanStack AI handles.
+ */
+export type FalSpeechProviderOptions<TModel extends string> = Omit<
+  FalModelInput<TModel>,
+  'prompt' | 'text'
+>
+
+/**
+ * fal.ai text-to-speech adapter.
+ *
+ * Supports fal.ai TTS models like kokoro, elevenlabs, etc.
+ *
+ * @example
+ * ```typescript
+ * const adapter = falSpeech('fal-ai/kokoro/american-english')
+ * const result = await generateSpeech({
+ *   adapter,
+ *   text: 'Hello, world!',
+ *   voice: 'af_heart',
+ * })
+ * ```
+ */
+export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
+  TModel,
+  FalSpeechProviderOptions<TModel>
+> {
+  readonly name = 'fal' as const
+
+  constructor(model: TModel, config?: FalClientConfig) {
+    super(model, {})
+    configureFalClient(config)
+  }
+
+  async generateSpeech(
+    options: TTSOptions<FalSpeechProviderOptions<TModel>>,
+  ): Promise<TTSResult> {
+    const { logger } = options
+    logger.request(`activity=generateSpeech provider=fal model=${this.model}`, {
+      provider: 'fal',
+      model: this.model,
+    })
+    try {
+      const input = this.buildInput(options)
+      const result = await fal.subscribe(this.model, { input })
+      return await this.transformResponse(result)
+    } catch (error) {
+      logger.errors('fal.generateSpeech fatal', {
+        error,
+        source: 'fal.generateSpeech',
+      })
+      throw error
+    }
+  }
+
+  private buildInput(
+    options: TTSOptions<FalSpeechProviderOptions<TModel>>,
+  ): FalModelInput<TModel> {
+    const input = {
+      ...options.modelOptions,
+      // Map text to both prompt and text fields (different models use different fields)
+      prompt: options.text,
+      text: options.text,
+      ...(options.voice ? { voice: options.voice } : {}),
+      ...(options.speed ? { speed: options.speed } : {}),
+    } as FalModelInput<TModel>
+    return input
+  }
+
+  protected override generateId(): string {
+    return utilGenerateId(this.name)
+  }
+
+  private async transformResponse(
+    response: Result<OutputType<TModel>>,
+  ): Promise<TTSResult> {
+    const data = response.data as Record<string, unknown>
+
+    // fal returns { audio: { url, content_type } } or { audio_url: string }
+    let audioUrl: string | undefined
+    let contentType: string | undefined
+
+    if (data.audio && typeof data.audio === 'object' && 'url' in data.audio) {
+      const audioObj = data.audio as { url: string; content_type?: string }
+      audioUrl = audioObj.url
+      contentType = audioObj.content_type
+    } else if (typeof data.audio_url === 'string') {
+      audioUrl = data.audio_url
+    }
+
+    if (!audioUrl) {
+      throw new Error('Audio URL not found in fal TTS response')
+    }
+
+    // Fetch the audio and convert to base64 to match TTSResult contract.
+    // Using a chunked helper here — spreading Uint8Array into btoa exceeds
+    // V8's argument limit (~65k) for any realistic TTS clip.
+    const audioResponse = await fetch(audioUrl)
+    if (!audioResponse.ok) {
+      throw new Error(
+        `Failed to fetch audio from ${audioUrl}: ${audioResponse.status} ${audioResponse.statusText}`,
+      )
+    }
+    const arrayBuffer = await audioResponse.arrayBuffer()
+    const base64 = arrayBufferToBase64(arrayBuffer)
+
+    // Strip parameters like `; charset=...` from contentType, and only use
+    // the URL extension as a fallback when it looks like a real extension.
+    const contentTypeMime = contentType?.split(';')[0]?.trim()
+    const safeUrlExtension = extractUrlExtension(audioUrl)
+    // Prefer URL-derived extension when available (more canonical for file
+    // consumers), otherwise derive from the content-type mime subtype, then
+    // fall back to `wav`. Normalize `mpeg` → `mp3` so the format field is a
+    // usable file extension rather than the IANA subtype.
+    const rawFormat =
+      safeUrlExtension || contentTypeMime?.split('/')[1] || 'wav'
+    const format = rawFormat === 'mpeg' ? 'mp3' : rawFormat
+
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      audio: base64,
+      format,
+      contentType: contentTypeMime || `audio/${format}`,
+    }
+  }
+}
+
+export function falSpeech<TModel extends FalModel>(
+  model: TModel,
+  config?: FalClientConfig,
+): FalSpeechAdapter<TModel> {
+  return new FalSpeechAdapter(model, config)
+}