feat(ai-fal): per-model typed durations for video generation

.changeset/fal-typed-video-duration.md

@@ -0,0 +1,14 @@
+---
+'@tanstack/ai-fal': minor
+---
+
+Add per-model typed durations for fal video generation.
+
+`generateVideo({ duration })` is now typed from `@fal-ai/client`'s
+`EndpointTypeMap` for the selected model (e.g. `'5' | '10'` on Kling,
+`'4s' | '6s' | '8s'` on Veo 3.1). Popular models also implement
+`availableDurations()` / `snapDuration()`.
+
+**Breaking:** callers passing `duration: <number>` to fal video models must
+either pass the model's duration union directly or call
+`adapter.snapDuration(seconds)`.

docs/adapters/fal.md

@@ -160,7 +160,7 @@ size: "landscape_16_9"
 
 ## Video Generation (Experimental)
 
-> **Note:** Video generation is an experimental feature and may change in future releases. In particular, this version of the adapter does not map the duration paramater
+> **Note:** Video generation is an experimental feature and may change in future releases.
 
 Video generation uses a queue-based workflow: submit a job, poll for status, then retrieve the video URL when complete.
 
@@ -184,9 +184,7 @@ const job = await generateVideo({
   adapter,
   prompt: "A timelapse of a flower blooming",
   size: "16:9",
-  modelOptions: {
-    duration: "5",
-  },
+  duration: "5",
 });
 
 // 2. Poll for status
@@ -207,14 +205,45 @@ import { falVideo } from "@tanstack/ai-fal";
 const job = await generateVideo({
   adapter: falVideo("fal-ai/kling-video/v2.6/pro/image-to-video"),
   prompt: "Animate this scene with gentle wind",
+  duration: "5",
   modelOptions: {
     start_image_url: "https://example.com/image.jpg",
     generate_audio: true,
-    duration: "5",
   },
 });
 ```
 
+`duration` is typed per model from `@fal-ai/client`'s `EndpointTypeMap`. Popular models also implement `availableDurations()` / `snapDuration()` for UI sliders:
+
+| Model | `duration` type | `availableDurations()` |
+| --- | --- | --- |
+| `fal-ai/kling-video/v1.6/{standard,pro}/text-to-video`, `fal-ai/kling-video/v2.6/pro/{text,image}-to-video` | `'5' \| '10'` | discrete |
+| `fal-ai/kling-video/v3/pro/{text,image}-to-video` | `'3'` … `'15'` | discrete |
+| `fal-ai/pika/v2.2/text-to-video` | `'5' \| '10'` | discrete |
+| `fal-ai/ltx-2.3/{text,image}-to-video` (+ `/fast`) | `'6' \| '8' \| '10'` | discrete |
+| `fal-ai/luma-dream-machine/ray-2` | `'5s' \| '9s'` | discrete |
+| `fal-ai/veo3.1`, `fal-ai/veo3.1/fast` (+ `/image-to-video`), `fal-ai/veo3` (+ `/image-to-video`) | `'4s' \| '6s' \| '8s'` | discrete |
+| `fal-ai/wan-25-preview/text-to-video` | `'2'` … `'15'` | discrete |
+| `fal-ai/minimax/video-01` | not accepted | `{ kind: 'none' }` |
+| `fal-ai/hunyuan-video-v1.5/text-to-video` | not accepted (`num_frames`) | `{ kind: 'none' }` |
+
+```typescript
+import { generateVideo } from "@tanstack/ai";
+import { falVideo } from "@tanstack/ai-fal";
+
+const adapter = falVideo("fal-ai/veo3.1");
+adapter.availableDurations(); // { kind: 'discrete', values: ['4s', '6s', '8s'] }
+adapter.snapDuration(7); // '6s'
+
+await generateVideo({
+  adapter,
+  prompt: "A timelapse of a city skyline at dusk",
+  duration: adapter.snapDuration(7),
+});
+```
+
+Uncurated models still type `duration` from the SDK when the endpoint declares the field, but `availableDurations()` returns `{ kind: 'none' }` until they are added to the runtime map.
+
 ## Text-to-Speech
 
 Text-to-speech uses `falSpeech()` with the `generateSpeech()` activity. The adapter fetches the generated audio from fal's CDN and returns it as base64-encoded data to match the `TTSResult` contract.

docs/config.json

@@ -478,7 +478,7 @@
           "label": "Video Generation",
           "to": "media/video-generation",
           "addedAt": "2026-04-15",
-          "updatedAt": "2026-08-19"
+          "updatedAt": "2026-08-20"
         },
         {
           "label": "Generation Hooks",
@@ -878,7 +878,8 @@
         {
           "label": "fal.ai",
           "to": "adapters/fal",
-          "addedAt": "2026-04-15"
+          "addedAt": "2026-04-15",
+          "updatedAt": "2026-08-20"
         },
         {
           "label": "OpenRouter Adapter",

docs/media/video-generation.md

@@ -600,6 +600,8 @@ await generateVideo({
 Adapters that haven't declared a per-model duration map keep the plain
 `duration?: number` typing, return `{ kind: 'none' }` from
 `availableDurations()`, and return `undefined` from `snapDuration()`.
+fal is the exception: `duration` is typed from `@fal-ai/client`'s
+`EndpointTypeMap` even when the runtime map has no entry.
 
 > **Note:** The video URL returned for Veo jobs is served by the Gemini
 > Files API and requires your API key to download (send it as an
@@ -888,6 +890,29 @@ Two OpenRouter-specific behaviors to know about:
 - **Cost is reported on completion.** The gateway reports the real billed
   cost for the job; it's surfaced as `usage.cost` on the completed result.
 
+#### fal.ai Model Options
+
+`duration` is typed per endpoint from `@fal-ai/client`. Popular models also
+implement `availableDurations()` / `snapDuration()` (Kling 2.6/Pika `'5' | '10'`,
+Kling 3 `'3'`…`'15'`, Luma `'5s' | '9s'`, Veo 3.1 `'4s' | '6s' | '8s'`, WAN
+`'2'`…`'15'`). Models with no duration field (Minimax, Hunyuan) type `duration`
+as `undefined`, so passing one is a compile error. See the
+[fal adapter](../adapters/fal) for the full table.
+
+```typescript ignore
+import { generateVideo } from '@tanstack/ai'
+import { falVideo } from '@tanstack/ai-fal'
+
+const adapter = falVideo('fal-ai/veo3.1')
+adapter.availableDurations() // { kind: 'discrete', values: ['4s', '6s', '8s'] }
+
+await generateVideo({
+  adapter,
+  prompt: 'A timelapse of a city skyline at dusk',
+  duration: adapter.snapDuration(7), // '6s'
+})
+```
+
 ### Response Types
 
 > **Note:** The interfaces below are the underlying adapter-level types. The `getVideoJobStatus()` helper returns a single merged object, `{ status, progress?, url?, error?, usage? }` — it does not return `jobId` or `expiresAt`.

examples/ts-react-media/src/lib/server-functions.ts

@@ -296,32 +296,31 @@ function videoStreamForModel(data: VideoRequest): AsyncIterable<StreamChunk> {
   // Image-to-video models receive the start frame as a prompt part
   // (role: 'start_frame') — the fal adapter routes it to the endpoint's
   // start-image field. Text-to-video models take the text prompt only.
+  // `duration` is typed per endpoint ('5' | '10' on Kling 2.6, '3'…'15' on
+  // Kling 3, '4s' | '6s' | '8s' on Veo 3.1); `snapDuration(seconds)` picks the
+  // nearest supported value so a UI slider never has to know the literal.
   switch (data.model) {
     // Text-to-video models
     case 'fal-ai/kling-video/v3/pro/text-to-video': {
+      const adapter = falVideo('fal-ai/kling-video/v3/pro/text-to-video')
       return generateVideo({
         stream: true,
         pollingInterval: VIDEO_POLL_INTERVAL_MS,
-        adapter: falVideo('fal-ai/kling-video/v3/pro/text-to-video'),
+        adapter,
         prompt: asTextPrompt(data.prompt),
         size: '16:9',
-        modelOptions: {
-          duration: '5',
-        },
+        duration: adapter.snapDuration(5),
       })
     }
     case 'fal-ai/veo3.1': {
-      // NOTE pass aspect ratio, resolution, and duration in model options
-      // This makes use of existing types and avoids type errors
+      const adapter = falVideo('fal-ai/veo3.1')
       return generateVideo({
         stream: true,
         pollingInterval: VIDEO_POLL_INTERVAL_MS,
-        adapter: falVideo('fal-ai/veo3.1'),
+        adapter,
         prompt: asTextPrompt(data.prompt),
         size: '16:9_1080p',
-        modelOptions: {
-          duration: '4s',
-        },
+        duration: adapter.snapDuration(4),
       })
     }
     case 'xai/grok-imagine-video/text-to-video': {
@@ -331,9 +330,7 @@ function videoStreamForModel(data: VideoRequest): AsyncIterable<StreamChunk> {
         adapter: falVideo('xai/grok-imagine-video/text-to-video'),
         prompt: asTextPrompt(data.prompt),
         size: '16:9_720p',
-        modelOptions: {
-          duration: 5,
-        },
+        duration: 5,
       })
     }
     case 'grok-imagine-video': {
@@ -378,37 +375,39 @@ function videoStreamForModel(data: VideoRequest): AsyncIterable<StreamChunk> {
       })
     }
     case 'fal-ai/ltx-2.3/text-to-video/fast': {
+      const adapter = falVideo('fal-ai/ltx-2.3/text-to-video/fast')
       return generateVideo({
         stream: true,
         pollingInterval: VIDEO_POLL_INTERVAL_MS,
-        adapter: falVideo('fal-ai/ltx-2.3/text-to-video/fast'),
+        adapter,
         prompt: asTextPrompt(data.prompt),
         size: '16:9_2160p',
+        duration: adapter.snapDuration(6),
       })
     }
     // Image-to-video models
     case 'fal-ai/kling-video/v3/pro/image-to-video': {
+      const adapter = falVideo('fal-ai/kling-video/v3/pro/image-to-video')
       return generateVideo({
         stream: true,
         pollingInterval: VIDEO_POLL_INTERVAL_MS,
-        adapter: falVideo('fal-ai/kling-video/v3/pro/image-to-video'),
+        adapter,
         prompt: asImageToVideoPrompt(data.prompt),
+        duration: adapter.snapDuration(5),
         modelOptions: {
           generate_audio: true,
-          duration: '5',
         },
       })
     }
     case 'fal-ai/veo3.1/image-to-video': {
+      const adapter = falVideo('fal-ai/veo3.1/image-to-video')
       return generateVideo({
         stream: true,
         pollingInterval: VIDEO_POLL_INTERVAL_MS,
-        adapter: falVideo('fal-ai/veo3.1/image-to-video'),
+        adapter,
         prompt: asImageToVideoPrompt(data.prompt),
         size: '16:9_1080p',
-        modelOptions: {
-          duration: '4s',
-        },
+        duration: adapter.snapDuration(4),
       })
     }
     case 'xai/grok-imagine-video/image-to-video': {
@@ -418,9 +417,7 @@ function videoStreamForModel(data: VideoRequest): AsyncIterable<StreamChunk> {
         adapter: falVideo('xai/grok-imagine-video/image-to-video'),
         prompt: asImageToVideoPrompt(data.prompt),
         size: '16:9_720p',
-        modelOptions: {
-          duration: 5,
-        },
+        duration: 5,
       })
     }
     case 'grok-imagine-video-1.5/image-to-video': {
@@ -437,12 +434,14 @@ function videoStreamForModel(data: VideoRequest): AsyncIterable<StreamChunk> {
       })
     }
     case 'fal-ai/ltx-2.3/image-to-video/fast': {
+      const adapter = falVideo('fal-ai/ltx-2.3/image-to-video/fast')
       return generateVideo({
         stream: true,
         pollingInterval: VIDEO_POLL_INTERVAL_MS,
-        adapter: falVideo('fal-ai/ltx-2.3/image-to-video/fast'),
+        adapter,
         prompt: asImageToVideoPrompt(data.prompt),
         size: '16:9_2160p',
+        duration: adapter.snapDuration(6),
       })
     }
     // Gemini Omni Flash (Interactions API, GEMINI_API_KEY). One model
@@ -485,11 +484,10 @@ function videoStreamForModel(data: VideoRequest): AsyncIterable<StreamChunk> {
           : {}),
       })
     }
-    // OpenRouter's dedicated async video API (`POST /api/v1/videos`). Unlike
-    // fal (which takes duration in `modelOptions`), OpenRouter types the
-    // top-level `duration` per model from its published metadata, and the
-    // adapter exposes `snapDuration()` to coerce a raw UI seconds value to
-    // the model's nearest supported duration.
+    // OpenRouter's dedicated async video API (`POST /api/v1/videos`). Like
+    // fal, it types the top-level `duration` per model and exposes
+    // `snapDuration()` to coerce a raw UI seconds value to the model's
+    // nearest supported duration.
     case 'bytedance/seedance-2.0': {
       const adapter = openRouterVideo('bytedance/seedance-2.0')
       return generateVideo({

packages/ai-fal/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,

packages/ai-fal/src/index.ts

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