@tanstack/ai-fal 0.10.1 → 0.12.0

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

@@ -1,6 +1,6 @@
-import { BaseVideoAdapter } from '@tanstack/ai/adapters';
+import { BaseVideoAdapter, DurationOptions } from '@tanstack/ai/adapters';
 import { VideoGenerationOptions, VideoJobResult, VideoStatusResult, VideoUrlResult } from '@tanstack/ai';
-import { FalModel, FalModelVideoSize, FalVideoPromptModalitiesFor, FalVideoProviderOptions } from '../model-meta.js';
+import { FalModel, FalModelVideoDuration, FalModelVideoSize, FalVideoPromptModalitiesFor, FalVideoProviderOptions } from '../model-meta.js';
 import { FalClientConfig } from '../utils/client.js';
 /**
  * fal.ai video generation adapter.
@@ -11,11 +11,13 @@ import { FalClientConfig } from '../utils/client.js';
  *
  * @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>>> {
+export declare class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<TModel, FalVideoProviderOptions<TModel>, Record<TModel, FalVideoProviderOptions<TModel>>, Record<TModel, FalModelVideoSize<TModel>>, Record<TModel, FalVideoPromptModalitiesFor<TModel>>, Record<TModel, FalModelVideoDuration<TModel>>> {
     readonly kind: "video";
     readonly name: "fal";
     constructor(model: TModel, config?: FalClientConfig);
-    createVideoJob(options: VideoGenerationOptions<FalVideoProviderOptions<TModel>, FalModelVideoSize<TModel>>): Promise<VideoJobResult>;
+    createVideoJob(options: VideoGenerationOptions<FalVideoProviderOptions<TModel>, FalModelVideoSize<TModel>, FalModelVideoDuration<TModel>>): Promise<VideoJobResult>;
+    availableDurations(): DurationOptions<FalModelVideoDuration<TModel>>;
+    snapDuration(seconds: number): FalModelVideoDuration<TModel> | undefined;
     getVideoStatus(jobId: string): Promise<VideoStatusResult>;
     getVideoUrl(jobId: string): Promise<VideoUrlResult>;
     protected generateId(): string;

package/dist/esm/adapters/video.js

@@ -1,10 +1,10 @@
 import { buildFalUsage, takeBillableUnits } from "../utils/billing.js";
 import { configureFalClient, generateId } from "../utils/client.js";
 import { mapImageInputsToFalVideoFields } from "../image/image-inputs.js";
-import { mapVideoSizeToFalFormat } from "../video/video-provider-options.js";
+import { getFalVideoDurationOptions, mapVideoSizeToFalFormat } from "../video/video-provider-options.js";
 import { fal } from "@fal-ai/client";
 import { resolveMediaPrompt } from "@tanstack/ai";
-import { BaseVideoAdapter } from "@tanstack/ai/adapters";
+import { BaseVideoAdapter, snapToDurationOption } from "@tanstack/ai/adapters";
 //#region src/adapters/video.ts
 /**
 * Map video conditioning inputs onto fal field names.
@@ -86,7 +86,7 @@ var FalVideoAdapter = class extends BaseVideoAdapter {
 				...audioFields,
 				...modelOptions,
 				...resolved.text ? { prompt: resolved.text } : {},
-				...duration ? { duration } : {}
+				...duration !== void 0 ? { duration } : {}
 			};
 			const { request_id } = await fal.queue.submit(this.model, {
 				input,
@@ -104,6 +104,12 @@ var FalVideoAdapter = class extends BaseVideoAdapter {
 			throw error;
 		}
 	}
+	availableDurations() {
+		return getFalVideoDurationOptions(this.model);
+	}
+	snapDuration(seconds) {
+		return snapToDurationOption(seconds, this.availableDurations());
+	}
 	async getVideoStatus(jobId) {
 		const statusResponse = await fal.queue.status(this.model, {
 			requestId: jobId,

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

@@ -1 +1 @@
-{"version":3,"file":"video.js","names":[],"sources":["../../../src/adapters/video.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { resolveMediaPrompt } from '@tanstack/ai'\nimport { BaseVideoAdapter } from '@tanstack/ai/adapters'\nimport {\n  configureFalClient,\n  generateId as utilGenerateId,\n} from '../utils/client'\nimport { buildFalUsage, takeBillableUnits } from '../utils/billing'\nimport { mapVideoSizeToFalFormat } from '../video/video-provider-options'\nimport { mapImageInputsToFalVideoFields } from '../image/image-inputs'\nimport type {\n  AudioPart,\n  MediaInputMetadata,\n  VideoGenerationOptions,\n  VideoJobResult,\n  VideoPart,\n  VideoStatusResult,\n  VideoUrlResult,\n} from '@tanstack/ai'\nimport type {\n  FalModel,\n  FalModelInput,\n  FalModelVideoSize,\n  FalVideoPromptModalitiesFor,\n  FalVideoProviderOptions,\n} from '../model-meta'\nimport type { FalClientConfig } from '../utils/client'\n\n/**\n * Map video conditioning inputs onto fal field names.\n * Video-to-video endpoints on fal almost universally use `video_url`; the\n * occasional model takes `video_urls` (rare). Mirror the image-input logic\n * positionally with a `reference` role escape hatch via `reference_video_urls`.\n */\nfunction mapVideoInputsToFalFields(\n  videoInputs?: ReadonlyArray<VideoPart<MediaInputMetadata>>,\n): Record<string, unknown> {\n  if (!videoInputs || videoInputs.length === 0) return {}\n  const references: Array<string> = []\n  const sources: Array<string> = []\n  for (const part of videoInputs) {\n    const url = videoPartToUrl(part)\n    if (\n      part.metadata?.role === 'reference' ||\n      part.metadata?.role === 'character'\n    ) {\n      references.push(url)\n    } else {\n      sources.push(url)\n    }\n  }\n  const out: Record<string, unknown> = {}\n  if (references.length > 0) out.reference_video_urls = references\n  if (sources.length === 1) {\n    out.video_url = sources[0]\n  } else if (sources.length > 1) {\n    out.video_urls = sources\n  }\n  return out\n}\n\nfunction mapAudioInputsToFalFields(\n  audioInputs?: ReadonlyArray<AudioPart<MediaInputMetadata>>,\n): Record<string, unknown> {\n  if (!audioInputs || audioInputs.length === 0) return {}\n  const [part, ...rest] = audioInputs\n  if (!part || rest.length > 0) {\n    throw new Error(\n      `fal: exactly one audio prompt part is supported (received ${audioInputs.length}).`,\n    )\n  }\n  return {\n    audio_url:\n      part.source.type === 'url'\n        ? part.source.value\n        : `data:${part.source.mimeType};base64,${part.source.value}`,\n  }\n}\n\nfunction videoPartToUrl(part: VideoPart<MediaInputMetadata>): string {\n  return part.source.type === 'url'\n    ? part.source.value\n    : `data:${part.source.mimeType};base64,${part.source.value}`\n}\n\ntype FalQueueStatus = 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED'\n\ninterface FalStatusResponse {\n  status: FalQueueStatus\n  queue_position?: number\n  logs?: Array<{ message: string }>\n}\n\ninterface FalVideoResultData {\n  video?: { url: string }\n  video_url?: string\n}\n\n/**\n * Maps fal.ai queue status to TanStack AI video status.\n *\n * Note: fal.ai does not return a FAILED queue status. Errors surface\n * as exceptions when fetching results from a COMPLETED job (e.g. 422\n * validation errors). Those are handled in getVideoUrl().\n */\nfunction mapFalStatusToVideoStatus(\n  falStatus: FalQueueStatus,\n): VideoStatusResult['status'] {\n  switch (falStatus) {\n    case 'IN_QUEUE':\n      return 'pending'\n    case 'IN_PROGRESS':\n      return 'processing'\n    case 'COMPLETED':\n      return 'completed'\n    default:\n      return 'processing'\n  }\n}\n\n/**\n * fal.ai video generation adapter.\n * Supports MiniMax, Luma, Kling, Hunyuan, and other fal.ai video models.\n *\n * Uses fal.ai's comprehensive type system to provide autocomplete\n * and type safety for all supported video models.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<\n  TModel,\n  FalVideoProviderOptions<TModel>,\n  Record<TModel, FalVideoProviderOptions<TModel>>,\n  Record<TModel, FalModelVideoSize<TModel>>,\n  Record<TModel, FalVideoPromptModalitiesFor<TModel>>\n> {\n  override readonly kind = 'video' 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 createVideoJob(\n    options: VideoGenerationOptions<\n      FalVideoProviderOptions<TModel>,\n      FalModelVideoSize<TModel>\n    >,\n  ): Promise<VideoJobResult> {\n    const { size, duration, modelOptions, logger } = options\n\n    logger.request(`activity=generateVideo provider=fal model=${this.model}`, {\n      provider: 'fal',\n      model: this.model,\n    })\n\n    try {\n      const resolved = resolveMediaPrompt(options.prompt)\n      const sizeParams = mapVideoSizeToFalFormat(size)\n      const inputImageFields = mapImageInputsToFalVideoFields(\n        this.model,\n        resolved.images,\n      )\n      const videoFields = mapVideoInputsToFalFields(resolved.videos)\n      const audioFields = mapAudioInputsToFalFields(resolved.audios)\n\n      const input = {\n        ...sizeParams,\n        ...inputImageFields,\n        ...videoFields,\n        ...audioFields,\n        // modelOptions applied after derived media fields so explicit user\n        // overrides (video_url, reference_video_urls, audio_url, ...) win.\n        ...modelOptions,\n        // Media-only prompts omit the prompt field rather than sending an\n        // empty string (e.g. pure image-to-video endpoints).\n        ...(resolved.text ? { prompt: resolved.text } : {}),\n        ...(duration ? { duration } : {}),\n      } as FalModelInput<TModel>\n\n      // Submit to queue and get request ID. Request-specific abortSignal only —\n      // never via fal.config() (global; would cancel concurrent jobs).\n      const { request_id } = await fal.queue.submit(this.model, {\n        input,\n        ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),\n      })\n\n      return {\n        jobId: request_id,\n        model: this.model,\n      }\n    } catch (error) {\n      logger.errors('fal.createVideoJob fatal', {\n        error,\n        source: 'fal.createVideoJob',\n      })\n      throw error\n    }\n  }\n\n  async getVideoStatus(jobId: string): Promise<VideoStatusResult> {\n    const statusResponse = (await fal.queue.status(this.model, {\n      requestId: jobId,\n      logs: true,\n    })) as FalStatusResponse\n\n    return {\n      jobId,\n      status: mapFalStatusToVideoStatus(statusResponse.status),\n      ...(statusResponse.queue_position != null\n        ? {\n            progress: Math.max(0, 100 - statusResponse.queue_position * 10),\n          }\n        : {}),\n    }\n  }\n\n  async getVideoUrl(jobId: string): Promise<VideoUrlResult> {\n    let result\n    try {\n      result = await fal.queue.result(this.model, {\n        requestId: jobId,\n      })\n    } catch (error: unknown) {\n      // fal.ai may report COMPLETED status but throw on result fetch\n      // (e.g. 422 validation errors). Extract the detailed error info.\n      const err = error as { body?: { detail?: unknown }; message?: string }\n      const detail = err.body?.detail\n      if (Array.isArray(detail)) {\n        const messages = detail.map(\n          (d: { msg?: string; loc?: Array<string> }) =>\n            d.loc ? `${d.loc.join('.')}: ${d.msg}` : d.msg,\n        )\n        throw new Error(`Video generation failed: ${messages.join('; ')}`)\n      }\n      throw new Error(\n        `Failed to retrieve video result: ${err.message || String(error)}`,\n      )\n    }\n\n    const data = result.data as FalVideoResultData\n\n    // Different models return video URL in different formats\n    const url = data.video?.url || data.video_url\n    if (!url) {\n      throw new Error('Video URL not found in response')\n    }\n\n    const usage = buildFalUsage(takeBillableUnits(result.requestId))\n\n    return {\n      jobId,\n      url,\n      ...(usage ? { usage } : {}),\n    }\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n}\n\n/**\n * Create a fal.ai video adapter with an explicit API key.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function createFalVideo<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalVideoAdapter<TModel> {\n  return new FalVideoAdapter(model, config)\n}\n\n/**\n * Create a fal.ai video adapter using config.apiKey or the FAL_KEY environment variable.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function falVideo<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalVideoAdapter<TModel> {\n  return createFalVideo(model, config)\n}\n"],"mappings":"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"}
+{"version":3,"file":"video.js","names":[],"sources":["../../../src/adapters/video.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { resolveMediaPrompt } from '@tanstack/ai'\nimport { BaseVideoAdapter, snapToDurationOption } from '@tanstack/ai/adapters'\nimport {\n  configureFalClient,\n  generateId as utilGenerateId,\n} from '../utils/client'\nimport { buildFalUsage, takeBillableUnits } from '../utils/billing'\nimport {\n  getFalVideoDurationOptions,\n  mapVideoSizeToFalFormat,\n} from '../video/video-provider-options'\nimport { mapImageInputsToFalVideoFields } from '../image/image-inputs'\nimport type { DurationOptions } from '@tanstack/ai/adapters'\nimport type {\n  AudioPart,\n  MediaInputMetadata,\n  VideoGenerationOptions,\n  VideoJobResult,\n  VideoPart,\n  VideoStatusResult,\n  VideoUrlResult,\n} from '@tanstack/ai'\nimport type {\n  FalModel,\n  FalModelInput,\n  FalModelVideoDuration,\n  FalModelVideoSize,\n  FalVideoPromptModalitiesFor,\n  FalVideoProviderOptions,\n} from '../model-meta'\nimport type { FalClientConfig } from '../utils/client'\n\n/**\n * Map video conditioning inputs onto fal field names.\n * Video-to-video endpoints on fal almost universally use `video_url`; the\n * occasional model takes `video_urls` (rare). Mirror the image-input logic\n * positionally with a `reference` role escape hatch via `reference_video_urls`.\n */\nfunction mapVideoInputsToFalFields(\n  videoInputs?: ReadonlyArray<VideoPart<MediaInputMetadata>>,\n): Record<string, unknown> {\n  if (!videoInputs || videoInputs.length === 0) return {}\n  const references: Array<string> = []\n  const sources: Array<string> = []\n  for (const part of videoInputs) {\n    const url = videoPartToUrl(part)\n    if (\n      part.metadata?.role === 'reference' ||\n      part.metadata?.role === 'character'\n    ) {\n      references.push(url)\n    } else {\n      sources.push(url)\n    }\n  }\n  const out: Record<string, unknown> = {}\n  if (references.length > 0) out.reference_video_urls = references\n  if (sources.length === 1) {\n    out.video_url = sources[0]\n  } else if (sources.length > 1) {\n    out.video_urls = sources\n  }\n  return out\n}\n\nfunction mapAudioInputsToFalFields(\n  audioInputs?: ReadonlyArray<AudioPart<MediaInputMetadata>>,\n): Record<string, unknown> {\n  if (!audioInputs || audioInputs.length === 0) return {}\n  const [part, ...rest] = audioInputs\n  if (!part || rest.length > 0) {\n    throw new Error(\n      `fal: exactly one audio prompt part is supported (received ${audioInputs.length}).`,\n    )\n  }\n  return {\n    audio_url:\n      part.source.type === 'url'\n        ? part.source.value\n        : `data:${part.source.mimeType};base64,${part.source.value}`,\n  }\n}\n\nfunction videoPartToUrl(part: VideoPart<MediaInputMetadata>): string {\n  return part.source.type === 'url'\n    ? part.source.value\n    : `data:${part.source.mimeType};base64,${part.source.value}`\n}\n\ntype FalQueueStatus = 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED'\n\ninterface FalStatusResponse {\n  status: FalQueueStatus\n  queue_position?: number\n  logs?: Array<{ message: string }>\n}\n\ninterface FalVideoResultData {\n  video?: { url: string }\n  video_url?: string\n}\n\n/**\n * Maps fal.ai queue status to TanStack AI video status.\n *\n * Note: fal.ai does not return a FAILED queue status. Errors surface\n * as exceptions when fetching results from a COMPLETED job (e.g. 422\n * validation errors). Those are handled in getVideoUrl().\n */\nfunction mapFalStatusToVideoStatus(\n  falStatus: FalQueueStatus,\n): VideoStatusResult['status'] {\n  switch (falStatus) {\n    case 'IN_QUEUE':\n      return 'pending'\n    case 'IN_PROGRESS':\n      return 'processing'\n    case 'COMPLETED':\n      return 'completed'\n    default:\n      return 'processing'\n  }\n}\n\n/**\n * fal.ai video generation adapter.\n * Supports MiniMax, Luma, Kling, Hunyuan, and other fal.ai video models.\n *\n * Uses fal.ai's comprehensive type system to provide autocomplete\n * and type safety for all supported video models.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<\n  TModel,\n  FalVideoProviderOptions<TModel>,\n  Record<TModel, FalVideoProviderOptions<TModel>>,\n  Record<TModel, FalModelVideoSize<TModel>>,\n  Record<TModel, FalVideoPromptModalitiesFor<TModel>>,\n  Record<TModel, FalModelVideoDuration<TModel>>\n> {\n  override readonly kind = 'video' 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 createVideoJob(\n    options: VideoGenerationOptions<\n      FalVideoProviderOptions<TModel>,\n      FalModelVideoSize<TModel>,\n      FalModelVideoDuration<TModel>\n    >,\n  ): Promise<VideoJobResult> {\n    const { size, duration, modelOptions, logger } = options\n\n    logger.request(`activity=generateVideo provider=fal model=${this.model}`, {\n      provider: 'fal',\n      model: this.model,\n    })\n\n    try {\n      const resolved = resolveMediaPrompt(options.prompt)\n      const sizeParams = mapVideoSizeToFalFormat(size)\n      const inputImageFields = mapImageInputsToFalVideoFields(\n        this.model,\n        resolved.images,\n      )\n      const videoFields = mapVideoInputsToFalFields(resolved.videos)\n      const audioFields = mapAudioInputsToFalFields(resolved.audios)\n\n      const input = {\n        ...sizeParams,\n        ...inputImageFields,\n        ...videoFields,\n        ...audioFields,\n        // modelOptions applied after derived media fields so explicit user\n        // overrides (video_url, reference_video_urls, audio_url, ...) win.\n        ...modelOptions,\n        // Media-only prompts omit the prompt field rather than sending an\n        // empty string (e.g. pure image-to-video endpoints).\n        ...(resolved.text ? { prompt: resolved.text } : {}),\n        ...(duration !== undefined ? { duration } : {}),\n      } as FalModelInput<TModel>\n\n      // Submit to queue and get request ID. Request-specific abortSignal only —\n      // never via fal.config() (global; would cancel concurrent jobs).\n      const { request_id } = await fal.queue.submit(this.model, {\n        input,\n        ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),\n      })\n\n      return {\n        jobId: request_id,\n        model: this.model,\n      }\n    } catch (error) {\n      logger.errors('fal.createVideoJob fatal', {\n        error,\n        source: 'fal.createVideoJob',\n      })\n      throw error\n    }\n  }\n\n  override availableDurations(): DurationOptions<\n    FalModelVideoDuration<TModel>\n  > {\n    return getFalVideoDurationOptions(this.model)\n  }\n\n  override snapDuration(\n    seconds: number,\n  ): FalModelVideoDuration<TModel> | undefined {\n    return snapToDurationOption(seconds, this.availableDurations())\n  }\n\n  async getVideoStatus(jobId: string): Promise<VideoStatusResult> {\n    const statusResponse = (await fal.queue.status(this.model, {\n      requestId: jobId,\n      logs: true,\n    })) as FalStatusResponse\n\n    return {\n      jobId,\n      status: mapFalStatusToVideoStatus(statusResponse.status),\n      ...(statusResponse.queue_position != null\n        ? {\n            progress: Math.max(0, 100 - statusResponse.queue_position * 10),\n          }\n        : {}),\n    }\n  }\n\n  async getVideoUrl(jobId: string): Promise<VideoUrlResult> {\n    let result\n    try {\n      result = await fal.queue.result(this.model, {\n        requestId: jobId,\n      })\n    } catch (error: unknown) {\n      // fal.ai may report COMPLETED status but throw on result fetch\n      // (e.g. 422 validation errors). Extract the detailed error info.\n      const err = error as { body?: { detail?: unknown }; message?: string }\n      const detail = err.body?.detail\n      if (Array.isArray(detail)) {\n        const messages = detail.map(\n          (d: { msg?: string; loc?: Array<string> }) =>\n            d.loc ? `${d.loc.join('.')}: ${d.msg}` : d.msg,\n        )\n        throw new Error(`Video generation failed: ${messages.join('; ')}`)\n      }\n      throw new Error(\n        `Failed to retrieve video result: ${err.message || String(error)}`,\n      )\n    }\n\n    const data = result.data as FalVideoResultData\n\n    // Different models return video URL in different formats\n    const url = data.video?.url || data.video_url\n    if (!url) {\n      throw new Error('Video URL not found in response')\n    }\n\n    const usage = buildFalUsage(takeBillableUnits(result.requestId))\n\n    return {\n      jobId,\n      url,\n      ...(usage ? { usage } : {}),\n    }\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n}\n\n/**\n * Create a fal.ai video adapter with an explicit API key.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function createFalVideo<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalVideoAdapter<TModel> {\n  return new FalVideoAdapter(model, config)\n}\n\n/**\n * Create a fal.ai video adapter using config.apiKey or the FAL_KEY environment variable.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function falVideo<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalVideoAdapter<TModel> {\n  return createFalVideo(model, config)\n}\n"],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -3,5 +3,5 @@ export { FalVideoAdapter, falVideo } from './adapters/video.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 { type FalImageProviderOptions, type FalVideoProviderOptions, type FalSpeechProviderOptions, type FalTranscriptionProviderOptions, type FalAudioProviderOptions, type FalModel, type FalModelInput, type FalModelOutput, type FalModelImageSize, type FalModelVideoSize, type FalModelVideoDuration, } from './model-meta.js';
 export { getFalApiKeyFromEnv, configureFalClient, generateId, type FalClientConfig, } from './utils/client.js';

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

@@ -88,6 +88,21 @@ export type FalModelVideoSizeInput<TModel extends string> = TModel extends keyof
     aspect_ratio?: string;
     resolution?: string;
 };
+/**
+ * Extract the `duration` field type from a fal video model's input.
+ * Falls back to `string | number | undefined` for models not in the SDK's
+ * `EndpointTypeMap`.
+ *
+ * Shapes seen in the wild:
+ *  - `'5' | '10'` (Kling, Pika): discrete numeric strings
+ *  - `'5s' | '9s'` (Luma): keyword strings with unit
+ *  - `'4s' | '6s' | '8s'` (Veo3 via FAL): keyword strings
+ *  - `'2' | … | '15'` (WAN-25): discrete-range numeric strings
+ *  - undefined (Minimax, Hunyuan): no duration field; passing one is a type error
+ */
+export type FalModelVideoDuration<TModel extends string> = TModel extends keyof EndpointTypeMap ? 'duration' extends keyof EndpointTypeMap[TModel]['input'] ? Extract<NonNullable<EndpointTypeMap[TModel]['input'] extends {
+    duration?: infer D;
+} ? D : never>, string | number> : undefined : string | number | undefined;
 /**
  * Prompt input modalities for a fal image endpoint, derived from the SDK's
  * endpoint input type: an endpoint accepts image prompt parts exactly when
@@ -111,7 +126,7 @@ export type FalVideoPromptModalitiesFor<TModel extends string> = TModel extends
  * video/audio) are optional here even when the endpoint requires them —
  * they're usually supplied as prompt parts instead.
  */
-export type FalVideoProviderOptions<TModel extends string> = TModel extends keyof EndpointTypeMap ? WithOptionalMediaInputFields<Omit<FalModelInput<TModel>, 'prompt'>> : Record<string, unknown>;
+export type FalVideoProviderOptions<TModel extends string> = TModel extends keyof EndpointTypeMap ? WithOptionalMediaInputFields<Omit<FalModelInput<TModel>, 'prompt' | 'duration'>> : Record<string, unknown>;
 /**
  * Provider options for TTS, excluding fields TanStack AI handles.
  * Use this for the `modelOptions` parameter in speech generation.

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

@@ -19,9 +19,10 @@ export declare function takeBillableUnits(requestId: string | undefined): number
 /**
  * Build a {@link TokenUsage} carrying fal's billed quantity. Media generation has
  * no tokens, so the token fields are zero and the real billing signal rides on
- * `unitsBilled` — mirroring how the duration-billed transcription adapters
- * surface `durationSeconds`. Returns `undefined` when no units were captured so
- * callers can omit `usage` entirely.
+ * `billed`, denominated in `'units'` — fal's priced unit is endpoint-defined
+ * (its pricing page maps each endpoint to a unit price), so the count is opaque
+ * by design. Returns `undefined` when no units were captured so callers can
+ * omit `usage` entirely.
  */
 export declare function buildFalUsage(unitsBilled: number | undefined): TokenUsage | undefined;
 /**

package/dist/esm/utils/billing.js

@@ -59,9 +59,10 @@ function takeBillableUnits(requestId) {
 /**
 * Build a {@link TokenUsage} carrying fal's billed quantity. Media generation has
 * no tokens, so the token fields are zero and the real billing signal rides on
-* `unitsBilled` — mirroring how the duration-billed transcription adapters
-* surface `durationSeconds`. Returns `undefined` when no units were captured so
-* callers can omit `usage` entirely.
+* `billed`, denominated in `'units'` — fal's priced unit is endpoint-defined
+* (its pricing page maps each endpoint to a unit price), so the count is opaque
+* by design. Returns `undefined` when no units were captured so callers can
+* omit `usage` entirely.
 */
 function buildFalUsage(unitsBilled) {
 	if (unitsBilled == null) return void 0;
@@ -69,6 +70,10 @@ function buildFalUsage(unitsBilled) {
 		promptTokens: 0,
 		completionTokens: 0,
 		totalTokens: 0,
+		billed: {
+			quantity: unitsBilled,
+			unit: "units"
+		},
 		unitsBilled
 	};
 }

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

@@ -1 +1 @@
-{"version":3,"file":"billing.js","names":[],"sources":["../../../src/utils/billing.ts"],"sourcesContent":["import type { TokenUsage } from '@tanstack/ai'\n\n/**\n * Response header fal sets on a queue *result* fetch carrying the real billed\n * quantity for the generation, denominated in the endpoint's priced unit.\n */\nconst FAL_BILLABLE_UNITS_HEADER = 'x-fal-billable-units'\n\n/**\n * Response header fal sets carrying the request id. The fal client surfaces this\n * same value as `Result.requestId`, so keying captured billable units by it\n * guarantees the adapter's lookup matches the fetch the units came from — no URL\n * parsing or global correlation registry of our own design needed.\n */\nconst FAL_REQUEST_ID_HEADER = 'x-fal-request-id'\n\n/**\n * Upper bound on retained, not-yet-consumed billable-unit entries. Each\n * successful generation reads-and-deletes its entry (see {@link takeBillableUnits}),\n * so this only guards against an unbounded leak when a result fetch records units\n * but the adapter never resolves (e.g. it throws before reading). When the cap is\n * exceeded the oldest entry is evicted (Map preserves insertion order).\n */\nconst MAX_PENDING_ENTRIES = 256\n\nconst billableUnitsByRequestId = new Map<string, number>()\n\n/**\n * Parse the `x-fal-billable-units` header value into a finite number. Returns\n * `undefined` for a missing or non-numeric value so callers can skip attaching\n * usage rather than surfacing `NaN`.\n */\nexport function parseBillableUnits(value: string | null): number | undefined {\n  if (value == null || value === '') return undefined\n  const parsed = Number(value)\n  return Number.isFinite(parsed) ? parsed : undefined\n}\n\n/**\n * Record the billable units carried by a fal result response, keyed by the\n * request id from the same response. Reading headers does not consume the body,\n * so the response can be returned to the fal client untouched.\n */\nexport function recordBillableUnitsFromResponse(response: Response): void {\n  const units = parseBillableUnits(\n    response.headers.get(FAL_BILLABLE_UNITS_HEADER),\n  )\n  if (units == null) return\n  const requestId = response.headers.get(FAL_REQUEST_ID_HEADER)\n  if (!requestId) return\n  if (\n    billableUnitsByRequestId.size >= MAX_PENDING_ENTRIES &&\n    !billableUnitsByRequestId.has(requestId)\n  ) {\n    const oldest = billableUnitsByRequestId.keys().next().value\n    if (oldest !== undefined) billableUnitsByRequestId.delete(oldest)\n  }\n  billableUnitsByRequestId.set(requestId, units)\n}\n\n/**\n * Read and remove the billable units recorded for a request id. Removing on read\n * keeps the registry from growing across the lifetime of the process.\n */\nexport function takeBillableUnits(\n  requestId: string | undefined,\n): number | undefined {\n  if (!requestId) return undefined\n  const units = billableUnitsByRequestId.get(requestId)\n  if (units !== undefined) billableUnitsByRequestId.delete(requestId)\n  return units\n}\n\n/**\n * Build a {@link TokenUsage} carrying fal's billed quantity. Media generation has\n * no tokens, so the token fields are zero and the real billing signal rides on\n * `unitsBilled` — mirroring how the duration-billed transcription adapters\n * surface `durationSeconds`. Returns `undefined` when no units were captured so\n * callers can omit `usage` entirely.\n */\nexport function buildFalUsage(\n  unitsBilled: number | undefined,\n): TokenUsage | undefined {\n  if (unitsBilled == null) return undefined\n  return {\n    promptTokens: 0,\n    completionTokens: 0,\n    totalTokens: 0,\n    unitsBilled,\n  }\n}\n\n/**\n * Wrap a fetch so every fal request's response is inspected for the\n * `x-fal-billable-units` header before being returned untouched. Installed as\n * fal's `config.fetch`, which (unlike a global `responseHandler`) is honoured for\n * every request — the fal client forces `resultResponseHandler` per queue\n * operation, clobbering any configured response handler.\n *\n * `baseFetch` is the underlying implementation to delegate to (defaults to the\n * global `fetch`). Injecting it keeps usage capture working when a caller\n * supplies a custom fetch — a proxy, instrumentation, or a test mock — without\n * mutating any global.\n */\nexport function createBillingFetch(\n  baseFetch: typeof fetch = globalThis.fetch,\n): typeof fetch {\n  return async (input, init) => {\n    const response = await baseFetch(input, init)\n    try {\n      recordBillableUnitsFromResponse(response)\n    } catch {\n      // Capturing usage must never break the underlying request.\n    }\n    return response\n  }\n}\n"],"mappings":";;;;;AAMA,IAAM,4BAA4B;;;;;;;AAQlC,IAAM,wBAAwB;;;;;;;;AAS9B,IAAM,sBAAsB;AAE5B,IAAM,2CAA2B,IAAI,IAAoB;;;;;;AAOzD,SAAgB,mBAAmB,OAA0C;CAC3E,IAAI,SAAS,QAAQ,UAAU,IAAI,OAAO,KAAA;CAC1C,MAAM,SAAS,OAAO,KAAK;CAC3B,OAAO,OAAO,SAAS,MAAM,IAAI,SAAS,KAAA;AAC5C;;;;;;AAOA,SAAgB,gCAAgC,UAA0B;CACxE,MAAM,QAAQ,mBACZ,SAAS,QAAQ,IAAI,yBAAyB,CAChD;CACA,IAAI,SAAS,MAAM;CACnB,MAAM,YAAY,SAAS,QAAQ,IAAI,qBAAqB;CAC5D,IAAI,CAAC,WAAW;CAChB,IACE,yBAAyB,QAAQ,uBACjC,CAAC,yBAAyB,IAAI,SAAS,GACvC;EACA,MAAM,SAAS,yBAAyB,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;EACtD,IAAI,WAAW,KAAA,GAAW,yBAAyB,OAAO,MAAM;CAClE;CACA,yBAAyB,IAAI,WAAW,KAAK;AAC/C;;;;;AAMA,SAAgB,kBACd,WACoB;CACpB,IAAI,CAAC,WAAW,OAAO,KAAA;CACvB,MAAM,QAAQ,yBAAyB,IAAI,SAAS;CACpD,IAAI,UAAU,KAAA,GAAW,yBAAyB,OAAO,SAAS;CAClE,OAAO;AACT;;;;;;;;AASA,SAAgB,cACd,aACwB;CACxB,IAAI,eAAe,MAAM,OAAO,KAAA;CAChC,OAAO;EACL,cAAc;EACd,kBAAkB;EAClB,aAAa;EACb;CACF;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBACd,YAA0B,WAAW,OACvB;CACd,OAAO,OAAO,OAAO,SAAS;EAC5B,MAAM,WAAW,MAAM,UAAU,OAAO,IAAI;EAC5C,IAAI;GACF,gCAAgC,QAAQ;EAC1C,QAAQ,CAER;EACA,OAAO;CACT;AACF"}
+{"version":3,"file":"billing.js","names":[],"sources":["../../../src/utils/billing.ts"],"sourcesContent":["import type { TokenUsage } from '@tanstack/ai'\n\n/**\n * Response header fal sets on a queue *result* fetch carrying the real billed\n * quantity for the generation, denominated in the endpoint's priced unit.\n */\nconst FAL_BILLABLE_UNITS_HEADER = 'x-fal-billable-units'\n\n/**\n * Response header fal sets carrying the request id. The fal client surfaces this\n * same value as `Result.requestId`, so keying captured billable units by it\n * guarantees the adapter's lookup matches the fetch the units came from — no URL\n * parsing or global correlation registry of our own design needed.\n */\nconst FAL_REQUEST_ID_HEADER = 'x-fal-request-id'\n\n/**\n * Upper bound on retained, not-yet-consumed billable-unit entries. Each\n * successful generation reads-and-deletes its entry (see {@link takeBillableUnits}),\n * so this only guards against an unbounded leak when a result fetch records units\n * but the adapter never resolves (e.g. it throws before reading). When the cap is\n * exceeded the oldest entry is evicted (Map preserves insertion order).\n */\nconst MAX_PENDING_ENTRIES = 256\n\nconst billableUnitsByRequestId = new Map<string, number>()\n\n/**\n * Parse the `x-fal-billable-units` header value into a finite number. Returns\n * `undefined` for a missing or non-numeric value so callers can skip attaching\n * usage rather than surfacing `NaN`.\n */\nexport function parseBillableUnits(value: string | null): number | undefined {\n  if (value == null || value === '') return undefined\n  const parsed = Number(value)\n  return Number.isFinite(parsed) ? parsed : undefined\n}\n\n/**\n * Record the billable units carried by a fal result response, keyed by the\n * request id from the same response. Reading headers does not consume the body,\n * so the response can be returned to the fal client untouched.\n */\nexport function recordBillableUnitsFromResponse(response: Response): void {\n  const units = parseBillableUnits(\n    response.headers.get(FAL_BILLABLE_UNITS_HEADER),\n  )\n  if (units == null) return\n  const requestId = response.headers.get(FAL_REQUEST_ID_HEADER)\n  if (!requestId) return\n  if (\n    billableUnitsByRequestId.size >= MAX_PENDING_ENTRIES &&\n    !billableUnitsByRequestId.has(requestId)\n  ) {\n    const oldest = billableUnitsByRequestId.keys().next().value\n    if (oldest !== undefined) billableUnitsByRequestId.delete(oldest)\n  }\n  billableUnitsByRequestId.set(requestId, units)\n}\n\n/**\n * Read and remove the billable units recorded for a request id. Removing on read\n * keeps the registry from growing across the lifetime of the process.\n */\nexport function takeBillableUnits(\n  requestId: string | undefined,\n): number | undefined {\n  if (!requestId) return undefined\n  const units = billableUnitsByRequestId.get(requestId)\n  if (units !== undefined) billableUnitsByRequestId.delete(requestId)\n  return units\n}\n\n/**\n * Build a {@link TokenUsage} carrying fal's billed quantity. Media generation has\n * no tokens, so the token fields are zero and the real billing signal rides on\n * `billed`, denominated in `'units'` — fal's priced unit is endpoint-defined\n * (its pricing page maps each endpoint to a unit price), so the count is opaque\n * by design. Returns `undefined` when no units were captured so callers can\n * omit `usage` entirely.\n */\nexport function buildFalUsage(\n  unitsBilled: number | undefined,\n): TokenUsage | undefined {\n  if (unitsBilled == null) return undefined\n  return {\n    promptTokens: 0,\n    completionTokens: 0,\n    totalTokens: 0,\n    billed: { quantity: unitsBilled, unit: 'units' },\n    unitsBilled,\n  }\n}\n\n/**\n * Wrap a fetch so every fal request's response is inspected for the\n * `x-fal-billable-units` header before being returned untouched. Installed as\n * fal's `config.fetch`, which (unlike a global `responseHandler`) is honoured for\n * every request — the fal client forces `resultResponseHandler` per queue\n * operation, clobbering any configured response handler.\n *\n * `baseFetch` is the underlying implementation to delegate to (defaults to the\n * global `fetch`). Injecting it keeps usage capture working when a caller\n * supplies a custom fetch — a proxy, instrumentation, or a test mock — without\n * mutating any global.\n */\nexport function createBillingFetch(\n  baseFetch: typeof fetch = globalThis.fetch,\n): typeof fetch {\n  return async (input, init) => {\n    const response = await baseFetch(input, init)\n    try {\n      recordBillableUnitsFromResponse(response)\n    } catch {\n      // Capturing usage must never break the underlying request.\n    }\n    return response\n  }\n}\n"],"mappings":";;;;;AAMA,IAAM,4BAA4B;;;;;;;AAQlC,IAAM,wBAAwB;;;;;;;;AAS9B,IAAM,sBAAsB;AAE5B,IAAM,2CAA2B,IAAI,IAAoB;;;;;;AAOzD,SAAgB,mBAAmB,OAA0C;CAC3E,IAAI,SAAS,QAAQ,UAAU,IAAI,OAAO,KAAA;CAC1C,MAAM,SAAS,OAAO,KAAK;CAC3B,OAAO,OAAO,SAAS,MAAM,IAAI,SAAS,KAAA;AAC5C;;;;;;AAOA,SAAgB,gCAAgC,UAA0B;CACxE,MAAM,QAAQ,mBACZ,SAAS,QAAQ,IAAI,yBAAyB,CAChD;CACA,IAAI,SAAS,MAAM;CACnB,MAAM,YAAY,SAAS,QAAQ,IAAI,qBAAqB;CAC5D,IAAI,CAAC,WAAW;CAChB,IACE,yBAAyB,QAAQ,uBACjC,CAAC,yBAAyB,IAAI,SAAS,GACvC;EACA,MAAM,SAAS,yBAAyB,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;EACtD,IAAI,WAAW,KAAA,GAAW,yBAAyB,OAAO,MAAM;CAClE;CACA,yBAAyB,IAAI,WAAW,KAAK;AAC/C;;;;;AAMA,SAAgB,kBACd,WACoB;CACpB,IAAI,CAAC,WAAW,OAAO,KAAA;CACvB,MAAM,QAAQ,yBAAyB,IAAI,SAAS;CACpD,IAAI,UAAU,KAAA,GAAW,yBAAyB,OAAO,SAAS;CAClE,OAAO;AACT;;;;;;;;;AAUA,SAAgB,cACd,aACwB;CACxB,IAAI,eAAe,MAAM,OAAO,KAAA;CAChC,OAAO;EACL,cAAc;EACd,kBAAkB;EAClB,aAAa;EACb,QAAQ;GAAE,UAAU;GAAa,MAAM;EAAQ;EAC/C;CACF;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBACd,YAA0B,WAAW,OACvB;CACd,OAAO,OAAO,OAAO,SAAS;EAC5B,MAAM,WAAW,MAAM,UAAU,OAAO,IAAI;EAC5C,IAAI;GACF,gCAAgC,QAAQ;EAC1C,QAAQ,CAER;EACA,OAAO;CACT;AACF"}

package/dist/esm/video/video-provider-options.d.ts

@@ -1,2 +1,4 @@
-import { FalModelVideoSize, FalModelVideoSizeInput } from '../model-meta.js';
-export declare function mapVideoSizeToFalFormat<TModel extends string>(size: FalModelVideoSize<TModel> | undefined): FalModelVideoSizeInput<TModel> | undefined;
+import { DurationOptions } from '@tanstack/ai/adapters';
+import { FalModelVideoDuration, FalModelVideoSize, FalModelVideoSizeInput } from '../model-meta.js';
+export declare function mapVideoSizeToFalFormat<TModel extends string>(size?: FalModelVideoSize<TModel>): FalModelVideoSizeInput<TModel>;
+export declare function getFalVideoDurationOptions<TModel extends string>(model: TModel): DurationOptions<FalModelVideoDuration<TModel>>;

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

@@ -1,17 +1,119 @@
 //#region src/video/video-provider-options.ts
 function mapVideoSizeToFalFormat(size) {
-	if (!size) return void 0;
+	if (!size) return {};
 	if (size.includes("_")) {
-		const [aspect_ratio, resolution] = size.split("_");
+		const [aspectRatio, resolution] = size.split("_");
 		return {
-			aspect_ratio,
+			aspect_ratio: aspectRatio,
 			resolution
 		};
 	}
 	if (size.includes(":")) return { aspect_ratio: size };
 	return { resolution: size };
 }
+/**
+* Identity helper that checks each entry against the SDK's `duration` union
+* for its own key, so a typo'd endpoint id or a stale union fails to compile.
+*/
+function durationMap(map) {
+	return map;
+}
+var KLING_5_10 = {
+	kind: "discrete",
+	values: ["5", "10"]
+};
+var VEO_4_6_8 = {
+	kind: "discrete",
+	values: [
+		"4s",
+		"6s",
+		"8s"
+	]
+};
+var LTX_6_8_10 = {
+	kind: "discrete",
+	values: [
+		"6",
+		"8",
+		"10"
+	]
+};
+var KLING_3_15 = {
+	kind: "discrete",
+	values: [
+		"3",
+		"4",
+		"5",
+		"6",
+		"7",
+		"8",
+		"9",
+		"10",
+		"11",
+		"12",
+		"13",
+		"14",
+		"15"
+	]
+};
+/**
+* Curated map of per-model duration options for popular fal.ai video models.
+* Values are checked at compile time against `@fal-ai/client`'s
+* `EndpointTypeMap` input types via `durationMap`.
+*
+* Models not listed here fall back to `{ kind: 'none' }` — honest "we don't
+* know" rather than guessing. The type-level `FalModelVideoDuration<TModel>`
+* still derives from the SDK types, so autocomplete works for SDK-known
+* models that aren't curated here.
+*/
+var FAL_VIDEO_DURATIONS = durationMap({
+	"fal-ai/kling-video/v1.6/standard/text-to-video": KLING_5_10,
+	"fal-ai/kling-video/v1.6/pro/text-to-video": KLING_5_10,
+	"fal-ai/kling-video/v2.6/pro/text-to-video": KLING_5_10,
+	"fal-ai/kling-video/v2.6/pro/image-to-video": KLING_5_10,
+	"fal-ai/kling-video/v3/pro/text-to-video": KLING_3_15,
+	"fal-ai/kling-video/v3/pro/image-to-video": KLING_3_15,
+	"fal-ai/pika/v2.2/text-to-video": KLING_5_10,
+	"fal-ai/luma-dream-machine/ray-2": {
+		kind: "discrete",
+		values: ["5s", "9s"]
+	},
+	"fal-ai/veo3": VEO_4_6_8,
+	"fal-ai/veo3/image-to-video": VEO_4_6_8,
+	"fal-ai/veo3.1": VEO_4_6_8,
+	"fal-ai/veo3.1/image-to-video": VEO_4_6_8,
+	"fal-ai/veo3.1/fast": VEO_4_6_8,
+	"fal-ai/veo3.1/fast/image-to-video": VEO_4_6_8,
+	"fal-ai/ltx-2.3/text-to-video": LTX_6_8_10,
+	"fal-ai/ltx-2.3/text-to-video/fast": LTX_6_8_10,
+	"fal-ai/ltx-2.3/image-to-video": LTX_6_8_10,
+	"fal-ai/ltx-2.3/image-to-video/fast": LTX_6_8_10,
+	"fal-ai/wan-25-preview/text-to-video": {
+		kind: "discrete",
+		values: [
+			"2",
+			"3",
+			"4",
+			"5",
+			"6",
+			"7",
+			"8",
+			"9",
+			"10",
+			"11",
+			"12",
+			"13",
+			"14",
+			"15"
+		]
+	},
+	"fal-ai/minimax/video-01": { kind: "none" },
+	"fal-ai/hunyuan-video-v1.5/text-to-video": { kind: "none" }
+});
+function getFalVideoDurationOptions(model) {
+	return FAL_VIDEO_DURATIONS[model] ?? { kind: "none" };
+}
 //#endregion
-export { mapVideoSizeToFalFormat };
+export { getFalVideoDurationOptions, mapVideoSizeToFalFormat };
 
 //# sourceMappingURL=video-provider-options.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"video-provider-options.js","names":[],"sources":["../../../src/video/video-provider-options.ts"],"sourcesContent":["import type { FalModelVideoSize, FalModelVideoSizeInput } from '../model-meta'\n\nexport function mapVideoSizeToFalFormat<TModel extends string>(\n  size: FalModelVideoSize<TModel> | undefined,\n): FalModelVideoSizeInput<TModel> | undefined {\n  if (!size) return undefined\n\n  // \"16:9_720p\" → { aspect_ratio, resolution }\n  // \"16:9\"      → { aspect_ratio }\n  // \"720p\"      → { resolution }\n  if (size.includes('_')) {\n    const [aspect_ratio, resolution] = size.split('_')\n    return {\n      aspect_ratio,\n      resolution,\n    } as FalModelVideoSizeInput<TModel>\n  }\n\n  if (size.includes(':')) {\n    return { aspect_ratio: size } as FalModelVideoSizeInput<TModel>\n  }\n\n  return { resolution: size } as FalModelVideoSizeInput<TModel>\n}\n"],"mappings":";AAEA,SAAgB,wBACd,MAC4C;CAC5C,IAAI,CAAC,MAAM,OAAO,KAAA;CAKlB,IAAI,KAAK,SAAS,GAAG,GAAG;EACtB,MAAM,CAAC,cAAc,cAAc,KAAK,MAAM,GAAG;EACjD,OAAO;GACL;GACA;EACF;CACF;CAEA,IAAI,KAAK,SAAS,GAAG,GACnB,OAAO,EAAE,cAAc,KAAK;CAG9B,OAAO,EAAE,YAAY,KAAK;AAC5B"}
+{"version":3,"file":"video-provider-options.js","names":[],"sources":["../../../src/video/video-provider-options.ts"],"sourcesContent":["import type { DurationOptions } from '@tanstack/ai/adapters'\nimport type {\n  FalModelVideoDuration,\n  FalModelVideoSize,\n  FalModelVideoSizeInput,\n} from '../model-meta'\n\nexport function mapVideoSizeToFalFormat<TModel extends string>(\n  size?: FalModelVideoSize<TModel>,\n): FalModelVideoSizeInput<TModel> {\n  if (!size) {\n    return {} as FalModelVideoSizeInput<TModel>\n  }\n\n  if (size.includes('_')) {\n    const [aspectRatio, resolution] = size.split('_')\n    return {\n      aspect_ratio: aspectRatio,\n      resolution,\n    } as FalModelVideoSizeInput<TModel>\n  }\n\n  if (size.includes(':')) {\n    return { aspect_ratio: size } as FalModelVideoSizeInput<TModel>\n  }\n\n  return { resolution: size } as FalModelVideoSizeInput<TModel>\n}\n\n/**\n * Identity helper that checks each entry against the SDK's `duration` union\n * for its own key, so a typo'd endpoint id or a stale union fails to compile.\n */\nfunction durationMap<\n  const T extends {\n    [K in keyof T & string]: DurationOptions<FalModelVideoDuration<K>>\n  },\n>(map: T): T {\n  return map\n}\n\nconst KLING_5_10 = { kind: 'discrete', values: ['5', '10'] } as const\nconst VEO_4_6_8 = { kind: 'discrete', values: ['4s', '6s', '8s'] } as const\nconst LTX_6_8_10 = { kind: 'discrete', values: ['6', '8', '10'] } as const\nconst KLING_3_15 = {\n  kind: 'discrete',\n  values: [\n    '3',\n    '4',\n    '5',\n    '6',\n    '7',\n    '8',\n    '9',\n    '10',\n    '11',\n    '12',\n    '13',\n    '14',\n    '15',\n  ],\n} as const\n\n/**\n * Curated map of per-model duration options for popular fal.ai video models.\n * Values are checked at compile time against `@fal-ai/client`'s\n * `EndpointTypeMap` input types via `durationMap`.\n *\n * Models not listed here fall back to `{ kind: 'none' }` — honest \"we don't\n * know\" rather than guessing. The type-level `FalModelVideoDuration<TModel>`\n * still derives from the SDK types, so autocomplete works for SDK-known\n * models that aren't curated here.\n */\nconst FAL_VIDEO_DURATIONS = durationMap({\n  'fal-ai/kling-video/v1.6/standard/text-to-video': KLING_5_10,\n  'fal-ai/kling-video/v1.6/pro/text-to-video': KLING_5_10,\n  'fal-ai/kling-video/v2.6/pro/text-to-video': KLING_5_10,\n  'fal-ai/kling-video/v2.6/pro/image-to-video': KLING_5_10,\n  'fal-ai/kling-video/v3/pro/text-to-video': KLING_3_15,\n  'fal-ai/kling-video/v3/pro/image-to-video': KLING_3_15,\n  'fal-ai/pika/v2.2/text-to-video': KLING_5_10,\n  'fal-ai/luma-dream-machine/ray-2': {\n    kind: 'discrete',\n    values: ['5s', '9s'],\n  },\n  'fal-ai/veo3': VEO_4_6_8,\n  'fal-ai/veo3/image-to-video': VEO_4_6_8,\n  'fal-ai/veo3.1': VEO_4_6_8,\n  'fal-ai/veo3.1/image-to-video': VEO_4_6_8,\n  'fal-ai/veo3.1/fast': VEO_4_6_8,\n  'fal-ai/veo3.1/fast/image-to-video': VEO_4_6_8,\n  'fal-ai/ltx-2.3/text-to-video': LTX_6_8_10,\n  'fal-ai/ltx-2.3/text-to-video/fast': LTX_6_8_10,\n  'fal-ai/ltx-2.3/image-to-video': LTX_6_8_10,\n  'fal-ai/ltx-2.3/image-to-video/fast': LTX_6_8_10,\n  'fal-ai/wan-25-preview/text-to-video': {\n    kind: 'discrete',\n    values: [\n      '2',\n      '3',\n      '4',\n      '5',\n      '6',\n      '7',\n      '8',\n      '9',\n      '10',\n      '11',\n      '12',\n      '13',\n      '14',\n      '15',\n    ],\n  },\n  'fal-ai/minimax/video-01': { kind: 'none' },\n  'fal-ai/hunyuan-video-v1.5/text-to-video': { kind: 'none' },\n})\n\nexport function getFalVideoDurationOptions<TModel extends string>(\n  model: TModel,\n): DurationOptions<FalModelVideoDuration<TModel>> {\n  const entry = (FAL_VIDEO_DURATIONS as Record<string, unknown>)[model]\n  // The map is keyed by literal ids but the adapter's TModel is an open string;\n  // the lookup result can't be correlated by TS, hence the one cast here.\n  return (entry ?? { kind: 'none' }) as DurationOptions<\n    FalModelVideoDuration<TModel>\n  >\n}\n"],"mappings":";AAOA,SAAgB,wBACd,MACgC;CAChC,IAAI,CAAC,MACH,OAAO,CAAC;CAGV,IAAI,KAAK,SAAS,GAAG,GAAG;EACtB,MAAM,CAAC,aAAa,cAAc,KAAK,MAAM,GAAG;EAChD,OAAO;GACL,cAAc;GACd;EACF;CACF;CAEA,IAAI,KAAK,SAAS,GAAG,GACnB,OAAO,EAAE,cAAc,KAAK;CAG9B,OAAO,EAAE,YAAY,KAAK;AAC5B;;;;;AAMA,SAAS,YAIP,KAAW;CACX,OAAO;AACT;AAEA,IAAM,aAAa;CAAE,MAAM;CAAY,QAAQ,CAAC,KAAK,IAAI;AAAE;AAC3D,IAAM,YAAY;CAAE,MAAM;CAAY,QAAQ;EAAC;EAAM;EAAM;CAAI;AAAE;AACjE,IAAM,aAAa;CAAE,MAAM;CAAY,QAAQ;EAAC;EAAK;EAAK;CAAI;AAAE;AAChE,IAAM,aAAa;CACjB,MAAM;CACN,QAAQ;EACN;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF;AACF;;;;;;;;;;;AAYA,IAAM,sBAAsB,YAAY;CACtC,kDAAkD;CAClD,6CAA6C;CAC7C,6CAA6C;CAC7C,8CAA8C;CAC9C,2CAA2C;CAC3C,4CAA4C;CAC5C,kCAAkC;CAClC,mCAAmC;EACjC,MAAM;EACN,QAAQ,CAAC,MAAM,IAAI;CACrB;CACA,eAAe;CACf,8BAA8B;CAC9B,iBAAiB;CACjB,gCAAgC;CAChC,sBAAsB;CACtB,qCAAqC;CACrC,gCAAgC;CAChC,qCAAqC;CACrC,iCAAiC;CACjC,sCAAsC;CACtC,uCAAuC;EACrC,MAAM;EACN,QAAQ;GACN;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;GACA;EACF;CACF;CACA,2BAA2B,EAAE,MAAM,OAAO;CAC1C,2CAA2C,EAAE,MAAM,OAAO;AAC5D,CAAC;AAED,SAAgB,2BACd,OACgD;CAIhD,OAHe,oBAAgD,UAG9C,EAAE,MAAM,OAAO;AAGlC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-fal",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "fal.ai adapter for TanStack AI image, video, audio, speech, and transcription generation.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -54,10 +54,10 @@
   "devDependencies": {
     "@vitest/coverage-v8": "4.1.10",
     "vite": "^8.2.1",
-    "@tanstack/ai": "0.45.0"
+    "@tanstack/ai": "0.47.1"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.45.0"
+    "@tanstack/ai": "^0.47.1"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/video.ts

@@ -1,13 +1,17 @@
 import { fal } from '@fal-ai/client'
 import { resolveMediaPrompt } from '@tanstack/ai'
-import { BaseVideoAdapter } from '@tanstack/ai/adapters'
+import { BaseVideoAdapter, snapToDurationOption } from '@tanstack/ai/adapters'
 import {
   configureFalClient,
   generateId as utilGenerateId,
 } from '../utils/client'
 import { buildFalUsage, takeBillableUnits } from '../utils/billing'
-import { mapVideoSizeToFalFormat } from '../video/video-provider-options'
+import {
+  getFalVideoDurationOptions,
+  mapVideoSizeToFalFormat,
+} from '../video/video-provider-options'
 import { mapImageInputsToFalVideoFields } from '../image/image-inputs'
+import type { DurationOptions } from '@tanstack/ai/adapters'
 import type {
   AudioPart,
   MediaInputMetadata,
@@ -20,6 +24,7 @@ import type {
 import type {
   FalModel,
   FalModelInput,
+  FalModelVideoDuration,
   FalModelVideoSize,
   FalVideoPromptModalitiesFor,
   FalVideoProviderOptions,
@@ -132,7 +137,8 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
   FalVideoProviderOptions<TModel>,
   Record<TModel, FalVideoProviderOptions<TModel>>,
   Record<TModel, FalModelVideoSize<TModel>>,
-  Record<TModel, FalVideoPromptModalitiesFor<TModel>>
+  Record<TModel, FalVideoPromptModalitiesFor<TModel>>,
+  Record<TModel, FalModelVideoDuration<TModel>>
 > {
   override readonly kind = 'video' as const
   readonly name = 'fal' as const
@@ -145,7 +151,8 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
   async createVideoJob(
     options: VideoGenerationOptions<
       FalVideoProviderOptions<TModel>,
-      FalModelVideoSize<TModel>
+      FalModelVideoSize<TModel>,
+      FalModelVideoDuration<TModel>
     >,
   ): Promise<VideoJobResult> {
     const { size, duration, modelOptions, logger } = options
@@ -176,7 +183,7 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
         // Media-only prompts omit the prompt field rather than sending an
         // empty string (e.g. pure image-to-video endpoints).
         ...(resolved.text ? { prompt: resolved.text } : {}),
-        ...(duration ? { duration } : {}),
+        ...(duration !== undefined ? { duration } : {}),
       } as FalModelInput<TModel>
 
       // Submit to queue and get request ID. Request-specific abortSignal only —
@@ -199,6 +206,18 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
     }
   }
 
+  override availableDurations(): DurationOptions<
+    FalModelVideoDuration<TModel>
+  > {
+    return getFalVideoDurationOptions(this.model)
+  }
+
+  override snapDuration(
+    seconds: number,
+  ): FalModelVideoDuration<TModel> | undefined {
+    return snapToDurationOption(seconds, this.availableDurations())
+  }
+
   async getVideoStatus(jobId: string): Promise<VideoStatusResult> {
     const statusResponse = (await fal.queue.status(this.model, {
       requestId: jobId,

package/src/index.ts

@@ -46,6 +46,7 @@ export {
   type FalModelOutput,
   type FalModelImageSize,
   type FalModelVideoSize,
+  type FalModelVideoDuration,
 } from './model-meta'
 // ============================================================================
 // Utils

package/src/model-meta.ts

@@ -144,6 +144,32 @@ export type FalModelVideoSizeInput<TModel extends string> =
         : never
     : { aspect_ratio?: string; resolution?: string }
 
+/**
+ * Extract the `duration` field type from a fal video model's input.
+ * Falls back to `string | number | undefined` for models not in the SDK's
+ * `EndpointTypeMap`.
+ *
+ * Shapes seen in the wild:
+ *  - `'5' | '10'` (Kling, Pika): discrete numeric strings
+ *  - `'5s' | '9s'` (Luma): keyword strings with unit
+ *  - `'4s' | '6s' | '8s'` (Veo3 via FAL): keyword strings
+ *  - `'2' | … | '15'` (WAN-25): discrete-range numeric strings
+ *  - undefined (Minimax, Hunyuan): no duration field; passing one is a type error
+ */
+export type FalModelVideoDuration<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? 'duration' extends keyof EndpointTypeMap[TModel]['input']
+      ? Extract<
+          NonNullable<
+            EndpointTypeMap[TModel]['input'] extends { duration?: infer D }
+              ? D
+              : never
+          >,
+          string | number
+        >
+      : undefined
+    : string | number | undefined
+
 /**
  * Prompt input modalities for a fal image endpoint, derived from the SDK's
  * endpoint input type: an endpoint accepts image prompt parts exactly when
@@ -194,7 +220,9 @@ export type FalVideoPromptModalitiesFor<TModel extends string> =
  */
 export type FalVideoProviderOptions<TModel extends string> =
   TModel extends keyof EndpointTypeMap
-    ? WithOptionalMediaInputFields<Omit<FalModelInput<TModel>, 'prompt'>>
+    ? WithOptionalMediaInputFields<
+        Omit<FalModelInput<TModel>, 'prompt' | 'duration'>
+      >
     : Record<string, unknown>
 
 /**

package/src/utils/billing.ts

@@ -74,9 +74,10 @@ export function takeBillableUnits(
 /**
  * Build a {@link TokenUsage} carrying fal's billed quantity. Media generation has
  * no tokens, so the token fields are zero and the real billing signal rides on
- * `unitsBilled` — mirroring how the duration-billed transcription adapters
- * surface `durationSeconds`. Returns `undefined` when no units were captured so
- * callers can omit `usage` entirely.
+ * `billed`, denominated in `'units'` — fal's priced unit is endpoint-defined
+ * (its pricing page maps each endpoint to a unit price), so the count is opaque
+ * by design. Returns `undefined` when no units were captured so callers can
+ * omit `usage` entirely.
  */
 export function buildFalUsage(
   unitsBilled: number | undefined,
@@ -86,6 +87,7 @@ export function buildFalUsage(
     promptTokens: 0,
     completionTokens: 0,
     totalTokens: 0,
+    billed: { quantity: unitsBilled, unit: 'units' },
     unitsBilled,
   }
 }

package/src/video/video-provider-options.ts

@@ -1,17 +1,21 @@
-import type { FalModelVideoSize, FalModelVideoSizeInput } from '../model-meta'
+import type { DurationOptions } from '@tanstack/ai/adapters'
+import type {
+  FalModelVideoDuration,
+  FalModelVideoSize,
+  FalModelVideoSizeInput,
+} from '../model-meta'
 
 export function mapVideoSizeToFalFormat<TModel extends string>(
-  size: FalModelVideoSize<TModel> | undefined,
-): FalModelVideoSizeInput<TModel> | undefined {
-  if (!size) return undefined
+  size?: FalModelVideoSize<TModel>,
+): FalModelVideoSizeInput<TModel> {
+  if (!size) {
+    return {} as FalModelVideoSizeInput<TModel>
+  }
 
-  // "16:9_720p" → { aspect_ratio, resolution }
-  // "16:9"      → { aspect_ratio }
-  // "720p"      → { resolution }
   if (size.includes('_')) {
-    const [aspect_ratio, resolution] = size.split('_')
+    const [aspectRatio, resolution] = size.split('_')
     return {
-      aspect_ratio,
+      aspect_ratio: aspectRatio,
       resolution,
     } as FalModelVideoSizeInput<TModel>
   }
@@ -22,3 +26,103 @@ export function mapVideoSizeToFalFormat<TModel extends string>(
 
   return { resolution: size } as FalModelVideoSizeInput<TModel>
 }
+
+/**
+ * Identity helper that checks each entry against the SDK's `duration` union
+ * for its own key, so a typo'd endpoint id or a stale union fails to compile.
+ */
+function durationMap<
+  const T extends {
+    [K in keyof T & string]: DurationOptions<FalModelVideoDuration<K>>
+  },
+>(map: T): T {
+  return map
+}
+
+const KLING_5_10 = { kind: 'discrete', values: ['5', '10'] } as const
+const VEO_4_6_8 = { kind: 'discrete', values: ['4s', '6s', '8s'] } as const
+const LTX_6_8_10 = { kind: 'discrete', values: ['6', '8', '10'] } as const
+const KLING_3_15 = {
+  kind: 'discrete',
+  values: [
+    '3',
+    '4',
+    '5',
+    '6',
+    '7',
+    '8',
+    '9',
+    '10',
+    '11',
+    '12',
+    '13',
+    '14',
+    '15',
+  ],
+} as const
+
+/**
+ * Curated map of per-model duration options for popular fal.ai video models.
+ * Values are checked at compile time against `@fal-ai/client`'s
+ * `EndpointTypeMap` input types via `durationMap`.
+ *
+ * Models not listed here fall back to `{ kind: 'none' }` — honest "we don't
+ * know" rather than guessing. The type-level `FalModelVideoDuration<TModel>`
+ * still derives from the SDK types, so autocomplete works for SDK-known
+ * models that aren't curated here.
+ */
+const FAL_VIDEO_DURATIONS = durationMap({
+  'fal-ai/kling-video/v1.6/standard/text-to-video': KLING_5_10,
+  'fal-ai/kling-video/v1.6/pro/text-to-video': KLING_5_10,
+  'fal-ai/kling-video/v2.6/pro/text-to-video': KLING_5_10,
+  'fal-ai/kling-video/v2.6/pro/image-to-video': KLING_5_10,
+  'fal-ai/kling-video/v3/pro/text-to-video': KLING_3_15,
+  'fal-ai/kling-video/v3/pro/image-to-video': KLING_3_15,
+  'fal-ai/pika/v2.2/text-to-video': KLING_5_10,
+  'fal-ai/luma-dream-machine/ray-2': {
+    kind: 'discrete',
+    values: ['5s', '9s'],
+  },
+  'fal-ai/veo3': VEO_4_6_8,
+  'fal-ai/veo3/image-to-video': VEO_4_6_8,
+  'fal-ai/veo3.1': VEO_4_6_8,
+  'fal-ai/veo3.1/image-to-video': VEO_4_6_8,
+  'fal-ai/veo3.1/fast': VEO_4_6_8,
+  'fal-ai/veo3.1/fast/image-to-video': VEO_4_6_8,
+  'fal-ai/ltx-2.3/text-to-video': LTX_6_8_10,
+  'fal-ai/ltx-2.3/text-to-video/fast': LTX_6_8_10,
+  'fal-ai/ltx-2.3/image-to-video': LTX_6_8_10,
+  'fal-ai/ltx-2.3/image-to-video/fast': LTX_6_8_10,
+  'fal-ai/wan-25-preview/text-to-video': {
+    kind: 'discrete',
+    values: [
+      '2',
+      '3',
+      '4',
+      '5',
+      '6',
+      '7',
+      '8',
+      '9',
+      '10',
+      '11',
+      '12',
+      '13',
+      '14',
+      '15',
+    ],
+  },
+  'fal-ai/minimax/video-01': { kind: 'none' },
+  'fal-ai/hunyuan-video-v1.5/text-to-video': { kind: 'none' },
+})
+
+export function getFalVideoDurationOptions<TModel extends string>(
+  model: TModel,
+): DurationOptions<FalModelVideoDuration<TModel>> {
+  const entry = (FAL_VIDEO_DURATIONS as Record<string, unknown>)[model]
+  // The map is keyed by literal ids but the adapter's TModel is an open string;
+  // the lookup result can't be correlated by TS, hence the one cast here.
+  return (entry ?? { kind: 'none' }) as DurationOptions<
+    FalModelVideoDuration<TModel>
+  >
+}