@tanstack/ai-fal 0.6.17 → 0.7.0

package/dist/esm/adapters/audio.d.ts

@@ -0,0 +1,32 @@
+import { BaseAudioAdapter } from '@tanstack/ai/adapters';
+import { AudioGenerationOptions, AudioGenerationResult } from '@tanstack/ai';
+import { FalClientConfig } from '../utils.js';
+import { FalModel, FalModelInput } from '../model-meta.js';
+/**
+ * Provider options for audio generation, excluding fields TanStack AI handles.
+ */
+export type FalAudioProviderOptions<TModel extends string> = Omit<FalModelInput<TModel>, 'prompt'>;
+/**
+ * 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 declare class FalAudioAdapter<TModel extends FalModel> extends BaseAudioAdapter<TModel, FalAudioProviderOptions<TModel>> {
+    readonly name: "fal";
+    constructor(model: TModel, config?: FalClientConfig);
+    generateAudio(options: AudioGenerationOptions<FalAudioProviderOptions<TModel>>): Promise<AudioGenerationResult>;
+    private buildInput;
+    protected generateId(): string;
+    private transformResponse;
+}
+export declare function falAudio<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalAudioAdapter<TModel>;

package/dist/esm/adapters/audio.js

@@ -0,0 +1,80 @@
+import { fal } from "@fal-ai/client";
+import { BaseAudioAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, generateId, deriveAudioContentType } from "../utils/client.js";
+const DURATION_FRAGMENT_BUILDERS = {
+  "fal-ai/elevenlabs/music": (seconds) => ({ music_length_ms: seconds * 1e3 }),
+  "fal-ai/stable-audio-25/text-to-audio": (seconds) => ({
+    seconds_total: seconds
+  })
+};
+function buildDurationFragment(model, duration) {
+  if (duration == null) return {};
+  const builder = DURATION_FRAGMENT_BUILDERS[model];
+  return builder ? builder(duration) : { duration };
+}
+class FalAudioAdapter extends BaseAudioAdapter {
+  constructor(model, config) {
+    super(model, {});
+    this.name = "fal";
+    configureFalClient(config);
+  }
+  async generateAudio(options) {
+    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;
+    }
+  }
+  buildInput(options) {
+    return {
+      ...buildDurationFragment(this.model, options.duration),
+      ...options.modelOptions,
+      prompt: options.prompt
+    };
+  }
+  generateId() {
+    return generateId(this.name);
+  }
+  transformResponse(response) {
+    const data = response.data;
+    let audioUrl;
+    let contentType;
+    if (data.audio && typeof data.audio === "object" && "url" in data.audio) {
+      const audioObj = data.audio;
+      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)
+      }
+    };
+  }
+}
+function falAudio(model, config) {
+  return new FalAudioAdapter(model, config);
+}
+export {
+  FalAudioAdapter,
+  falAudio
+};
+//# sourceMappingURL=audio.js.map

package/dist/esm/adapters/audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.js","sources":["../../../src/adapters/audio.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { BaseAudioAdapter } from '@tanstack/ai/adapters'\nimport {\n  configureFalClient,\n  deriveAudioContentType,\n  generateId as utilGenerateId,\n} from '../utils'\nimport type { OutputType, Result } from '@fal-ai/client'\nimport type {\n  AudioGenerationOptions,\n  AudioGenerationResult,\n} from '@tanstack/ai'\nimport type { FalClientConfig } from '../utils'\nimport type { FalModel, FalModelInput } from '../model-meta'\n\n/**\n * Provider options for audio generation, excluding fields TanStack AI handles.\n */\nexport type FalAudioProviderOptions<TModel extends string> = Omit<\n  FalModelInput<TModel>,\n  'prompt'\n>\n\n/**\n * Fal audio models don't agree on the name for \"how long should this be.\"\n * Most accept seconds via `duration`, but a few use model-specific fields —\n * e.g. ElevenLabs wants milliseconds via `music_length_ms`, Stable Audio wants\n * `seconds_total`. Explicit per-model entries override the default; user\n * `modelOptions` still win over either.\n */\nconst DURATION_FRAGMENT_BUILDERS: Record<\n  string,\n  (seconds: number) => Record<string, unknown>\n> = {\n  'fal-ai/elevenlabs/music': (seconds) => ({ music_length_ms: seconds * 1000 }),\n  'fal-ai/stable-audio-25/text-to-audio': (seconds) => ({\n    seconds_total: seconds,\n  }),\n}\n\nfunction buildDurationFragment(\n  model: string,\n  duration: number | undefined,\n): Record<string, unknown> {\n  if (duration == null) return {}\n  const builder = DURATION_FRAGMENT_BUILDERS[model]\n  return builder ? builder(duration) : { duration }\n}\n\n/**\n * fal.ai audio generation adapter.\n *\n * Supports fal.ai audio models like diffrhythm (music), sound effects, etc.\n *\n * @example\n * ```typescript\n * const adapter = falAudio('fal-ai/diffrhythm')\n * const result = await generateAudio({\n *   adapter,\n *   prompt: 'An upbeat electronic track with synths',\n *   duration: 10,\n * })\n * ```\n */\nexport class FalAudioAdapter<TModel extends FalModel> extends BaseAudioAdapter<\n  TModel,\n  FalAudioProviderOptions<TModel>\n> {\n  readonly name = 'fal' as const\n\n  constructor(model: TModel, config?: FalClientConfig) {\n    super(model, {})\n    configureFalClient(config)\n  }\n\n  async generateAudio(\n    options: AudioGenerationOptions<FalAudioProviderOptions<TModel>>,\n  ): Promise<AudioGenerationResult> {\n    const { logger } = options\n    logger.request(`activity=generateAudio provider=fal model=${this.model}`, {\n      provider: 'fal',\n      model: this.model,\n    })\n    try {\n      const input = this.buildInput(options)\n      const result = await fal.subscribe(this.model, { input })\n      return this.transformResponse(result)\n    } catch (error) {\n      logger.errors('fal.generateAudio fatal', {\n        error,\n        source: 'fal.generateAudio',\n      })\n      throw error\n    }\n  }\n\n  private buildInput(\n    options: AudioGenerationOptions<FalAudioProviderOptions<TModel>>,\n  ): FalModelInput<TModel> {\n    return {\n      ...buildDurationFragment(this.model, options.duration),\n      ...options.modelOptions,\n      prompt: options.prompt,\n    } as FalModelInput<TModel>\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n\n  private transformResponse(\n    response: Result<OutputType<TModel>>,\n  ): AudioGenerationResult {\n    const data = response.data as Record<string, unknown>\n\n    // fal returns { audio: { url, content_type } } or { audio_url: string }\n    let audioUrl: string | undefined\n    let contentType: string | undefined\n\n    if (data.audio && typeof data.audio === 'object' && 'url' in data.audio) {\n      const audioObj = data.audio as { url: string; content_type?: string }\n      audioUrl = audioObj.url\n      contentType = audioObj.content_type\n    } else if (typeof data.audio_url === 'string') {\n      audioUrl = data.audio_url\n    }\n\n    if (!audioUrl) {\n      throw new Error('Audio URL not found in fal audio generation response')\n    }\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      audio: {\n        url: audioUrl,\n        contentType: deriveAudioContentType(contentType, audioUrl),\n      },\n    }\n  }\n}\n\nexport function falAudio<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalAudioAdapter<TModel> {\n  return new FalAudioAdapter(model, config)\n}\n"],"names":["utilGenerateId"],"mappings":";;;AA8BA,MAAM,6BAGF;AAAA,EACF,2BAA2B,CAAC,aAAa,EAAE,iBAAiB,UAAU,IAAA;AAAA,EACtE,wCAAwC,CAAC,aAAa;AAAA,IACpD,eAAe;AAAA,EAAA;AAEnB;AAEA,SAAS,sBACP,OACA,UACyB;AACzB,MAAI,YAAY,KAAM,QAAO,CAAA;AAC7B,QAAM,UAAU,2BAA2B,KAAK;AAChD,SAAO,UAAU,QAAQ,QAAQ,IAAI,EAAE,SAAA;AACzC;AAiBO,MAAM,wBAAiD,iBAG5D;AAAA,EAGA,YAAY,OAAe,QAA0B;AACnD,UAAM,OAAO,EAAE;AAHjB,SAAS,OAAO;AAId,uBAAmB,MAAM;AAAA,EAC3B;AAAA,EAEA,MAAM,cACJ,SACgC;AAChC,UAAM,EAAE,WAAW;AACnB,WAAO,QAAQ,6CAA6C,KAAK,KAAK,IAAI;AAAA,MACxE,UAAU;AAAA,MACV,OAAO,KAAK;AAAA,IAAA,CACb;AACD,QAAI;AACF,YAAM,QAAQ,KAAK,WAAW,OAAO;AACrC,YAAM,SAAS,MAAM,IAAI,UAAU,KAAK,OAAO,EAAE,OAAO;AACxD,aAAO,KAAK,kBAAkB,MAAM;AAAA,IACtC,SAAS,OAAO;AACd,aAAO,OAAO,2BAA2B;AAAA,QACvC;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEQ,WACN,SACuB;AACvB,WAAO;AAAA,MACL,GAAG,sBAAsB,KAAK,OAAO,QAAQ,QAAQ;AAAA,MACrD,GAAG,QAAQ;AAAA,MACX,QAAQ,QAAQ;AAAA,IAAA;AAAA,EAEpB;AAAA,EAEmB,aAAqB;AACtC,WAAOA,WAAe,KAAK,IAAI;AAAA,EACjC;AAAA,EAEQ,kBACN,UACuB;AACvB,UAAM,OAAO,SAAS;AAGtB,QAAI;AACJ,QAAI;AAEJ,QAAI,KAAK,SAAS,OAAO,KAAK,UAAU,YAAY,SAAS,KAAK,OAAO;AACvE,YAAM,WAAW,KAAK;AACtB,iBAAW,SAAS;AACpB,oBAAc,SAAS;AAAA,IACzB,WAAW,OAAO,KAAK,cAAc,UAAU;AAC7C,iBAAW,KAAK;AAAA,IAClB;AAEA,QAAI,CAAC,UAAU;AACb,YAAM,IAAI,MAAM,sDAAsD;AAAA,IACxE;AAEA,WAAO;AAAA,MACL,IAAI,SAAS,aAAa,KAAK,WAAA;AAAA,MAC/B,OAAO,KAAK;AAAA,MACZ,OAAO;AAAA,QACL,KAAK;AAAA,QACL,aAAa,uBAAuB,aAAa,QAAQ;AAAA,MAAA;AAAA,IAC3D;AAAA,EAEJ;AACF;AAEO,SAAS,SACd,OACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,OAAO,MAAM;AAC1C;"}

package/dist/esm/adapters/image.js

@@ -4,7 +4,7 @@ import { configureFalClient, generateId } from "../utils/client.js";
 import { mapSizeToFalFormat } from "../image/image-provider-options.js";
 class FalImageAdapter extends BaseImageAdapter {
   constructor(model, config) {
-    super({}, model);
+    super(model, {});
     this.kind = "image";
     this.name = "fal";
     configureFalClient(config);
@@ -50,6 +50,11 @@ class FalImageAdapter extends BaseImageAdapter {
     } else if ("image" in data && data.image && typeof data.image === "object") {
       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,
@@ -57,14 +62,20 @@ class FalImageAdapter extends BaseImageAdapter {
     };
   }
   parseImage(img) {
-    const url = img.url;
+    let url;
+    if (typeof img === "string") {
+      url = img;
+    } else if (img && typeof img === "object" && "url" in img && typeof img.url === "string") {
+      url = img.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/dist/esm/adapters/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { configureFalClient, generateId as utilGenerateId } from '../utils'\nimport { mapSizeToFalFormat } from '../image/image-provider-options'\nimport type { OutputType, Result } from '@fal-ai/client'\nimport type { FalClientConfig } from '../utils'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n} from '@tanstack/ai'\nimport type {\n  FalImageProviderOptions,\n  FalModel,\n  FalModelImageSize,\n  FalModelInput,\n} from '../model-meta'\n\n/**\n * fal.ai image generation adapter with full type inference.\n *\n * Uses fal.ai's comprehensive type system to provide autocomplete\n *\n * and type safety for all 600+ supported models.\n *\n * @example\n * ```typescript\n * const adapter = falImage('fal-ai/flux/dev')\n * const result = await adapter.generateImages({\n *   model: 'fal-ai/flux/dev',\n *   prompt: 'a cat',\n *   modelOptions: {\n *     num_inference_steps: 28, // Type-safe! Autocomplete works\n *     guidance_scale: 3.5,\n *   },\n * })\n * ```\n */\nexport class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<\n  TModel,\n  FalImageProviderOptions<TModel>,\n  Record<TModel, FalImageProviderOptions<TModel>>,\n  Record<TModel, FalModelImageSize<TModel>>\n> {\n  readonly kind = 'image' as const\n  readonly name = 'fal' as const\n\n  constructor(model: TModel, config?: FalClientConfig) {\n    super({}, model)\n    configureFalClient(config)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<\n      FalImageProviderOptions<TModel>,\n      FalModelImageSize<TModel>\n    >,\n  ): Promise<ImageGenerationResult> {\n    const { logger } = options\n\n    logger.request(`activity=generateImage provider=fal model=${this.model}`, {\n      provider: 'fal',\n      model: this.model,\n    })\n\n    try {\n      const input = this.buildInput(options)\n      const result = await fal.subscribe(this.model, { input })\n      return this.transformResponse(result)\n    } catch (error) {\n      logger.errors('fal.generateImage fatal', {\n        error,\n        source: 'fal.generateImage',\n      })\n      throw error\n    }\n  }\n\n  private buildInput(\n    options: ImageGenerationOptions<FalImageProviderOptions<TModel>, string>,\n  ): FalModelInput<TModel> {\n    const sizeParams = mapSizeToFalFormat(options.size)\n    const input = {\n      ...options.modelOptions,\n      ...sizeParams,\n      prompt: options.prompt,\n      num_images: options.numberOfImages,\n    } as FalModelInput<TModel>\n    return input\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n\n  private transformResponse(\n    response: Result<OutputType<TModel>>,\n  ): ImageGenerationResult {\n    const images: Array<GeneratedImage> = []\n    const data = response.data\n\n    // Handle array of images (most models return { images: [...] })\n    if ('images' in data && Array.isArray(data.images)) {\n      for (const img of data.images) {\n        images.push(this.parseImage(img))\n      }\n    }\n    // Handle single image response (some models return { image: {...} })\n    else if ('image' in data && data.image && typeof data.image === 'object') {\n      images.push(this.parseImage(data.image))\n    }\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      images,\n    }\n  }\n\n  private parseImage(img: { url: string }): GeneratedImage {\n    const url = img.url\n    // Check if it's a base64 data URL\n    if (url.startsWith('data:')) {\n      const base64Match = url.match(/^data:image\\/[^;]+;base64,(.+)$/)\n      if (base64Match) {\n        return {\n          b64Json: base64Match[1],\n          url,\n        }\n      }\n    }\n    return { url }\n  }\n}\n\nexport function createFalImage<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalImageAdapter<TModel> {\n  return new FalImageAdapter(model, config)\n}\n\nexport function falImage<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalImageAdapter<TModel> {\n  return createFalImage(model, config)\n}\n"],"names":["utilGenerateId"],"mappings":";;;;AAsCO,MAAM,wBAAiD,iBAK5D;AAAA,EAIA,YAAY,OAAe,QAA0B;AACnD,UAAM,CAAA,GAAI,KAAK;AAJjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAId,uBAAmB,MAAM;AAAA,EAC3B;AAAA,EAEA,MAAM,eACJ,SAIgC;AAChC,UAAM,EAAE,WAAW;AAEnB,WAAO,QAAQ,6CAA6C,KAAK,KAAK,IAAI;AAAA,MACxE,UAAU;AAAA,MACV,OAAO,KAAK;AAAA,IAAA,CACb;AAED,QAAI;AACF,YAAM,QAAQ,KAAK,WAAW,OAAO;AACrC,YAAM,SAAS,MAAM,IAAI,UAAU,KAAK,OAAO,EAAE,OAAO;AACxD,aAAO,KAAK,kBAAkB,MAAM;AAAA,IACtC,SAAS,OAAO;AACd,aAAO,OAAO,2BAA2B;AAAA,QACvC;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEQ,WACN,SACuB;AACvB,UAAM,aAAa,mBAAmB,QAAQ,IAAI;AAClD,UAAM,QAAQ;AAAA,MACZ,GAAG,QAAQ;AAAA,MACX,GAAG;AAAA,MACH,QAAQ,QAAQ;AAAA,MAChB,YAAY,QAAQ;AAAA,IAAA;AAEtB,WAAO;AAAA,EACT;AAAA,EAEmB,aAAqB;AACtC,WAAOA,WAAe,KAAK,IAAI;AAAA,EACjC;AAAA,EAEQ,kBACN,UACuB;AACvB,UAAM,SAAgC,CAAA;AACtC,UAAM,OAAO,SAAS;AAGtB,QAAI,YAAY,QAAQ,MAAM,QAAQ,KAAK,MAAM,GAAG;AAClD,iBAAW,OAAO,KAAK,QAAQ;AAC7B,eAAO,KAAK,KAAK,WAAW,GAAG,CAAC;AAAA,MAClC;AAAA,IACF,WAES,WAAW,QAAQ,KAAK,SAAS,OAAO,KAAK,UAAU,UAAU;AACxE,aAAO,KAAK,KAAK,WAAW,KAAK,KAAK,CAAC;AAAA,IACzC;AAEA,WAAO;AAAA,MACL,IAAI,SAAS,aAAa,KAAK,WAAA;AAAA,MAC/B,OAAO,KAAK;AAAA,MACZ;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEQ,WAAW,KAAsC;AACvD,UAAM,MAAM,IAAI;AAEhB,QAAI,IAAI,WAAW,OAAO,GAAG;AAC3B,YAAM,cAAc,IAAI,MAAM,iCAAiC;AAC/D,UAAI,aAAa;AACf,eAAO;AAAA,UACL,SAAS,YAAY,CAAC;AAAA,UACtB;AAAA,QAAA;AAAA,MAEJ;AAAA,IACF;AACA,WAAO,EAAE,IAAA;AAAA,EACX;AACF;AAEO,SAAS,eACd,OACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,OAAO,MAAM;AAC1C;AAEO,SAAS,SACd,OACA,QACyB;AACzB,SAAO,eAAe,OAAO,MAAM;AACrC;"}
+{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { configureFalClient, generateId as utilGenerateId } from '../utils'\nimport { mapSizeToFalFormat } from '../image/image-provider-options'\nimport type { OutputType, Result } from '@fal-ai/client'\nimport type { FalClientConfig } from '../utils'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n} from '@tanstack/ai'\nimport type {\n  FalImageProviderOptions,\n  FalModel,\n  FalModelImageSize,\n  FalModelInput,\n} from '../model-meta'\n\n/**\n * fal.ai image generation adapter with full type inference.\n *\n * Uses fal.ai's comprehensive type system to provide autocomplete\n *\n * and type safety for all 600+ supported models.\n *\n * @example\n * ```typescript\n * const adapter = falImage('fal-ai/flux/dev')\n * const result = await adapter.generateImages({\n *   model: 'fal-ai/flux/dev',\n *   prompt: 'a cat',\n *   modelOptions: {\n *     num_inference_steps: 28, // Type-safe! Autocomplete works\n *     guidance_scale: 3.5,\n *   },\n * })\n * ```\n */\nexport class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<\n  TModel,\n  FalImageProviderOptions<TModel>,\n  Record<TModel, FalImageProviderOptions<TModel>>,\n  Record<TModel, FalModelImageSize<TModel>>\n> {\n  readonly kind = 'image' as const\n  readonly name = 'fal' as const\n\n  constructor(model: TModel, config?: FalClientConfig) {\n    super(model, {})\n    configureFalClient(config)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<\n      FalImageProviderOptions<TModel>,\n      FalModelImageSize<TModel>\n    >,\n  ): Promise<ImageGenerationResult> {\n    const { logger } = options\n\n    logger.request(`activity=generateImage provider=fal model=${this.model}`, {\n      provider: 'fal',\n      model: this.model,\n    })\n\n    try {\n      const input = this.buildInput(options)\n      const result = await fal.subscribe(this.model, { input })\n      return this.transformResponse(result)\n    } catch (error) {\n      logger.errors('fal.generateImage fatal', {\n        error,\n        source: 'fal.generateImage',\n      })\n      throw error\n    }\n  }\n\n  private buildInput(\n    options: ImageGenerationOptions<FalImageProviderOptions<TModel>, string>,\n  ): FalModelInput<TModel> {\n    const sizeParams = mapSizeToFalFormat(options.size)\n    const input = {\n      ...options.modelOptions,\n      ...sizeParams,\n      prompt: options.prompt,\n      num_images: options.numberOfImages,\n    } as FalModelInput<TModel>\n    return input\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n\n  private transformResponse(\n    response: Result<OutputType<TModel>>,\n  ): ImageGenerationResult {\n    const images: Array<GeneratedImage> = []\n    const data = response.data\n\n    // Handle array of images (most models return { images: [...] })\n    if ('images' in data && Array.isArray(data.images)) {\n      for (const img of data.images) {\n        images.push(this.parseImage(img))\n      }\n    }\n    // Handle single image response (some models return { image: {...} })\n    else if ('image' in data && data.image && typeof data.image === 'object') {\n      images.push(this.parseImage(data.image))\n    }\n\n    if (images.length === 0) {\n      throw new Error(\n        'Unexpected fal image response shape. Expected images[] or image{}. Got keys: ' +\n          Object.keys(data).join(','),\n      )\n    }\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      images,\n    }\n  }\n\n  private parseImage(img: unknown): GeneratedImage {\n    let url: string\n    if (typeof img === 'string') {\n      url = img\n    } else if (\n      img &&\n      typeof img === 'object' &&\n      'url' in img &&\n      typeof (img as { url: unknown }).url === 'string'\n    ) {\n      url = (img as { url: string }).url\n    } else {\n      throw new Error(\n        `Invalid image payload from fal response: expected string or { url: string }, received ${\n          img === null ? 'null' : typeof img\n        }`,\n      )\n    }\n\n    if (url.startsWith('data:')) {\n      const base64Match = url.match(/^data:image\\/[^;]+;base64,(.+)$/)\n      if (base64Match && base64Match[1]) {\n        return { b64Json: base64Match[1] }\n      }\n    }\n    return { url }\n  }\n}\n\nexport function createFalImage<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalImageAdapter<TModel> {\n  return new FalImageAdapter(model, config)\n}\n\nexport function falImage<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalImageAdapter<TModel> {\n  return createFalImage(model, config)\n}\n"],"names":["utilGenerateId"],"mappings":";;;;AAsCO,MAAM,wBAAiD,iBAK5D;AAAA,EAIA,YAAY,OAAe,QAA0B;AACnD,UAAM,OAAO,EAAE;AAJjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAId,uBAAmB,MAAM;AAAA,EAC3B;AAAA,EAEA,MAAM,eACJ,SAIgC;AAChC,UAAM,EAAE,WAAW;AAEnB,WAAO,QAAQ,6CAA6C,KAAK,KAAK,IAAI;AAAA,MACxE,UAAU;AAAA,MACV,OAAO,KAAK;AAAA,IAAA,CACb;AAED,QAAI;AACF,YAAM,QAAQ,KAAK,WAAW,OAAO;AACrC,YAAM,SAAS,MAAM,IAAI,UAAU,KAAK,OAAO,EAAE,OAAO;AACxD,aAAO,KAAK,kBAAkB,MAAM;AAAA,IACtC,SAAS,OAAO;AACd,aAAO,OAAO,2BAA2B;AAAA,QACvC;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEQ,WACN,SACuB;AACvB,UAAM,aAAa,mBAAmB,QAAQ,IAAI;AAClD,UAAM,QAAQ;AAAA,MACZ,GAAG,QAAQ;AAAA,MACX,GAAG;AAAA,MACH,QAAQ,QAAQ;AAAA,MAChB,YAAY,QAAQ;AAAA,IAAA;AAEtB,WAAO;AAAA,EACT;AAAA,EAEmB,aAAqB;AACtC,WAAOA,WAAe,KAAK,IAAI;AAAA,EACjC;AAAA,EAEQ,kBACN,UACuB;AACvB,UAAM,SAAgC,CAAA;AACtC,UAAM,OAAO,SAAS;AAGtB,QAAI,YAAY,QAAQ,MAAM,QAAQ,KAAK,MAAM,GAAG;AAClD,iBAAW,OAAO,KAAK,QAAQ;AAC7B,eAAO,KAAK,KAAK,WAAW,GAAG,CAAC;AAAA,MAClC;AAAA,IACF,WAES,WAAW,QAAQ,KAAK,SAAS,OAAO,KAAK,UAAU,UAAU;AACxE,aAAO,KAAK,KAAK,WAAW,KAAK,KAAK,CAAC;AAAA,IACzC;AAEA,QAAI,OAAO,WAAW,GAAG;AACvB,YAAM,IAAI;AAAA,QACR,kFACE,OAAO,KAAK,IAAI,EAAE,KAAK,GAAG;AAAA,MAAA;AAAA,IAEhC;AAEA,WAAO;AAAA,MACL,IAAI,SAAS,aAAa,KAAK,WAAA;AAAA,MAC/B,OAAO,KAAK;AAAA,MACZ;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEQ,WAAW,KAA8B;AAC/C,QAAI;AACJ,QAAI,OAAO,QAAQ,UAAU;AAC3B,YAAM;AAAA,IACR,WACE,OACA,OAAO,QAAQ,YACf,SAAS,OACT,OAAQ,IAAyB,QAAQ,UACzC;AACA,YAAO,IAAwB;AAAA,IACjC,OAAO;AACL,YAAM,IAAI;AAAA,QACR,yFACE,QAAQ,OAAO,SAAS,OAAO,GACjC;AAAA,MAAA;AAAA,IAEJ;AAEA,QAAI,IAAI,WAAW,OAAO,GAAG;AAC3B,YAAM,cAAc,IAAI,MAAM,iCAAiC;AAC/D,UAAI,eAAe,YAAY,CAAC,GAAG;AACjC,eAAO,EAAE,SAAS,YAAY,CAAC,EAAA;AAAA,MACjC;AAAA,IACF;AACA,WAAO,EAAE,IAAA;AAAA,EACX;AACF;AAEO,SAAS,eACd,OACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,OAAO,MAAM;AAC1C;AAEO,SAAS,SACd,OACA,QACyB;AACzB,SAAO,eAAe,OAAO,MAAM;AACrC;"}

package/dist/esm/adapters/speech.d.ts

@@ -0,0 +1,32 @@
+import { BaseTTSAdapter } from '@tanstack/ai/adapters';
+import { TTSOptions, TTSResult } from '@tanstack/ai';
+import { FalClientConfig } from '../utils.js';
+import { FalModel, FalModelInput } from '../model-meta.js';
+/**
+ * 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 declare class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<TModel, FalSpeechProviderOptions<TModel>> {
+    readonly name: "fal";
+    constructor(model: TModel, config?: FalClientConfig);
+    generateSpeech(options: TTSOptions<FalSpeechProviderOptions<TModel>>): Promise<TTSResult>;
+    private buildInput;
+    protected generateId(): string;
+    private transformResponse;
+}
+export declare function falSpeech<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalSpeechAdapter<TModel>;

package/dist/esm/adapters/speech.js

@@ -0,0 +1,84 @@
+import { fal } from "@fal-ai/client";
+import { BaseTTSAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, generateId, arrayBufferToBase64, extractUrlExtension } from "../utils/client.js";
+class FalSpeechAdapter extends BaseTTSAdapter {
+  constructor(model, config) {
+    super(model, {});
+    this.name = "fal";
+    configureFalClient(config);
+  }
+  async generateSpeech(options) {
+    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;
+    }
+  }
+  buildInput(options) {
+    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 } : {}
+    };
+    return input;
+  }
+  generateId() {
+    return generateId(this.name);
+  }
+  async transformResponse(response) {
+    const data = response.data;
+    let audioUrl;
+    let contentType;
+    if (data.audio && typeof data.audio === "object" && "url" in data.audio) {
+      const audioObj = data.audio;
+      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");
+    }
+    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);
+    const contentTypeMime = contentType?.split(";")[0]?.trim();
+    const safeUrlExtension = extractUrlExtension(audioUrl);
+    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}`
+    };
+  }
+}
+function falSpeech(model, config) {
+  return new FalSpeechAdapter(model, config);
+}
+export {
+  FalSpeechAdapter,
+  falSpeech
+};
+//# sourceMappingURL=speech.js.map

package/dist/esm/adapters/speech.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech.js","sources":["../../../src/adapters/speech.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { BaseTTSAdapter } from '@tanstack/ai/adapters'\nimport {\n  arrayBufferToBase64,\n  configureFalClient,\n  extractUrlExtension,\n  generateId as utilGenerateId,\n} from '../utils'\nimport type { OutputType, Result } from '@fal-ai/client'\nimport type { TTSOptions, TTSResult } from '@tanstack/ai'\nimport type { FalClientConfig } from '../utils'\nimport type { FalModel, FalModelInput } from '../model-meta'\n\n/**\n * Provider options for TTS, excluding fields TanStack AI handles.\n */\nexport type FalSpeechProviderOptions<TModel extends string> = Omit<\n  FalModelInput<TModel>,\n  'prompt' | 'text'\n>\n\n/**\n * fal.ai text-to-speech adapter.\n *\n * Supports fal.ai TTS models like kokoro, elevenlabs, etc.\n *\n * @example\n * ```typescript\n * const adapter = falSpeech('fal-ai/kokoro/american-english')\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'Hello, world!',\n *   voice: 'af_heart',\n * })\n * ```\n */\nexport class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<\n  TModel,\n  FalSpeechProviderOptions<TModel>\n> {\n  readonly name = 'fal' as const\n\n  constructor(model: TModel, config?: FalClientConfig) {\n    super(model, {})\n    configureFalClient(config)\n  }\n\n  async generateSpeech(\n    options: TTSOptions<FalSpeechProviderOptions<TModel>>,\n  ): Promise<TTSResult> {\n    const { logger } = options\n    logger.request(`activity=generateSpeech provider=fal model=${this.model}`, {\n      provider: 'fal',\n      model: this.model,\n    })\n    try {\n      const input = this.buildInput(options)\n      const result = await fal.subscribe(this.model, { input })\n      return await this.transformResponse(result)\n    } catch (error) {\n      logger.errors('fal.generateSpeech fatal', {\n        error,\n        source: 'fal.generateSpeech',\n      })\n      throw error\n    }\n  }\n\n  private buildInput(\n    options: TTSOptions<FalSpeechProviderOptions<TModel>>,\n  ): FalModelInput<TModel> {\n    const input = {\n      ...options.modelOptions,\n      // Map text to both prompt and text fields (different models use different fields)\n      prompt: options.text,\n      text: options.text,\n      ...(options.voice ? { voice: options.voice } : {}),\n      ...(options.speed ? { speed: options.speed } : {}),\n    } as FalModelInput<TModel>\n    return input\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n\n  private async transformResponse(\n    response: Result<OutputType<TModel>>,\n  ): Promise<TTSResult> {\n    const data = response.data as Record<string, unknown>\n\n    // fal returns { audio: { url, content_type } } or { audio_url: string }\n    let audioUrl: string | undefined\n    let contentType: string | undefined\n\n    if (data.audio && typeof data.audio === 'object' && 'url' in data.audio) {\n      const audioObj = data.audio as { url: string; content_type?: string }\n      audioUrl = audioObj.url\n      contentType = audioObj.content_type\n    } else if (typeof data.audio_url === 'string') {\n      audioUrl = data.audio_url\n    }\n\n    if (!audioUrl) {\n      throw new Error('Audio URL not found in fal TTS response')\n    }\n\n    // Fetch the audio and convert to base64 to match TTSResult contract.\n    // Using a chunked helper here — spreading Uint8Array into btoa exceeds\n    // V8's argument limit (~65k) for any realistic TTS clip.\n    const audioResponse = await fetch(audioUrl)\n    if (!audioResponse.ok) {\n      throw new Error(\n        `Failed to fetch audio from ${audioUrl}: ${audioResponse.status} ${audioResponse.statusText}`,\n      )\n    }\n    const arrayBuffer = await audioResponse.arrayBuffer()\n    const base64 = arrayBufferToBase64(arrayBuffer)\n\n    // Strip parameters like `; charset=...` from contentType, and only use\n    // the URL extension as a fallback when it looks like a real extension.\n    const contentTypeMime = contentType?.split(';')[0]?.trim()\n    const safeUrlExtension = extractUrlExtension(audioUrl)\n    // Prefer URL-derived extension when available (more canonical for file\n    // consumers), otherwise derive from the content-type mime subtype, then\n    // fall back to `wav`. Normalize `mpeg` → `mp3` so the format field is a\n    // usable file extension rather than the IANA subtype.\n    const rawFormat =\n      safeUrlExtension || contentTypeMime?.split('/')[1] || 'wav'\n    const format = rawFormat === 'mpeg' ? 'mp3' : rawFormat\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      audio: base64,\n      format,\n      contentType: contentTypeMime || `audio/${format}`,\n    }\n  }\n}\n\nexport function falSpeech<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalSpeechAdapter<TModel> {\n  return new FalSpeechAdapter(model, config)\n}\n"],"names":["utilGenerateId"],"mappings":";;;AAoCO,MAAM,yBAAkD,eAG7D;AAAA,EAGA,YAAY,OAAe,QAA0B;AACnD,UAAM,OAAO,EAAE;AAHjB,SAAS,OAAO;AAId,uBAAmB,MAAM;AAAA,EAC3B;AAAA,EAEA,MAAM,eACJ,SACoB;AACpB,UAAM,EAAE,WAAW;AACnB,WAAO,QAAQ,8CAA8C,KAAK,KAAK,IAAI;AAAA,MACzE,UAAU;AAAA,MACV,OAAO,KAAK;AAAA,IAAA,CACb;AACD,QAAI;AACF,YAAM,QAAQ,KAAK,WAAW,OAAO;AACrC,YAAM,SAAS,MAAM,IAAI,UAAU,KAAK,OAAO,EAAE,OAAO;AACxD,aAAO,MAAM,KAAK,kBAAkB,MAAM;AAAA,IAC5C,SAAS,OAAO;AACd,aAAO,OAAO,4BAA4B;AAAA,QACxC;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEQ,WACN,SACuB;AACvB,UAAM,QAAQ;AAAA,MACZ,GAAG,QAAQ;AAAA;AAAA,MAEX,QAAQ,QAAQ;AAAA,MAChB,MAAM,QAAQ;AAAA,MACd,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAA,IAAU,CAAA;AAAA,MAC/C,GAAI,QAAQ,QAAQ,EAAE,OAAO,QAAQ,MAAA,IAAU,CAAA;AAAA,IAAC;AAElD,WAAO;AAAA,EACT;AAAA,EAEmB,aAAqB;AACtC,WAAOA,WAAe,KAAK,IAAI;AAAA,EACjC;AAAA,EAEA,MAAc,kBACZ,UACoB;AACpB,UAAM,OAAO,SAAS;AAGtB,QAAI;AACJ,QAAI;AAEJ,QAAI,KAAK,SAAS,OAAO,KAAK,UAAU,YAAY,SAAS,KAAK,OAAO;AACvE,YAAM,WAAW,KAAK;AACtB,iBAAW,SAAS;AACpB,oBAAc,SAAS;AAAA,IACzB,WAAW,OAAO,KAAK,cAAc,UAAU;AAC7C,iBAAW,KAAK;AAAA,IAClB;AAEA,QAAI,CAAC,UAAU;AACb,YAAM,IAAI,MAAM,yCAAyC;AAAA,IAC3D;AAKA,UAAM,gBAAgB,MAAM,MAAM,QAAQ;AAC1C,QAAI,CAAC,cAAc,IAAI;AACrB,YAAM,IAAI;AAAA,QACR,8BAA8B,QAAQ,KAAK,cAAc,MAAM,IAAI,cAAc,UAAU;AAAA,MAAA;AAAA,IAE/F;AACA,UAAM,cAAc,MAAM,cAAc,YAAA;AACxC,UAAM,SAAS,oBAAoB,WAAW;AAI9C,UAAM,kBAAkB,aAAa,MAAM,GAAG,EAAE,CAAC,GAAG,KAAA;AACpD,UAAM,mBAAmB,oBAAoB,QAAQ;AAKrD,UAAM,YACJ,oBAAoB,iBAAiB,MAAM,GAAG,EAAE,CAAC,KAAK;AACxD,UAAM,SAAS,cAAc,SAAS,QAAQ;AAE9C,WAAO;AAAA,MACL,IAAI,SAAS,aAAa,KAAK,WAAA;AAAA,MAC/B,OAAO,KAAK;AAAA,MACZ,OAAO;AAAA,MACP;AAAA,MACA,aAAa,mBAAmB,SAAS,MAAM;AAAA,IAAA;AAAA,EAEnD;AACF;AAEO,SAAS,UACd,OACA,QAC0B;AAC1B,SAAO,IAAI,iBAAiB,OAAO,MAAM;AAC3C;"}

package/dist/esm/adapters/transcription.d.ts

@@ -0,0 +1,32 @@
+import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters';
+import { TranscriptionOptions, TranscriptionResult } from '@tanstack/ai';
+import { FalClientConfig } from '../utils.js';
+import { FalModel, FalModelInput } from '../model-meta.js';
+/**
+ * Provider options for transcription, excluding fields TanStack AI handles.
+ */
+export type FalTranscriptionProviderOptions<TModel extends string> = Omit<FalModelInput<TModel>, 'audio_url'>;
+/**
+ * fal.ai transcription (speech-to-text) adapter.
+ *
+ * Supports fal.ai STT models like whisper, wizper, etc.
+ *
+ * @example
+ * ```typescript
+ * const adapter = falTranscription('fal-ai/whisper')
+ * const result = await generateTranscription({
+ *   adapter,
+ *   audio: 'https://example.com/audio.mp3',
+ *   language: 'en',
+ * })
+ * ```
+ */
+export declare class FalTranscriptionAdapter<TModel extends FalModel> extends BaseTranscriptionAdapter<TModel, FalTranscriptionProviderOptions<TModel>> {
+    readonly name: "fal";
+    constructor(model: TModel, config?: FalClientConfig);
+    transcribe(options: TranscriptionOptions<FalTranscriptionProviderOptions<TModel>>): Promise<TranscriptionResult>;
+    private buildInput;
+    protected generateId(): string;
+    private transformResponse;
+}
+export declare function falTranscription<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalTranscriptionAdapter<TModel>;

package/dist/esm/adapters/transcription.js

@@ -0,0 +1,90 @@
+import { fal } from "@fal-ai/client";
+import { BaseTranscriptionAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, dataUrlToBlob, generateId } from "../utils/client.js";
+class FalTranscriptionAdapter extends BaseTranscriptionAdapter {
+  constructor(model, config) {
+    super(model, {});
+    this.name = "fal";
+    configureFalClient(config);
+  }
+  async transcribe(options) {
+    const { logger } = options;
+    logger.request(
+      `activity=generateTranscription 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.generateTranscription fatal", {
+        error,
+        source: "fal.generateTranscription"
+      });
+      throw error;
+    }
+  }
+  buildInput(options) {
+    let audioInput;
+    if (options.audio instanceof ArrayBuffer) {
+      audioInput = new Blob([options.audio]);
+    } else if (typeof options.audio === "string") {
+      audioInput = dataUrlToBlob(options.audio) ?? options.audio;
+    } else {
+      audioInput = options.audio;
+    }
+    const input = {
+      ...options.modelOptions,
+      audio_url: audioInput,
+      ...options.language ? { language: options.language } : {},
+      ...options.prompt ? { prompt: options.prompt } : {}
+    };
+    return input;
+  }
+  generateId() {
+    return generateId(this.name);
+  }
+  transformResponse(response) {
+    const data = response.data;
+    const text = data.text || "";
+    let segments;
+    const chunks = data.chunks;
+    if (chunks && Array.isArray(chunks)) {
+      segments = chunks.flatMap((chunk, index) => {
+        const ts = chunk.timestamp;
+        if (!Array.isArray(ts) || ts.length < 2 || typeof ts[0] !== "number" || typeof ts[1] !== "number") {
+          return [];
+        }
+        return [
+          {
+            id: index,
+            start: ts[0],
+            end: ts[1],
+            text: chunk.text,
+            ...chunk.speaker ? { speaker: chunk.speaker } : {}
+          }
+        ];
+      });
+    }
+    const language = data.language || data.inferred_languages?.[0] || data.languages?.[0];
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      text,
+      language,
+      segments
+    };
+  }
+}
+function falTranscription(model, config) {
+  return new FalTranscriptionAdapter(model, config);
+}
+export {
+  FalTranscriptionAdapter,
+  falTranscription
+};
+//# sourceMappingURL=transcription.js.map

package/dist/esm/adapters/transcription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcription.js","sources":["../../../src/adapters/transcription.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'\nimport {\n  configureFalClient,\n  dataUrlToBlob,\n  generateId as utilGenerateId,\n} from '../utils'\nimport type { OutputType, Result } from '@fal-ai/client'\nimport type {\n  TranscriptionOptions,\n  TranscriptionResult,\n  TranscriptionSegment,\n} from '@tanstack/ai'\nimport type { FalClientConfig } from '../utils'\nimport type { FalModel, FalModelInput } from '../model-meta'\n\n/**\n * Provider options for transcription, excluding fields TanStack AI handles.\n */\nexport type FalTranscriptionProviderOptions<TModel extends string> = Omit<\n  FalModelInput<TModel>,\n  'audio_url'\n>\n\ninterface FalChunk {\n  text: string\n  timestamp?: [number, number] | null\n  speaker?: string\n}\n\n/**\n * fal.ai transcription (speech-to-text) adapter.\n *\n * Supports fal.ai STT models like whisper, wizper, etc.\n *\n * @example\n * ```typescript\n * const adapter = falTranscription('fal-ai/whisper')\n * const result = await generateTranscription({\n *   adapter,\n *   audio: 'https://example.com/audio.mp3',\n *   language: 'en',\n * })\n * ```\n */\nexport class FalTranscriptionAdapter<\n  TModel extends FalModel,\n> extends BaseTranscriptionAdapter<\n  TModel,\n  FalTranscriptionProviderOptions<TModel>\n> {\n  readonly name = 'fal' as const\n\n  constructor(model: TModel, config?: FalClientConfig) {\n    super(model, {})\n    configureFalClient(config)\n  }\n\n  async transcribe(\n    options: TranscriptionOptions<FalTranscriptionProviderOptions<TModel>>,\n  ): Promise<TranscriptionResult> {\n    const { logger } = options\n    logger.request(\n      `activity=generateTranscription provider=fal model=${this.model}`,\n      {\n        provider: 'fal',\n        model: this.model,\n      },\n    )\n    try {\n      const input = this.buildInput(options)\n      const result = await fal.subscribe(this.model, { input })\n      return this.transformResponse(result)\n    } catch (error) {\n      logger.errors('fal.generateTranscription fatal', {\n        error,\n        source: 'fal.generateTranscription',\n      })\n      throw error\n    }\n  }\n\n  private buildInput(\n    options: TranscriptionOptions<FalTranscriptionProviderOptions<TModel>>,\n  ): FalModelInput<TModel> {\n    // fal-client auto-uploads Blob/File inputs via fal.storage.upload, but\n    // passes strings through unchanged — so a `data:` URL would reach fal's\n    // API and get rejected with a 422 \"Unsupported data URL\". Decode data\n    // URLs to a Blob up front so the auto-upload path handles them.\n    let audioInput: string | Blob | File\n    if (options.audio instanceof ArrayBuffer) {\n      audioInput = new Blob([options.audio])\n    } else if (typeof options.audio === 'string') {\n      audioInput = dataUrlToBlob(options.audio) ?? options.audio\n    } else {\n      audioInput = options.audio\n    }\n\n    const input = {\n      ...options.modelOptions,\n      audio_url: audioInput,\n      ...(options.language ? { language: options.language } : {}),\n      ...(options.prompt ? { prompt: options.prompt } : {}),\n    } as FalModelInput<TModel>\n    return input\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n\n  private transformResponse(\n    response: Result<OutputType<TModel>>,\n  ): TranscriptionResult {\n    const data = response.data as Record<string, unknown>\n\n    const text = (data.text as string) || ''\n\n    // Map fal chunks to TanStack segments. fal whisper can return\n    // `timestamp: null` on some chunks (e.g. when word-level timing is\n    // disabled), and the runtime payload is not actually constrained to a\n    // 2-tuple — treat it as unknown and validate before indexing.\n    let segments: Array<TranscriptionSegment> | undefined\n    const chunks = data.chunks as Array<FalChunk> | undefined\n    if (chunks && Array.isArray(chunks)) {\n      segments = chunks.flatMap((chunk, index) => {\n        const ts = chunk.timestamp as unknown\n        if (\n          !Array.isArray(ts) ||\n          ts.length < 2 ||\n          typeof ts[0] !== 'number' ||\n          typeof ts[1] !== 'number'\n        ) {\n          return []\n        }\n        return [\n          {\n            id: index,\n            start: ts[0],\n            end: ts[1],\n            text: chunk.text,\n            ...(chunk.speaker ? { speaker: chunk.speaker } : {}),\n          },\n        ]\n      })\n    }\n\n    // Extract language from response\n    const language =\n      (data.language as string) ||\n      (data.inferred_languages as Array<string> | undefined)?.[0] ||\n      (data.languages as Array<string> | undefined)?.[0]\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      text,\n      language,\n      segments,\n    }\n  }\n}\n\nexport function falTranscription<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalTranscriptionAdapter<TModel> {\n  return new FalTranscriptionAdapter(model, config)\n}\n"],"names":["utilGenerateId"],"mappings":";;;AA6CO,MAAM,gCAEH,yBAGR;AAAA,EAGA,YAAY,OAAe,QAA0B;AACnD,UAAM,OAAO,EAAE;AAHjB,SAAS,OAAO;AAId,uBAAmB,MAAM;AAAA,EAC3B;AAAA,EAEA,MAAM,WACJ,SAC8B;AAC9B,UAAM,EAAE,WAAW;AACnB,WAAO;AAAA,MACL,qDAAqD,KAAK,KAAK;AAAA,MAC/D;AAAA,QACE,UAAU;AAAA,QACV,OAAO,KAAK;AAAA,MAAA;AAAA,IACd;AAEF,QAAI;AACF,YAAM,QAAQ,KAAK,WAAW,OAAO;AACrC,YAAM,SAAS,MAAM,IAAI,UAAU,KAAK,OAAO,EAAE,OAAO;AACxD,aAAO,KAAK,kBAAkB,MAAM;AAAA,IACtC,SAAS,OAAO;AACd,aAAO,OAAO,mCAAmC;AAAA,QAC/C;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEQ,WACN,SACuB;AAKvB,QAAI;AACJ,QAAI,QAAQ,iBAAiB,aAAa;AACxC,mBAAa,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC;AAAA,IACvC,WAAW,OAAO,QAAQ,UAAU,UAAU;AAC5C,mBAAa,cAAc,QAAQ,KAAK,KAAK,QAAQ;AAAA,IACvD,OAAO;AACL,mBAAa,QAAQ;AAAA,IACvB;AAEA,UAAM,QAAQ;AAAA,MACZ,GAAG,QAAQ;AAAA,MACX,WAAW;AAAA,MACX,GAAI,QAAQ,WAAW,EAAE,UAAU,QAAQ,SAAA,IAAa,CAAA;AAAA,MACxD,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAA,IAAW,CAAA;AAAA,IAAC;AAErD,WAAO;AAAA,EACT;AAAA,EAEmB,aAAqB;AACtC,WAAOA,WAAe,KAAK,IAAI;AAAA,EACjC;AAAA,EAEQ,kBACN,UACqB;AACrB,UAAM,OAAO,SAAS;AAEtB,UAAM,OAAQ,KAAK,QAAmB;AAMtC,QAAI;AACJ,UAAM,SAAS,KAAK;AACpB,QAAI,UAAU,MAAM,QAAQ,MAAM,GAAG;AACnC,iBAAW,OAAO,QAAQ,CAAC,OAAO,UAAU;AAC1C,cAAM,KAAK,MAAM;AACjB,YACE,CAAC,MAAM,QAAQ,EAAE,KACjB,GAAG,SAAS,KACZ,OAAO,GAAG,CAAC,MAAM,YACjB,OAAO,GAAG,CAAC,MAAM,UACjB;AACA,iBAAO,CAAA;AAAA,QACT;AACA,eAAO;AAAA,UACL;AAAA,YACE,IAAI;AAAA,YACJ,OAAO,GAAG,CAAC;AAAA,YACX,KAAK,GAAG,CAAC;AAAA,YACT,MAAM,MAAM;AAAA,YACZ,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAA,IAAY,CAAA;AAAA,UAAC;AAAA,QACpD;AAAA,MAEJ,CAAC;AAAA,IACH;AAGA,UAAM,WACH,KAAK,YACL,KAAK,qBAAmD,CAAC,KACzD,KAAK,YAA0C,CAAC;AAEnD,WAAO;AAAA,MACL,IAAI,SAAS,aAAa,KAAK,WAAA;AAAA,MAC/B,OAAO,KAAK;AAAA,MACZ;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AACF;AAEO,SAAS,iBACd,OACA,QACiC;AACjC,SAAO,IAAI,wBAAwB,OAAO,MAAM;AAClD;"}

package/dist/esm/image/image-provider-options.js

@@ -1,12 +1,16 @@
 function mapSizeToFalFormat(size) {
   if (!size) return void 0;
-  const match = size.match(/^(\d+:\d+)(?:_(.+))?$/);
-  return {
-    image_size: size,
-    aspect_ratio: match?.[1],
-    ...match?.[2] && {
-      resolution: match?.[2]
+  if (typeof size === "string") {
+    const match = size.match(/^(\d+:\d+)(?:_(.+))?$/);
+    if (match) {
+      return {
+        aspect_ratio: match[1],
+        ...match[2] ? { resolution: match[2] } : {}
+      };
     }
+  }
+  return {
+    image_size: size
   };
 }
 export {

package/dist/esm/image/image-provider-options.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-provider-options.js","sources":["../../../src/image/image-provider-options.ts"],"sourcesContent":["import type { FalModelImageSize, FalModelImageSizeInput } from '../model-meta'\n\nexport function mapSizeToFalFormat<TModel extends string>(\n  size: FalModelImageSize<TModel> | undefined,\n): FalModelImageSizeInput<TModel> | undefined {\n  if (!size) return undefined\n\n  // \"16:9_4K\" → { aspect_ratio, resolution }\n  // \"16:9\"    → { aspect_ratio }\n  // no match  → { image_size }\n  const match = size.match(/^(\\d+:\\d+)(?:_(.+))?$/)\n\n  return {\n    image_size: size,\n    aspect_ratio: match?.[1],\n    ...(match?.[2] && {\n      resolution: match?.[2],\n    }),\n  }\n}\n"],"names":[],"mappings":"AAEO,SAAS,mBACd,MAC4C;AAC5C,MAAI,CAAC,KAAM,QAAO;AAKlB,QAAM,QAAQ,KAAK,MAAM,uBAAuB;AAEhD,SAAO;AAAA,IACL,YAAY;AAAA,IACZ,cAAc,QAAQ,CAAC;AAAA,IACvB,GAAI,QAAQ,CAAC,KAAK;AAAA,MAChB,YAAY,QAAQ,CAAC;AAAA,IAAA;AAAA,EACvB;AAEJ;"}
+{"version":3,"file":"image-provider-options.js","sources":["../../../src/image/image-provider-options.ts"],"sourcesContent":["import type { FalModelImageSize, FalModelImageSizeInput } from '../model-meta'\n\nexport function mapSizeToFalFormat<TModel extends string>(\n  size: FalModelImageSize<TModel> | undefined,\n): FalModelImageSizeInput<TModel> | undefined {\n  if (!size) return undefined\n\n  // \"16:9_4K\" → { aspect_ratio, resolution }\n  // \"16:9\"    → { aspect_ratio }\n  // no match  → { image_size }\n  if (typeof size === 'string') {\n    const match = size.match(/^(\\d+:\\d+)(?:_(.+))?$/)\n    if (match) {\n      return {\n        aspect_ratio: match[1],\n        ...(match[2] ? { resolution: match[2] } : {}),\n      } as FalModelImageSizeInput<TModel>\n    }\n  }\n\n  return {\n    image_size: size,\n  } as FalModelImageSizeInput<TModel>\n}\n"],"names":[],"mappings":"AAEO,SAAS,mBACd,MAC4C;AAC5C,MAAI,CAAC,KAAM,QAAO;AAKlB,MAAI,OAAO,SAAS,UAAU;AAC5B,UAAM,QAAQ,KAAK,MAAM,uBAAuB;AAChD,QAAI,OAAO;AACT,aAAO;AAAA,QACL,cAAc,MAAM,CAAC;AAAA,QACrB,GAAI,MAAM,CAAC,IAAI,EAAE,YAAY,MAAM,CAAC,MAAM,CAAA;AAAA,MAAC;AAAA,IAE/C;AAAA,EACF;AAEA,SAAO;AAAA,IACL,YAAY;AAAA,EAAA;AAEhB;"}

package/dist/esm/index.d.ts

@@ -1,4 +1,7 @@
 export { FalImageAdapter, falImage } from './adapters/image.js';
 export { FalVideoAdapter, falVideo } from './adapters/video.js';
-export { type FalImageProviderOptions, type FalVideoProviderOptions, type FalModel, type FalModelInput, type FalModelOutput, type FalModelImageSize, type FalModelVideoSize, } from './model-meta.js';
+export { FalSpeechAdapter, falSpeech } from './adapters/speech.js';
+export { FalTranscriptionAdapter, falTranscription, } from './adapters/transcription.js';
+export { FalAudioAdapter, falAudio } from './adapters/audio.js';
+export { type FalImageProviderOptions, type FalVideoProviderOptions, type FalSpeechProviderOptions, type FalTranscriptionProviderOptions, type FalAudioProviderOptions, type FalModel, type FalModelInput, type FalModelOutput, type FalModelImageSize, type FalModelVideoSize, } from './model-meta.js';
 export { getFalApiKeyFromEnv, configureFalClient, generateId, type FalClientConfig, } from './utils.js';

package/dist/esm/index.js

@@ -1,11 +1,20 @@
 import { FalImageAdapter, falImage } from "./adapters/image.js";
 import { FalVideoAdapter, falVideo } from "./adapters/video.js";
+import { FalSpeechAdapter, falSpeech } from "./adapters/speech.js";
+import { FalTranscriptionAdapter, falTranscription } from "./adapters/transcription.js";
+import { FalAudioAdapter, falAudio } from "./adapters/audio.js";
 import { configureFalClient, generateId, getFalApiKeyFromEnv } from "./utils/client.js";
 export {
+  FalAudioAdapter,
   FalImageAdapter,
+  FalSpeechAdapter,
+  FalTranscriptionAdapter,
   FalVideoAdapter,
   configureFalClient,
+  falAudio,
   falImage,
+  falSpeech,
+  falTranscription,
   falVideo,
   generateId,
   getFalApiKeyFromEnv

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/dist/esm/model-meta.d.ts

@@ -74,3 +74,18 @@ export type FalModelVideoSizeInput<TModel extends string> = TModel extends keyof
  * Use this for the `modelOptions` parameter in video generation.
  */
 export type FalVideoProviderOptions<TModel extends string> = TModel extends keyof EndpointTypeMap ? Omit<FalModelInput<TModel>, 'prompt'> : Record<string, any>;
+/**
+ * Provider options for TTS, excluding fields TanStack AI handles.
+ * Use this for the `modelOptions` parameter in speech generation.
+ */
+export type FalSpeechProviderOptions<TModel extends string> = Omit<FalModelInput<TModel>, 'prompt' | 'text'>;
+/**
+ * Provider options for transcription, excluding fields TanStack AI handles.
+ * Use this for the `modelOptions` parameter in transcription.
+ */
+export type FalTranscriptionProviderOptions<TModel extends string> = Omit<FalModelInput<TModel>, 'audio_url'>;
+/**
+ * Provider options for audio generation, excluding fields TanStack AI handles.
+ * Use this for the `modelOptions` parameter in audio generation.
+ */
+export type FalAudioProviderOptions<TModel extends string> = Omit<FalModelInput<TModel>, 'prompt'>;

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

@@ -5,3 +5,34 @@ export interface FalClientConfig {
 export declare function getFalApiKeyFromEnv(): string;
 export declare function configureFalClient(config?: FalClientConfig): void;
 export declare function generateId(prefix: string): string;
+/**
+ * Extract a safe file extension from a URL. Strips query strings, URL
+ * fragments, and any trailing slashes, and only returns the extension when
+ * it looks like a real one (2-5 alphanumeric chars). Returns undefined
+ * otherwise so callers can fall back to a default.
+ */
+export declare function extractUrlExtension(url: string): string | undefined;
+/**
+ * Derive a reasonable audio content-type. Prefers the explicit MIME (stripped
+ * of parameters), then an extension-based lookup for common audio formats,
+ * otherwise falls back to audio/mpeg — fal URLs virtually always serve mp3.
+ */
+export declare function deriveAudioContentType(explicitContentType: string | undefined, url: string): string;
+/**
+ * Decode a `data:` URL into a Blob so fal-client can auto-upload it via
+ * `fal.storage.upload`. fal's inference API rejects data URLs with a 422
+ * "Unsupported data URL", so we convert them before handing them off.
+ *
+ * Supports both base64 and URL-encoded data URLs. Returns `undefined` for
+ * anything that isn't a data URL, so callers can fall through to other
+ * handling (http URLs are passed to fal as-is).
+ */
+export declare function dataUrlToBlob(value: string): Blob | undefined;
+/**
+ * Convert an ArrayBuffer to base64 in a cross-runtime way.
+ *
+ * The naive `btoa(String.fromCharCode(...bytes))` form blows up V8's argument
+ * limit (~65k) on realistic audio payloads, so we either use `Buffer` (Node /
+ * Bun) or walk the byte array in a single loop (browser).
+ */
+export declare function arrayBufferToBase64(bytes: ArrayBuffer): string;