feat(ai-grok): add duration range options to grok video adapter

Replace the throwing `validateVideoDuration` with the standard duration-options
mechanism. Both grok-imagine video models declare a continuous 1–15 integer-
second range via a `GROK_VIDEO_DURATIONS` table, and the adapter overrides
`availableDurations()` / `snapDuration()` (backed by the shared
`snapToDurationOption` helper) so consumers can discover and pre-snap durations.

`createVideoJob` now snaps the requested duration into range (clamp + round)
instead of rejecting it, and the snapped value is spread after `...modelOptions`
so it is authoritative. Adds the per-model `GrokVideoModelDurationByName`
generic, narrows the `createVideoJob` signature to carry the size/duration type
params, exports the new helpers/type, and documents the range in the media docs.

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

Author: tombeckenham

docs/media/video-generation.md

@@ -597,6 +597,16 @@ const { jobId } = await generateVideo({
 })
 ```
 
+Both models accept any whole second in the **1–15** range. A raw `duration` is coerced into that range rather than rejected — values are clamped to `[1, 15]` and rounded to the nearest second. Inspect or pre-snap the range the same way as Veo:
+
+```typescript
+const adapter = grokVideo('grok-imagine-video')
+
+adapter.availableDurations() // { kind: 'range', min: 1, max: 15, step: 1, unit: 'seconds' }
+adapter.snapDuration(2.5) // 3 — clamped/rounded into range
+adapter.snapDuration(99) // 15
+```
+
 Generated clips include an audio track. When the job completes, the adapter reports `usage.unitsBilled` (billed seconds of video) and `usage.cost` (exact USD cost as returned by the API) on the result.
 
 ## Response Types

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

@@ -1,13 +1,14 @@
 import { resolveMediaPrompt } from '@tanstack/ai'
-import { BaseVideoAdapter } from '@tanstack/ai/adapters'
+import { BaseVideoAdapter, snapToDurationOption } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
 import {
+  getGrokVideoDurationOptions,
   isImageToVideoOnlyModel,
   parseGrokVideoSize,
-  validateVideoDuration,
   validateVideoSize,
 } from '../video/video-provider-options'
+import type { DurationOptions } from '@tanstack/ai/adapters'
 import type {
   ImagePart,
   MediaInputMetadata,
@@ -19,6 +20,7 @@ import type {
 } from '@tanstack/ai'
 import type { GrokVideoModel } from '../model-meta'
 import type {
+  GrokVideoModelDurationByName,
   GrokVideoModelInputModalitiesByName,
   GrokVideoModelProviderOptionsByName,
   GrokVideoModelSizeByName,
@@ -116,7 +118,8 @@ export class GrokVideoAdapter<
   GrokVideoProviderOptions,
   GrokVideoModelProviderOptionsByName,
   GrokVideoModelSizeByName,
-  GrokVideoModelInputModalitiesByName
+  GrokVideoModelInputModalitiesByName,
+  GrokVideoModelDurationByName
 > {
   readonly name = 'grok' as const
 
@@ -170,14 +173,23 @@ export class GrokVideoAdapter<
   }
 
   async createVideoJob(
-    options: VideoGenerationOptions<GrokVideoProviderOptions>,
+    options: VideoGenerationOptions<
+      GrokVideoProviderOptions,
+      GrokVideoModelSizeByName[TModel],
+      GrokVideoModelDurationByName[TModel]
+    >,
   ): Promise<VideoJobResult> {
     const { model, size, modelOptions, logger } = options
 
     validateVideoSize(model, size)
-    validateVideoDuration(model, options.duration)
-    validateVideoDuration(model, modelOptions?.duration)
-    const duration = options.duration ?? modelOptions?.duration
+
+    // Coerce the requested duration into the model's valid range (1–15s,
+    // integer) instead of rejecting it — `snapDuration` clamps and rounds.
+    // modelOptions wins over the generic `duration`, mirroring the size
+    // precedence below.
+    const rawDuration = modelOptions?.duration ?? options.duration
+    const duration =
+      rawDuration !== undefined ? this.snapDuration(rawDuration) : undefined
 
     // The interleaved prompt decomposes into verbatim text plus typed media
     // buckets. The Imagine video endpoint takes a text prompt and an optional
@@ -227,8 +239,10 @@ export class GrokVideoAdapter<
           resolution: parsedSize.resolution,
         }),
       }),
-      ...(duration !== undefined && { duration }),
       ...modelOptions,
+      // Spread after modelOptions so the snapped duration is authoritative
+      // (modelOptions.duration is folded into `duration` via snapDuration above).
+      ...(duration !== undefined && { duration }),
     }
 
     try {
@@ -352,6 +366,26 @@ export class GrokVideoAdapter<
         return 'processing'
     }
   }
+
+  /**
+   * Both grok-imagine video models accept a continuous 1–15 integer-second
+   * range. Consumers can use this to render UI without provider knowledge.
+   */
+  override availableDurations(): DurationOptions<
+    GrokVideoModelDurationByName[TModel]
+  > {
+    return getGrokVideoDurationOptions(this.model)
+  }
+
+  /**
+   * Coerce a raw seconds value to the closest valid duration (clamped to
+   * [1, 15] and rounded to whole seconds).
+   */
+  override snapDuration(
+    seconds: number,
+  ): GrokVideoModelDurationByName[TModel] | undefined {
+    return snapToDurationOption(seconds, this.availableDurations())
+  }
 }
 
 /**

packages/ai-grok/src/index.ts

@@ -38,10 +38,15 @@ export {
   grokVideo,
   type GrokVideoConfig,
 } from './adapters/video'
+export {
+  GROK_VIDEO_DURATIONS,
+  getGrokVideoDurationOptions,
+} from './video/video-provider-options'
 export type {
   GrokVideoProviderOptions,
   GrokVideoModelProviderOptionsByName,
   GrokVideoModelSizeByName,
+  GrokVideoModelDurationByName,
   GrokVideoAspectRatio,
   GrokVideoResolution,
   GrokVideoSize,

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

@@ -6,6 +6,9 @@
  * @experimental Video generation is an experimental feature and may change.
  */
 
+import type { DurationOptions } from '@tanstack/ai/adapters'
+import type { GrokVideoModel } from '../model-meta'
+
 /**
  * Aspect ratios accepted by the grok-imagine video models.
  *
@@ -107,23 +110,55 @@ export function validateVideoSize(
 }
 
 /**
- * Validate video duration (seconds) for a given grok video model.
- * The Imagine API accepts integer durations between 1 and 15 seconds.
+ * Per-model duration type. The Imagine API accepts any integer second in the
+ * 1–15 range, so this is a continuous range expressed as `number` (a literal
+ * union can't represent it). `snapDuration()` coerces a raw seconds value into
+ * the valid range at runtime.
  *
  * @experimental Video generation is an experimental feature and may change.
  */
-export function validateVideoDuration(model: string, duration?: number): void {
-  if (duration === undefined) return
-  if (
-    !Number.isInteger(duration) ||
-    duration < GROK_VIDEO_MIN_DURATION ||
-    duration > GROK_VIDEO_MAX_DURATION
-  ) {
-    throw new Error(
-      `Duration "${duration}" is not supported by model "${model}". ` +
-        `Supported durations: integer seconds between ${GROK_VIDEO_MIN_DURATION} and ${GROK_VIDEO_MAX_DURATION}`,
-    )
-  }
+export type GrokVideoModelDurationByName = {
+  'grok-imagine-video': number
+  'grok-imagine-video-1.5': number
+}
+
+/**
+ * Runtime duration table backing `availableDurations()` / `snapDuration()`.
+ * Both grok-imagine video models accept the same continuous 1–15 integer-second
+ * range.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export const GROK_VIDEO_DURATIONS: {
+  readonly [TModel in GrokVideoModel]: DurationOptions<
+    GrokVideoModelDurationByName[TModel]
+  >
+} = {
+  'grok-imagine-video': {
+    kind: 'range',
+    min: GROK_VIDEO_MIN_DURATION,
+    max: GROK_VIDEO_MAX_DURATION,
+    step: 1,
+    unit: 'seconds',
+  },
+  'grok-imagine-video-1.5': {
+    kind: 'range',
+    min: GROK_VIDEO_MIN_DURATION,
+    max: GROK_VIDEO_MAX_DURATION,
+    step: 1,
+    unit: 'seconds',
+  },
+}
+
+/**
+ * Look up the duration options for a grok video model.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export function getGrokVideoDurationOptions<TModel extends GrokVideoModel>(
+  model: TModel,
+): DurationOptions<GrokVideoModelDurationByName[TModel]> {
+  return GROK_VIDEO_DURATIONS[model]
 }
 
 /**

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

@@ -6,8 +6,8 @@ import {
   grokVideo,
 } from '../src/adapters/video'
 import {
+  getGrokVideoDurationOptions,
   parseGrokVideoSize,
-  validateVideoDuration,
   validateVideoSize,
 } from '../src/video/video-provider-options'
 
@@ -317,6 +317,7 @@ describe('Grok Video Adapter', () => {
         adapter.createVideoJob({
           model: 'grok-imagine-video-1.5',
           prompt: 'p',
+          // @ts-expect-error invalid size is also rejected at compile time
           size: '7:5',
           logger: testLogger,
         }),
@@ -325,36 +326,49 @@ describe('Grok Video Adapter', () => {
         adapter.createVideoJob({
           model: 'grok-imagine-video-1.5',
           prompt: 'p',
+          // @ts-expect-error invalid resolution is also rejected at compile time
           size: '16:9_9k',
           logger: testLogger,
         }),
       ).rejects.toThrow(/Resolution "9k" is not supported/)
       expect(fetchMock).not.toHaveBeenCalled()
     })
 
-    it('rejects out-of-range and non-integer durations before calling the API', async () => {
+    it('snaps out-of-range and non-integer durations into the valid range', async () => {
+      // [requested, snapped]: clamp to [1, 15], round to whole seconds.
+      const cases: Array<[number, number]> = [
+        [0, 1],
+        [16, 15],
+        [2.5, 3],
+        [7, 7],
+      ]
+      for (const [requested, snapped] of cases) {
+        const fetchMock = mockFetch(() => jsonResponse({ request_id: 'r' }))
+        const adapter = adapterWithFetch(fetchMock)
+        await adapter.createVideoJob({
+          model: 'grok-imagine-video-1.5',
+          prompt: i2vPrompt(),
+          duration: requested,
+          logger: testLogger,
+        })
+        const body = JSON.parse(String(fetchMock.mock.calls[0]![1]?.body))
+        expect(body.duration).toBe(snapped)
+      }
+    })
+
+    it('snaps a duration supplied via modelOptions', async () => {
       const fetchMock = mockFetch(() => jsonResponse({ request_id: 'r' }))
       const adapter = adapterWithFetch(fetchMock)
 
-      for (const duration of [0, 16, 2.5]) {
-        await expect(
-          adapter.createVideoJob({
-            model: 'grok-imagine-video-1.5',
-            prompt: 'p',
-            duration,
-            logger: testLogger,
-          }),
-        ).rejects.toThrow(/Duration .* is not supported/)
-      }
-      await expect(
-        adapter.createVideoJob({
-          model: 'grok-imagine-video-1.5',
-          prompt: 'p',
-          modelOptions: { duration: 99 },
-          logger: testLogger,
-        }),
-      ).rejects.toThrow(/Duration "99" is not supported/)
-      expect(fetchMock).not.toHaveBeenCalled()
+      await adapter.createVideoJob({
+        model: 'grok-imagine-video-1.5',
+        prompt: i2vPrompt(),
+        modelOptions: { duration: 99 },
+        logger: testLogger,
+      })
+
+      const body = JSON.parse(String(fetchMock.mock.calls[0]![1]?.body))
+      expect(body.duration).toBe(15)
     })
 
     it('surfaces API error messages from the xAI error body', async () => {
@@ -595,13 +609,36 @@ describe('Grok Video Adapter', () => {
       expect(() => validateVideoSize('m', '16:9_2k')).toThrow(/Resolution/)
     })
 
-    it('validates durations', () => {
-      expect(() => validateVideoDuration('m', undefined)).not.toThrow()
-      expect(() => validateVideoDuration('m', 1)).not.toThrow()
-      expect(() => validateVideoDuration('m', 15)).not.toThrow()
-      expect(() => validateVideoDuration('m', 0)).toThrow(/Duration/)
-      expect(() => validateVideoDuration('m', 16)).toThrow(/Duration/)
-      expect(() => validateVideoDuration('m', 1.5)).toThrow(/Duration/)
+    it('exposes the 1–15s duration range via getGrokVideoDurationOptions', () => {
+      expect(getGrokVideoDurationOptions('grok-imagine-video')).toEqual({
+        kind: 'range',
+        min: 1,
+        max: 15,
+        step: 1,
+        unit: 'seconds',
+      })
+      expect(getGrokVideoDurationOptions('grok-imagine-video-1.5')).toEqual({
+        kind: 'range',
+        min: 1,
+        max: 15,
+        step: 1,
+        unit: 'seconds',
+      })
+    })
+
+    it('availableDurations / snapDuration coerce raw seconds into range', () => {
+      const adapter = createGrokVideo('grok-imagine-video', 'test-api-key')
+      expect(adapter.availableDurations()).toEqual({
+        kind: 'range',
+        min: 1,
+        max: 15,
+        step: 1,
+        unit: 'seconds',
+      })
+      expect(adapter.snapDuration(0)).toBe(1)
+      expect(adapter.snapDuration(16)).toBe(15)
+      expect(adapter.snapDuration(2.5)).toBe(3)
+      expect(adapter.snapDuration(7)).toBe(7)
     })
   })
 })