@tanstack/ai-fal 0.9.5 → 0.9.6

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,83 @@
+import { fal } from "@fal-ai/client";
+import { BaseAudioAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, generateId, deriveAudioContentType } from "../utils/client.js";
+import { buildFalUsage, takeBillableUnits } from "../utils/billing.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 {
+  name = "fal";
+  constructor(model, config) {
+    super(model, {});
+    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");
+    }
+    const usage = buildFalUsage(takeBillableUnits(response.requestId));
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      audio: {
+        url: audioUrl,
+        contentType: deriveAudioContentType(contentType, audioUrl)
+      },
+      ...usage ? { usage } : {}
+    };
+  }
+}
+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  buildFalUsage,\n  configureFalClient,\n  deriveAudioContentType,\n  takeBillableUnits,\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 (\n      data['audio'] &&\n      typeof data['audio'] === 'object' &&\n      'url' in data['audio']\n    ) {\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    const usage = buildFalUsage(takeBillableUnits(response.requestId))\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      ...(usage ? { usage } : {}),\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":";;;;AAgCA,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,EACS,OAAO;AAAA,EAEhB,YAAY,OAAe,QAA0B;AACnD,UAAM,OAAO,EAAE;AACf,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,QACE,KAAK,OAAO,KACZ,OAAO,KAAK,OAAO,MAAM,YACzB,SAAS,KAAK,OAAO,GACrB;AACA,YAAM,WAAW,KAAK,OAAO;AAC7B,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,UAAM,QAAQ,cAAc,kBAAkB,SAAS,SAAS,CAAC;AAEjE,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,MAE3D,GAAI,QAAQ,EAAE,UAAU,CAAA;AAAA,IAAC;AAAA,EAE7B;AACF;AAEO,SAAS,SACd,OACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,OAAO,MAAM;AAC1C;"}

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

@@ -0,0 +1,36 @@
+import { BaseImageAdapter } from '@tanstack/ai/adapters';
+import { FalClientConfig } from '../utils.js';
+import { ImageGenerationOptions, ImageGenerationResult } from '@tanstack/ai';
+import { FalImagePromptModalitiesFor, FalImageProviderOptions, FalModel, FalModelImageSize } from '../model-meta.js';
+/**
+ * fal.ai image generation adapter with full type inference.
+ *
+ * Uses fal.ai's comprehensive type system to provide autocomplete
+ *
+ * and type safety for all 600+ supported models.
+ *
+ * @example
+ * ```typescript
+ * const adapter = falImage('fal-ai/flux/dev')
+ * const result = await adapter.generateImages({
+ *   model: 'fal-ai/flux/dev',
+ *   prompt: 'a cat',
+ *   modelOptions: {
+ *     num_inference_steps: 28, // Type-safe! Autocomplete works
+ *     guidance_scale: 3.5,
+ *   },
+ * })
+ * ```
+ */
+export declare class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<TModel, FalImageProviderOptions<TModel>, Record<TModel, FalImageProviderOptions<TModel>>, Record<TModel, FalModelImageSize<TModel>>, Record<TModel, FalImagePromptModalitiesFor<TModel>>> {
+    readonly kind: "image";
+    readonly name: "fal";
+    constructor(model: TModel, config?: FalClientConfig);
+    generateImages(options: ImageGenerationOptions<FalImageProviderOptions<TModel>, FalModelImageSize<TModel>>): Promise<ImageGenerationResult>;
+    private buildInput;
+    protected generateId(): string;
+    private transformResponse;
+    private parseImage;
+}
+export declare function createFalImage<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalImageAdapter<TModel>;
+export declare function falImage<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalImageAdapter<TModel>;

package/dist/esm/adapters/image.js

@@ -0,0 +1,115 @@
+import { fal } from "@fal-ai/client";
+import { resolveMediaPrompt } from "@tanstack/ai";
+import { BaseImageAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, generateId } from "../utils/client.js";
+import { buildFalUsage, takeBillableUnits } from "../utils/billing.js";
+import { mapSizeToFalFormat } from "../image/image-provider-options.js";
+import { mapImageInputsToFalFields } from "../image/image-inputs.js";
+class FalImageAdapter extends BaseImageAdapter {
+  kind = "image";
+  name = "fal";
+  constructor(model, config) {
+    super(model, {});
+    configureFalClient(config);
+  }
+  async generateImages(options) {
+    const { logger } = options;
+    logger.request(`activity=generateImage provider=fal model=${this.model}`, {
+      provider: "fal",
+      model: this.model
+    });
+    const resolved = resolveMediaPrompt(options.prompt);
+    if (resolved.videos.length > 0) {
+      throw new Error(
+        `fal.generateImages does not support video prompt parts on model ${this.model}.`
+      );
+    }
+    if (resolved.audios.length > 0) {
+      throw new Error(
+        `fal.generateImages does not support audio prompt parts on model ${this.model}.`
+      );
+    }
+    try {
+      const input = this.buildInput(options, resolved);
+      const result = await fal.subscribe(this.model, { input });
+      return this.transformResponse(result);
+    } catch (error) {
+      logger.errors("fal.generateImage fatal", {
+        error,
+        source: "fal.generateImage"
+      });
+      throw error;
+    }
+  }
+  buildInput(options, resolved) {
+    const sizeParams = mapSizeToFalFormat(options.size);
+    const inputFields = mapImageInputsToFalFields(this.model, resolved.images);
+    const input = {
+      ...sizeParams,
+      ...inputFields,
+      ...options.modelOptions,
+      // Media-only prompts (e.g. upscalers, background removal) omit the
+      // prompt field entirely rather than sending an empty string.
+      ...resolved.text ? { prompt: resolved.text } : {},
+      num_images: options.numberOfImages
+    };
+    return input;
+  }
+  generateId() {
+    return generateId(this.name);
+  }
+  transformResponse(response) {
+    const images = [];
+    const data = response.data;
+    if ("images" in data && Array.isArray(data.images)) {
+      for (const img of data.images) {
+        images.push(this.parseImage(img));
+      }
+    } 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(",")
+      );
+    }
+    const usage = buildFalUsage(takeBillableUnits(response.requestId));
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      images,
+      ...usage ? { usage } : {}
+    };
+  }
+  parseImage(img) {
+    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 && base64Match[1]) {
+        return { b64Json: base64Match[1] };
+      }
+    }
+    return { url };
+  }
+}
+function createFalImage(model, config) {
+  return new FalImageAdapter(model, config);
+}
+function falImage(model, config) {
+  return createFalImage(model, config);
+}
+export {
+  FalImageAdapter,
+  createFalImage,
+  falImage
+};
+//# sourceMappingURL=image.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { resolveMediaPrompt } from '@tanstack/ai'\nimport { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport {\n  buildFalUsage,\n  configureFalClient,\n  takeBillableUnits,\n  generateId as utilGenerateId,\n} from '../utils'\nimport { mapSizeToFalFormat } from '../image/image-provider-options'\nimport { mapImageInputsToFalFields } from '../image/image-inputs'\nimport type { OutputType, Result } from '@fal-ai/client'\nimport type { FalClientConfig } from '../utils'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n  ResolvedMediaPrompt,\n} from '@tanstack/ai'\nimport type {\n  FalImagePromptModalitiesFor,\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  Record<TModel, FalImagePromptModalitiesFor<TModel>>\n> {\n  override 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    const resolved = resolveMediaPrompt(options.prompt)\n\n    if (resolved.videos.length > 0) {\n      throw new Error(\n        `fal.generateImages does not support video prompt parts on model ${this.model}.`,\n      )\n    }\n    if (resolved.audios.length > 0) {\n      throw new Error(\n        `fal.generateImages does not support audio prompt parts on model ${this.model}.`,\n      )\n    }\n\n    try {\n      const input = this.buildInput(options, resolved)\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<\n      FalImageProviderOptions<TModel>,\n      FalModelImageSize<TModel>\n    >,\n    resolved: ResolvedMediaPrompt,\n  ): FalModelInput<TModel> {\n    const sizeParams = mapSizeToFalFormat(options.size)\n    // Order matters: size and derived image-input fields first, then\n    // modelOptions (so explicit user overrides win for mask_url /\n    // control_image_url / reference_image_urls), then the call-controlled\n    // prompt / num_images, which always take precedence.\n    const inputFields = mapImageInputsToFalFields(this.model, resolved.images)\n    const input = {\n      ...sizeParams,\n      ...inputFields,\n      ...options.modelOptions,\n      // Media-only prompts (e.g. upscalers, background removal) omit the\n      // prompt field entirely rather than sending an empty string.\n      ...(resolved.text ? { prompt: resolved.text } : {}),\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    const usage = buildFalUsage(takeBillableUnits(response.requestId))\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      images,\n      ...(usage ? { usage } : {}),\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.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":"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"}

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,87 @@
+import { fal } from "@fal-ai/client";
+import { BaseTTSAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, generateId, arrayBufferToBase64, extractUrlExtension } from "../utils/client.js";
+import { buildFalUsage, takeBillableUnits } from "../utils/billing.js";
+class FalSpeechAdapter extends BaseTTSAdapter {
+  name = "fal";
+  constructor(model, config) {
+    super(model, {});
+    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;
+    const usage = buildFalUsage(takeBillableUnits(response.requestId));
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      audio: base64,
+      format,
+      contentType: contentTypeMime || `audio/${format}`,
+      ...usage ? { usage } : {}
+    };
+  }
+}
+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  buildFalUsage,\n  configureFalClient,\n  extractUrlExtension,\n  takeBillableUnits,\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 (\n      data['audio'] &&\n      typeof data['audio'] === 'object' &&\n      'url' in data['audio']\n    ) {\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    const usage = buildFalUsage(takeBillableUnits(response.requestId))\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      audio: base64,\n      format,\n      contentType: contentTypeMime || `audio/${format}`,\n      ...(usage ? { usage } : {}),\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":";;;;AAsCO,MAAM,yBAAkD,eAG7D;AAAA,EACS,OAAO;AAAA,EAEhB,YAAY,OAAe,QAA0B;AACnD,UAAM,OAAO,EAAE;AACf,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,QACE,KAAK,OAAO,KACZ,OAAO,KAAK,OAAO,MAAM,YACzB,SAAS,KAAK,OAAO,GACrB;AACA,YAAM,WAAW,KAAK,OAAO;AAC7B,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,UAAM,QAAQ,cAAc,kBAAkB,SAAS,SAAS,CAAC;AAEjE,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,MAC/C,GAAI,QAAQ,EAAE,UAAU,CAAA;AAAA,IAAC;AAAA,EAE7B;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,93 @@
+import { fal } from "@fal-ai/client";
+import { BaseTranscriptionAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, dataUrlToBlob, generateId } from "../utils/client.js";
+import { buildFalUsage, takeBillableUnits } from "../utils/billing.js";
+class FalTranscriptionAdapter extends BaseTranscriptionAdapter {
+  name = "fal";
+  constructor(model, config) {
+    super(model, {});
+    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];
+    const usage = buildFalUsage(takeBillableUnits(response.requestId));
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      text,
+      ...language !== void 0 ? { language } : {},
+      ...segments !== void 0 ? { segments } : {},
+      ...usage ? { usage } : {}
+    };
+  }
+}
+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  buildFalUsage,\n  configureFalClient,\n  dataUrlToBlob,\n  takeBillableUnits,\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    const usage = buildFalUsage(takeBillableUnits(response.requestId))\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      text,\n      ...(language !== undefined ? { language } : {}),\n      ...(segments !== undefined ? { segments } : {}),\n      ...(usage ? { usage } : {}),\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":";;;;AA+CO,MAAM,gCAEH,yBAGR;AAAA,EACS,OAAO;AAAA,EAEhB,YAAY,OAAe,QAA0B;AACnD,UAAM,OAAO,EAAE;AACf,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,UAAM,QAAQ,cAAc,kBAAkB,SAAS,SAAS,CAAC;AAEjE,WAAO;AAAA,MACL,IAAI,SAAS,aAAa,KAAK,WAAA;AAAA,MAC/B,OAAO,KAAK;AAAA,MACZ;AAAA,MACA,GAAI,aAAa,SAAY,EAAE,SAAA,IAAa,CAAA;AAAA,MAC5C,GAAI,aAAa,SAAY,EAAE,SAAA,IAAa,CAAA;AAAA,MAC5C,GAAI,QAAQ,EAAE,UAAU,CAAA;AAAA,IAAC;AAAA,EAE7B;AACF;AAEO,SAAS,iBACd,OACA,QACiC;AACjC,SAAO,IAAI,wBAAwB,OAAO,MAAM;AAClD;"}

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

@@ -0,0 +1,34 @@
+import { BaseVideoAdapter } from '@tanstack/ai/adapters';
+import { VideoGenerationOptions, VideoJobResult, VideoStatusResult, VideoUrlResult } from '@tanstack/ai';
+import { FalModel, FalModelVideoSize, FalVideoPromptModalitiesFor, FalVideoProviderOptions } from '../model-meta.js';
+import { FalClientConfig } from '../utils.js';
+/**
+ * fal.ai video generation adapter.
+ * Supports MiniMax, Luma, Kling, Hunyuan, and other fal.ai video models.
+ *
+ * Uses fal.ai's comprehensive type system to provide autocomplete
+ * and type safety for all supported video models.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<TModel, FalVideoProviderOptions<TModel>, Record<TModel, FalVideoProviderOptions<TModel>>, Record<TModel, FalModelVideoSize<TModel>>, Record<TModel, FalVideoPromptModalitiesFor<TModel>>> {
+    readonly kind: "video";
+    readonly name: "fal";
+    constructor(model: TModel, config?: FalClientConfig);
+    createVideoJob(options: VideoGenerationOptions<FalVideoProviderOptions<TModel>, FalModelVideoSize<TModel>>): Promise<VideoJobResult>;
+    getVideoStatus(jobId: string): Promise<VideoStatusResult>;
+    getVideoUrl(jobId: string): Promise<VideoUrlResult>;
+    protected generateId(): string;
+}
+/**
+ * Create a fal.ai video adapter with an explicit API key.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare function createFalVideo<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalVideoAdapter<TModel>;
+/**
+ * Create a fal.ai video adapter using config.apiKey or the FAL_KEY environment variable.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare function falVideo<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalVideoAdapter<TModel>;