feat(ai-openrouter): typed per-model durations for video adapter

Wire openRouterVideo onto the shared typed-duration contract (the same one
geminiVideo uses): add the sixth BaseVideoAdapter generic
(OpenRouterVideoModelDurationByName), narrow `duration` per model from the
published `/api/v1/videos/models` metadata, and override availableDurations()
/ snapDuration() (backed by snapToDurationOption). `duration` is now a
compile-time per-model union; the runtime validateVideoDuration backstop stays
for JS callers and unknown-meta models.

- video-provider-options.ts: OpenRouterVideoModelDurationByName +
  getVideoDurationOptions (discrete from meta, none when unknown/empty)
- adapter: 6th generic, createVideoJob narrowed to per-model size/duration,
  availableDurations()/snapDuration() overrides
- export OpenRouterVideoModelDurationByName from index
- tests: 4 introspection cases; existing negative size/duration tests now use
  @ts-expect-error (proves the union rejects them) while still asserting the
  runtime throw
- docs/media/video-generation.md, docs/adapters/openrouter.md, media-generation
  SKILL.md: document snapDuration/availableDurations for OpenRouter; bump
  updatedAt; changeset

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tombeckenham

.changeset/openrouter-video-adapter.md

@@ -2,6 +2,6 @@
 '@tanstack/ai-openrouter': minor
 ---
 
-Add `openRouterVideo`, a video generation adapter for OpenRouter's dedicated async API (`POST /api/v1/videos`) — Seedance, Veo 3.1, Wan, Kling, and Sora 2 Pro through one API key. Follows the jobs/polling architecture (`generateVideo()` → `getVideoJobStatus()`), with per-model `size` / `duration` / provider-option types generated from OpenRouter's `GET /api/v1/videos/models` metadata and validated before submit. Image-conditioned prompts map `metadata.role` onto the wire: `start_frame` / `end_frame` → `frame_images[]` (`first_frame` / `last_frame`), `reference` / `character` → `input_references[]`; frame roles are validated against each model's `supported_frame_images`. Completed videos are downloaded server-side and returned as `data:` URLs (OpenRouter's download URLs require the API key), and the gateway-reported cost is surfaced as `usage.cost`.
+Add `openRouterVideo`, a video generation adapter for OpenRouter's dedicated async API (`POST /api/v1/videos`) — Seedance, Veo 3.1, Wan, Kling, and Sora 2 Pro through one API key. Follows the jobs/polling architecture (`generateVideo()` → `getVideoJobStatus()`), with per-model `size` / `duration` / provider-option types generated from OpenRouter's `GET /api/v1/videos/models` metadata and validated before submit. `duration` is typed per model on the shared typed-duration contract — the adapter implements `availableDurations()` and `snapDuration(seconds)` (matching the Veo adapter) to enumerate the valid set and coerce raw UI seconds to the closest supported value. Image-conditioned prompts map `metadata.role` onto the wire: `start_frame` / `end_frame` → `frame_images[]` (`first_frame` / `last_frame`), `reference` / `character` → `input_references[]`; frame roles are validated against each model's `supported_frame_images`. Completed videos are downloaded server-side and returned as `data:` URLs (OpenRouter's download URLs require the API key), and the gateway-reported cost is surfaced as `usage.cost`.
 
 Image adapter fixes from the #624 review: requested `size` is now validated (the `WIDTHxHEIGHT` union previously used a Unicode `×`, so every size except `1024x1024` silently dropped its aspect ratio; unsupported sizes now throw with the supported list), `numberOfImages > 1` throws instead of silently returning one image (verified live: the gateway ignores all count keys in `image_config`), and `image_config.strength` (0.0–1.0 image-to-image influence) is exposed via `modelOptions.strength`.

docs/adapters/openrouter.md

@@ -334,6 +334,8 @@ const { jobId } = await generateVideo({
     },
   ],
   size: "1280x720",
+  // `duration` is typed per model from the published metadata; coerce raw
+  // seconds with adapter.snapDuration() or enumerate via adapter.availableDurations().
   duration: 8,
 });
 

docs/media/video-generation.md

@@ -807,6 +807,25 @@ const { jobId } = await generateVideo({
 })
 ```
 
+Like the Veo adapter, OpenRouter's `duration` is **typed per model** — each
+model narrows `duration` to the whole-second union published in its metadata,
+and the adapter implements the same `availableDurations()` / `snapDuration()`
+introspection helpers:
+
+```typescript
+const adapter = openRouterVideo('bytedance/seedance-2.0')
+
+adapter.availableDurations()
+// { kind: 'discrete', values: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] }
+adapter.snapDuration(7.4) // 7 — closest valid duration
+
+await generateVideo({
+  adapter,
+  prompt: 'A timelapse of clouds',
+  duration: adapter.snapDuration(sliderSeconds), // coerce raw UI seconds
+})
+```
+
 Two OpenRouter-specific behaviors to know about:
 
 - **The completed video arrives as a `data:` URL.** OpenRouter's download

packages/ai-openrouter/src/adapters/video.ts

@@ -1,15 +1,18 @@
 import { OpenRouter } from '@openrouter/sdk'
 import { buildBaseUsage, resolveMediaPrompt } from '@tanstack/ai'
-import { BaseVideoAdapter } from '@tanstack/ai/adapters'
+import { BaseVideoAdapter, snapToDurationOption } from '@tanstack/ai/adapters'
 import { arrayBufferToBase64 } from '@tanstack/ai-utils'
 import { getOpenRouterApiKeyFromEnv } from '../utils'
 import {
+  getVideoDurationOptions,
   getVideoModelMeta,
   validateVideoDuration,
   validateVideoSize,
 } from '../video/video-provider-options'
+import type { DurationOptions } from '@tanstack/ai/adapters'
 import type {
   OpenRouterVideoModel,
+  OpenRouterVideoModelDurationByName,
   OpenRouterVideoModelInputModalitiesByName,
   OpenRouterVideoModelProviderOptionsByName,
   OpenRouterVideoModelSizeByName,
@@ -235,7 +238,8 @@ export class OpenRouterVideoAdapter<
   OpenRouterVideoProviderOptions,
   OpenRouterVideoModelProviderOptionsByName,
   OpenRouterVideoModelSizeByName,
-  OpenRouterVideoModelInputModalitiesByName
+  OpenRouterVideoModelInputModalitiesByName,
+  OpenRouterVideoModelDurationByName
 > {
   override readonly kind = 'video' as const
   readonly name = 'openrouter' as const
@@ -254,7 +258,11 @@ export class OpenRouterVideoAdapter<
   }
 
   async createVideoJob(
-    options: VideoGenerationOptions<OpenRouterVideoProviderOptions>,
+    options: VideoGenerationOptions<
+      OpenRouterVideoProviderOptions,
+      OpenRouterVideoModelSizeByName[TModel],
+      OpenRouterVideoModelDurationByName[TModel]
+    >,
   ): Promise<VideoJobResult> {
     const { size, duration, modelOptions, logger } = options
 
@@ -319,6 +327,18 @@ export class OpenRouterVideoAdapter<
     }
   }
 
+  override availableDurations(): DurationOptions<
+    OpenRouterVideoModelDurationByName[TModel]
+  > {
+    return getVideoDurationOptions(this.model)
+  }
+
+  override snapDuration(
+    seconds: number,
+  ): OpenRouterVideoModelDurationByName[TModel] | undefined {
+    return snapToDurationOption(seconds, this.availableDurations())
+  }
+
   async getVideoStatus(jobId: string): Promise<VideoStatusResult> {
     const response = await this.client.videoGeneration.getGeneration({ jobId })
     return {

packages/ai-openrouter/src/index.ts

@@ -68,6 +68,7 @@ export type {
   OpenRouterVideoModelProviderOptionsByName,
   OpenRouterVideoModelSizeByName,
   OpenRouterVideoModelInputModalitiesByName,
+  OpenRouterVideoModelDurationByName,
 } from './video/video-provider-options'
 
 // ============================================================================

packages/ai-openrouter/src/video/video-provider-options.ts

@@ -1,4 +1,5 @@
 import { OPENROUTER_VIDEO_MODEL_META } from '../model-meta'
+import type { DurationOptions } from '@tanstack/ai/adapters'
 import type { VideoGenerationRequestProvider } from '@openrouter/sdk/models'
 import type { OPENROUTER_VIDEO_MODELS } from '../model-meta'
 
@@ -123,6 +124,35 @@ export type OpenRouterVideoModelInputModalitiesByName = {
   [K in OpenRouterVideoModel]: readonly ['image']
 }
 
+/**
+ * Per-model duration unions (whole seconds, numeric — OpenRouter's
+ * `/api/v1/videos` `duration` field is a number). Derived from the generated
+ * model meta; models whose metadata reports `durations: null` (capabilities
+ * unknown) stay permissive (`number`).
+ */
+export type OpenRouterVideoModelDurationByName = {
+  [K in OpenRouterVideoModel]: ElementOf<VideoMeta[K]['durations'], number>
+}
+
+/**
+ * Duration options for a model, backing the adapter's `availableDurations()` /
+ * `snapDuration()`. OpenRouter publishes durations as a discrete list of whole
+ * seconds, so known models map to `{ kind: 'discrete' }`. Returns
+ * `{ kind: 'none' }` when the model is unknown or its meta reports no
+ * durations — mirroring the permissive runtime behavior of
+ * {@link validateVideoDuration}.
+ */
+export function getVideoDurationOptions<TModel extends OpenRouterVideoModel>(
+  model: TModel,
+): DurationOptions<OpenRouterVideoModelDurationByName[TModel]>
+export function getVideoDurationOptions(
+  model: string,
+): DurationOptions<number> {
+  const durations = VIDEO_MODEL_META[model]?.durations
+  if (!durations || durations.length === 0) return { kind: 'none' }
+  return { kind: 'discrete', values: durations }
+}
+
 /**
  * Validate a requested size against the model's supported sizes. No-op when
  * the model (or its size list) is unknown — OpenRouter then validates

packages/ai-openrouter/tests/video-adapter.test.ts

@@ -117,6 +117,8 @@ describe('OpenRouter Video Adapter', () => {
         adapter.createVideoJob({
           model: 'bytedance/seedance-2.0',
           prompt: 'A timelapse of clouds',
+          // @ts-expect-error invalid size — the per-model union rejects it at
+          // compile time; this still exercises the runtime guard for JS callers.
           size: '333x333',
           logger: testLogger,
         }),
@@ -132,6 +134,8 @@ describe('OpenRouter Video Adapter', () => {
         adapter.createVideoJob({
           model: 'bytedance/seedance-2.0',
           prompt: 'A timelapse of clouds',
+          // @ts-expect-error invalid duration — the per-model union rejects it
+          // at compile time; this still exercises the runtime guard.
           duration: 99,
           logger: testLogger,
         }),
@@ -485,4 +489,33 @@ describe('OpenRouter Video Adapter', () => {
       expect(mockFetch).not.toHaveBeenCalled()
     })
   })
+
+  describe('typed durations', () => {
+    it('availableDurations() reports the model discrete duration list', () => {
+      const adapter = createAdapter() // bytedance/seedance-2.0 → [4..15]
+      expect(adapter.availableDurations()).toEqual({
+        kind: 'discrete',
+        values: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+      })
+    })
+
+    it('snapDuration() returns an exact match unchanged', () => {
+      const adapter = createAdapter()
+      expect(adapter.snapDuration(8)).toBe(8)
+    })
+
+    it('snapDuration() snaps to the closest supported value', () => {
+      const adapter = createAdapter()
+      // 7.4 → 7 (rounds to nearest), 99 → 15 (clamped to max), 1 → 4 (min)
+      expect(adapter.snapDuration(7.4)).toBe(7)
+      expect(adapter.snapDuration(99)).toBe(15)
+      expect(adapter.snapDuration(1)).toBe(4)
+    })
+
+    it('snapDuration() picks the nearest of a sparse list', () => {
+      const adapter = createOpenRouterVideo('alibaba/wan-2.6', 'test-key') // [5, 10]
+      expect(adapter.snapDuration(6)).toBe(5)
+      expect(adapter.snapDuration(8)).toBe(10)
+    })
+  })
 })

packages/ai/skills/ai-core/media-generation/SKILL.md

@@ -4,9 +4,10 @@ description: >
   Image, audio, video, speech (TTS), and transcription generation using
   activity-specific adapters: generateImage() with openaiImage/geminiImage/byteplusImage,
   generateAudio() with geminiAudio/falAudio, generateVideo() with async
-  polling (openaiVideo/geminiVideo/grokVideo/falVideo/byteplusVideo, per-model typed
-  durations), generateSpeech() with openaiSpeech/byteplusSpeech, generateTranscription()
-  with openaiTranscription/byteplusTranscription. React hooks: useGenerateImage, useGenerateAudio,
+  polling (openaiVideo/geminiVideo/grokVideo/falVideo/byteplusVideo/openRouterVideo,
+  per-model typed durations), generateSpeech() with openaiSpeech/byteplusSpeech,
+  generateTranscription() with openaiTranscription/byteplusTranscription. React hooks:
+  useGenerateImage, useGenerateAudio,
   useGenerateSpeech, useTranscription, useGenerateVideo.
   TanStack Start server function integration with toServerSentEventsResponse.
 type: sub-skill
@@ -547,8 +548,9 @@ image-to-video only — needs an `image` prompt part as the starting frame, text
 aspect-ratio size template like `'16:9_720p'`, integer durations 1-15s, reports
 `usage.unitsBilled` seconds and exact `usage.cost`), `byteplusVideo(...)` (Seedance —
 aspect-ratio size template like `'16:9_720p'`, durations 4-15s on the 2.0 family,
-4-12s on 1.5-pro, 2-12s on the 1.0-pro models; reads `ARK_API_KEY`), and
-`falVideo(...)` (hosted models, see cost tracking below).
+4-12s on 1.5-pro, 2-12s on the 1.0-pro models; reads `ARK_API_KEY`),
+`openRouterVideo(...)` (OpenRouter's dedicated `POST /api/v1/videos` gateway),
+and `falVideo(...)` (hosted models, see cost tracking below).
 
 > **Seedance option applicability is per model and enforced server-side** —
 > Ark returns a 400 for an inapplicable field rather than ignoring it.
@@ -560,6 +562,28 @@ aspect-ratio size template like `'16:9_720p'`, durations 4-15s on the 2.0 family
 > days). Seedance is also reachable via `falVideo` — `byteplusVideo` is the
 > direct-to-BytePlus path.
 
+OpenRouter (`@tanstack/ai-openrouter`, `openRouterVideo`) runs the dedicated
+async video API (`POST /api/v1/videos`) and shares the same typed-duration
+contract — `duration`, `size`, and provider options are narrowed per model
+from OpenRouter's published metadata, with the same `availableDurations()` /
+`snapDuration()` helpers:
+
+```typescript
+import { openRouterVideo } from '@tanstack/ai-openrouter'
+
+const adapter = openRouterVideo('bytedance/seedance-2.0')
+adapter.availableDurations()
+// { kind: 'discrete', values: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] }
+adapter.snapDuration(7.4) // 7
+
+const { jobId } = await generateVideo({
+  adapter,
+  prompt: 'A timelapse of clouds',
+  duration: adapter.snapDuration(sliderSeconds),
+})
+// Completed url is a data: URL; usage.cost carries the real billed cost.
+```
+
 Client hook with job tracking:
 
 ```tsx